Technical docs for @stainless-code/codemap.
Start here: ../README.md (install, CLI, API, dev commands). This folder is deeper reference — pick a row below.
| File | Topic |
|---|---|
| why-codemap.md | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme |
| architecture.md | Schema, layering, CLI internals, API, User config (Zod), parsers, Key Files |
| agents.md | codemap agents init — bundled templates/agents → .agents/ in consumer projects (this repo’s .agents/ is dev/maintainer — see agents.md); per-file IDE symlink/copy, pointer files (codemap-pointer), --interactive, .gitignore / .codemap.* |
| benchmark.md | Indexing another project · Benchmark script · Query stdout (table vs JSON) · Custom scenarios (CODEMAP_BENCHMARK_CONFIG) · fixtures/minimal/ |
| golden-queries.md | Golden query design & policy (Tier A/B, no proprietary trees); runner: scripts/query-golden.ts |
| fixtures/golden/ | scenarios.json + minimal/ — bun run test:golden; Tier B: scenarios.external.example.json + bun run test:golden:external (benchmark § Fixtures) |
| fixtures/benchmark/ | Tracked scenarios.example.json — copy to *.local.json (gitignored) for CODEMAP_BENCHMARK_CONFIG |
| fixtures/qa/ | prompts.external.template.md — optional chat QA prompts for an external index (*.local.md gitignored) |
| packaging.md | CHANGELOG.md / dist/ / templates/ on npm, engines, Node vs Bun, Releases (Changesets; bun run version + oxfmt CHANGELOG.md) |
| roadmap.md | Forward-looking backlog (not a src/ inventory) |
| Topic | Canonical doc | Elsewhere |
|---|---|---|
| Runtime splits (SQLite, workers, globs, JSON config I/O) | packaging § Node vs Bun — the table lives here | architecture § Runtime links here; do not copy the table |
codemap.config.* shape / Zod validation |
architecture § User config | Root README § Configuration points here |
codemap agents init: --force on .agents/ in consumer projects (template file paths only), IDE matrix, per-file symlink/copy, templates/agents |
agents.md | Link here; do not paste the integration table into README or packaging |
CLAUDE.md / AGENTS.md / GEMINI.md / Copilot — managed codemap-pointer sections, merge vs --force |
agents.md § Pointer files | Link here; do not duplicate the situation table |
End-user CLI (index, query --json, query --recipe, query --recipes-json, query --print-sql, agents, flags, env) — query has no row cap; use SQL LIMIT; --json errors include SQL, DB open, and bootstrap failures; bundled templates/agents/ examples default to --json |
../README.md § CLI | architecture § CLI usage summarizes and links back; agents.md |
Golden query regression (test:golden, test:golden:external, --update) |
golden-queries.md | CONTRIBUTING § Golden queries; benchmark § Fixtures |
CODEMAP_BENCHMARK_CONFIG (per-repo benchmark JSON) |
benchmark § Custom scenarios | fixtures/benchmark/scenarios.example.json only |
bun run qa:external — index + disk checks + benchmark.ts on CODEMAP_* |
.github/CONTRIBUTING.md | scripts/qa-external-repo.ts (invocation only) |
- One topic per file; prefer relative links between these docs.
- CLI flags and examples — canonical README.md § CLI. Other docs summarize and link; do not copy full flag lists (see Single source of truth above). Implementation paths (
src/cli/…,QUERY_RECIPES) belong in architecture.md § CLI usage only. - Avoid stale file/symbol counts in narrative text — use
codemap query --json/bun run dev query --jsonafter indexing (or omit--jsonfor a terminal table); methodology tables in benchmark.md are fine. - This repo:
bun run devisbun src/index.ts;bun run build→ tsdown →dist/;bun run clean/bun run check-updates— .github/CONTRIBUTING.md. - Contributors: branch + PR into
main(CI),bun run check, JSDoc on public API.