代码地图

Diff per-delta baselines vs current — files / dependencies / deprecated drift in one envelope

codemap query --save-baseline=base-files "SELECT path FROM files" codemap query --save-baseline=base-dependencies "SELECT from_path, to_path FROM dependencies" codemap query --save-baseline=base-deprecated -r deprecated-symbols codemap audit --baseline base # auto-resolves base-{files,dependencies,deprecated} codemap audit --json --summary --baseline base # counts-only — useful for CI dashboards codemap audit --files-baseline base-files # explicit per-delta — runs only the slots provided codemap audit --baseline base --files-baseline hotfix-files # mixed — auto-resolve deps + deprecated; override files codemap audit --baseline base --no-index # skip the auto-incremental-index prelude (frozen-DB CI) codemap audit --base origin/main --json # ad-hoc — added[].attribution; --summary adds added_introduced/inherited codemap audit --base origin/main --format sarif # emit SARIF 2.1.0 directly (Code Scanning); also: --ci alias codemap audit --base origin/main --ci # CI shortcut: --format sarif + non-zero exit on additions codemap audit --base v1.0.0 --files-baseline pre-release-files # mix --base with per-delta override

a cached `.codemap/index.db` at that sha, then diffs. Cache hit on second run against same sha is sub-100ms. Requires git;

non-git projects get a clean `codemap audit: --base requires a git repository.` error.

formatted outputs require a flat row list

requires {from, to, label?, kind?} rows and rejects unbounded inputs (>50 edges) with a

non-MCP consumers (CI scripts, curl, IDE plugins). Loopback default; --token required on non-loopback.

TOKEN=$(openssl rand -hex 32) codemap serve --port 7878 --token "$TOKEN" & # --token required when --host is not loopback curl -s -X POST http://127.0.0.1:7878/tool/query \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $TOKEN" \ -d '{"sql":"SELECT name, file_path FROM symbols LIMIT 5"}'

Impact analysis — symbol/file blast-radius walker (callers, callees, dependents, dependencies)

codemap impact handleQuery # both directions, depth 3, all compatible graphs codemap impact dup --in src/a.ts --via calls # homonym symbol scoped to one defining file codemap impact src/db.ts --direction up # what depends on db.ts (file-level, deps + imports) codemap impact handleAudit --depth 1 --via calls # direct callers via the calls table only codemap impact runWatchLoop --json --summary | jq '.summary.nodes' # CI-gate fan-in score

Affected tests — reverse dependency walk from changed sources → test files to run

codemap affected --json # working-tree changes vs HEAD (git status + diff) git diff --name-only origin/main | codemap affected --stdin --json codemap affected src/lib/cache.ts --json # explicit changed paths codemap affected --changed-since origin/main --json # committed delta + working tree vs ref

Install

```bash bun add @stainless-code/codemap

or: npm install @stainless-code/codemap

```

Engines: Node ^20.19.0 || >=22.12.0 and/or Bun >=1.0.0 — see package.json and docs/packaging.md.

---

Full rebuild

codemap --full

auto-detects and forces a full rebuild so `source_fts` stays consistent.

codemap --with-fts --full codemap query --recipe text-in-deprecated-functions # demonstrates FTS5 ⨯ symbols ⨯ coverage JOIN

Live agent content (pointer protocol — full body served from installed package version)

codemap skill # full codemap SKILL markdown to stdout codemap rule # full codemap rule markdown to stdout

Bundled SQL (same as skill examples): fan-out rankings

codemap query --json --recipe fan-out codemap query --json --recipe fan-out-sample

Bundled diff-shape recipes: rename-preview, migrate-import-source, replace-marker-kind, stale-imports, migrate-deprecated, deprecated-usages, migrate-jsx-prop, add-jsdoc-deprecated

Agent/codemod rows (no recipe policy gates): echo '[{...}]' | codemap apply --rows - --yes

Index project root (optional <state-dir>/config.{ts,js,json}; --state-dir overrides .codemap/)

codemap

With --json: JSON array on success; {"error":"..."} on stdout for bad SQL, DB open, or query bootstrap (config/resolver)

codemap query "SELECT name, file_path FROM symbols LIMIT 10"

Architecture-boundary rules (declare in .codemap/config.ts):

Default action is "deny"; the table is reconciled from config on every index pass.

codemap query --recipe boundary-violations --format sarif > boundary-findings.sarif

.codemap/index.db size); CLI flag wins over .codemap/config.ts `fts5` field. Toggle change

Output envelope is always {matches, disambiguation?, warning?} — single match → {matches: [{...}]};

(default 3, --depth 0 = unbounded), limit-capped (default 500). Result envelope:

Optional git commit (recipe id required): codemap apply rename-preview --params old=a,new=b --yes --commit "chore: rename a→b"

query / query_recipe also accept baseline (same diff envelope as codemap query --baseline).

Output shape verbatim from `--json` envelopes (no re-mapping). Snake_case throughout.

Explicit config

codemap --config /path/to/config.json --full

Full reference

```bash

HTTP API — same tool taxonomy as `codemap mcp`, exposed over POST /tool/{name} for

CLI twins: query batch, trace, explore, node, file, schema, symbols, context --include-snippets, ingest-coverage, ingest-churn (same JSON as MCP/HTTP).

Programmatic API (ESM)

import { createCodemap } from "@stainless-code/codemap";

const cm = await createCodemap({ root: "/path/to/repo" });
await cm.index({ mode: "incremental" });
await cm.index({ mode: "full" });
await cm.index({ mode: "files", files: ["src/a.ts"] });
await cm.index({ quiet: true });

const rows = cm.query("SELECT name FROM symbols LIMIT 5");

createCodemap configures a process-global runtime (initCodemap); only one active project per process is supported. Advanced: runCodemapIndex when you hold a CodemapDatabase handle (library integration — not a separate public openDb() export; use createCodemap for the supported path). Module layout: docs/architecture.md § Layering.

---

Group rows by directory, CODEOWNERS owner, or workspace package

codemap query --json --summary --group-by directory -r fan-in codemap query --json --group-by owner -r deprecated-symbols codemap query --json --summary --group-by package "SELECT file_path FROM symbols"

`components-by-hooks` ranks by hook count without SQLite JSON1 (comma-based count on the stored JSON array).

Bundled recipes live in templates/recipes/ in the npm package; project recipes win on id collision