Imported from younggis/gis-read (
AGENTS.md). Install upstream withnpx skills add younggis/gis-read. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
This is a TypeScript GIS parser/converter CLI. Source code lives in src/: cli.ts defines the gis command, shared types and utilities are in types.ts, io.ts, crs.ts, encoding.ts, and format detection is in format-detect.ts. Format implementations live under src/parsers/, with one parser per GIS format plus index.ts as the parser facade. Tests live in test/; sample datasets used by tests and manual CLI checks live in data/. Build output is written to dist/ and should not be edited directly.
Build, Test, and Development Commands
npm install: install runtime and development dependencies.npm run dev -- <command>: run the CLI from TypeScript viats-node, for examplenpm run dev -- detect data/lakes.geojson.npm run build: compile TypeScript todist/with declarations and source maps.npm start -- <command>: run the built CLI fromdist/cli.js.npm test: run alltest/*.test.tsfiles with Node's built-in test runner andtsx.npm run lint: runtsc --noEmitfor type-checking without generating files.
Coding Style & Naming Conventions
Use ES modules and explicit .js extensions in local imports, matching the existing TypeScript setup. Keep strict typing: avoid implicit any, prefer exported interfaces from src/types.ts, and keep parser return values normalized to ParseResult. Use two-space indentation, single quotes, semicolons, and descriptive camelCase names for functions and variables. Parser files should be named after their format, such as geojson.ts or shapefile.ts.
Testing Guidelines
Tests use node:test and node:assert/strict. Add tests under test/ with the *.test.ts suffix. Parser tests should cover format detection, feature counts, representative geometry types, metadata/CRS handling, and round-trip writers when available. Reuse data/ fixtures when possible; if new fixtures are large, document why they are needed.
Change Synchronization
When adding, changing, or removing functionality, update all affected project surfaces in the same change. This includes automated tests under test/, the Chinese operation manual 操作手册.md, the English README README.md, and the Chinese README read.md. For CLI behavior changes, document the new or changed command examples in both README files and the operation manual. For parser, writer, CRS, encoding, or streaming changes, add or adjust tests that prove the behavior and update the relevant support matrix, limitations, or troubleshooting notes. Do not leave documentation saying an old behavior still exists after the code has changed.
Commit & Pull Request Guidelines
No repository-specific git history is available in this checkout. Use concise, imperative commit subjects such as Add GPX parser tests or Fix KML coordinate parsing. Pull requests should describe the changed formats or CLI behavior, list validation commands run (npm test, npm run lint, npm run build), and include sample CLI input/output when user-visible behavior changes.
Security & Configuration Tips
Do not commit generated dist/, logs, .env, or output/ files. Treat GIS inputs as untrusted: validate file formats, keep error messages actionable, and avoid loading very large files into memory when a streaming path exists.
