Skip to content

AGENTS.md

Latest commit

 

History

History
25 lines (18 loc) · 2.37 KB

AGENTS.md

File metadata and controls

25 lines (18 loc) · 2.37 KB

Repository Guidelines

Project Structure & Module Organization

src/cli/main.ts is the CLI entrypoint. Core logic lives in src/core/ and is split by responsibility: artifact resolution, Maven/POM inspection, source fetching, IDL parsing, indexing, and query execution. Tests live in test/ and use fixtures under test/fixtures/ for .proto, .thrift, and Maven POM scenarios. Build output goes to dist/ and should be treated as generated code.

Build, Test, and Development Commands

  • npm run dev -- --help runs the CLI directly through tsx without a build.
  • npm run build compiles TypeScript to dist/.
  • npm run check type-checks both production and test configs.
  • npm test runs the Node test runner against test/*.test.ts.
  • npm run pack:cli builds and creates the npm package tarball.

Use npm ci for a clean install in CI-like environments. The release workflow in .github/workflows/package.yml also runs check, test, and build on Node 22.

Coding Style & Naming Conventions

Use TypeScript with strict typing and ESM conventions. Follow the existing style: 2-space indentation, double quotes, semicolons, and relative imports ending in .js from TS source files. Prefer small focused modules in src/core/. Use camelCase for variables/functions, PascalCase for types/classes, and descriptive filenames such as project-inspector.ts or proto-parser.test.ts.

Testing Guidelines

Add or update tests for every behavior change. Keep test files in test/ with the *.test.ts suffix used by the current runner. Favor fixture-backed tests when parsing Maven, Proto, or Thrift inputs; add new sample files under test/fixtures/<domain>/ as needed. Run npm run check && npm test before opening a PR.

Commit & Pull Request Guidelines

Recent history uses short imperative subjects like fix .proto gaps and add fixes. Keep commit messages brief, lowercase is acceptable, and start with an action verb. PRs should explain the user-visible behavior change, list validation steps, and note any fixture or CLI output changes. Include example commands when altering CLI behavior, such as npm run dev -- query --gav ... --json.

Repository-Specific Notes

This project is version-pinned by design: prefer exact artifact coordinates over "latest" assumptions. When changing query or inspection flows, keep README.md and SKILL.md aligned with the CLI behavior.