ai-code-map 0.0.0-stage → 0.1.0-alpha.3

package/docs/api.md

@@ -0,0 +1,152 @@
+# Programmatic API
+
+Import path: `import { ... } from "ai-code-map"`.
+
+## Runtime-safe API
+
+The library API does not call `process.exit`; all failures throw `CodeMapError` or surfaced errors.
+
+Persisted artifacts are written in schema `v4`. Older maps return an actionable rescan error.
+Schema v4 adds redundant source ownership and line-count fields so direct loads can reject
+one-sided coherent corruption; a rescan is required.
+
+## Core functions
+
+- `initProject(options?) -> Promise<InitResult>`
+  - writes default config if missing
+  - options: `{ root?, config?, output?, force? }`
+- `scanProject(options?) -> Promise<ScanResult>`
+  - scans and writes artifacts
+  - auto-initializes config if absent
+  - options: `{ root?, config?, output?, strict?, analyzers?, parser?, semanticResolver? }`
+  - discovers config candidates (`tsconfig*.json`, `jsconfig.json`) and resolves transitive `extends` and project `references`
+  - computes exact ownership per normalized compiler unit and builds one deterministic TypeScript `Program` per unit
+  - processes compiler units sequentially in stable compiler-unit order, then merges normalized owned facts globally
+  - only owned files are persisted
+  - reuses a complete validated current map for the default pipeline; stale inputs, invalid companion artifacts, or custom parser/analyzer/resolver components run full analysis
+- `checkFreshness(options?) -> Promise<FreshnessResult>`
+  - validates the complete persisted artifact set and its raw-byte integrity index
+  - compares indexed sources, compiler-consumed files, project/toolchain-scoped typed resolution probes, observed directory listings and symlinks, consumed TypeScript libraries, configuration, and producer compatibility with current project state
+- `loadCodeMap(options?) -> Promise<CodeMap>`
+  - loads persisted map from resolved output directory
+- `buildProjectMap(map) -> ProjectMapView`
+  - projects a validated `CodeMap` into all indexed files, symbols, other endpoints, and grouped relations; does not mutate the input or check freshness
+  - returns `{ project, counts, files, symbols, endpoints, relations }`; nodes carry output-local `ref` values and original stable IDs
+  - symbol `file` points to a file ref; symbol `range` retains source coordinates
+  - relation groups contain `{ from, type, classification, targets: [{ ref, count }] }`; counts preserve all occurrence records, including heuristic and derived relations
+  - excludes source text, signatures, facts, and individual origin/confidence records; use the original map for that evidence
+- `formatProjectMap(view) -> string`
+  - deterministic complete text with short references, stable symbol IDs, source lines, evidence classifications, and occurrence counts; no pagination or row limit
+  - the CLI `map` command checks freshness and reuses the validated map before calling these functions; missing/stale/invalid artifacts return exit code 2
+- `computeManifestIntegrityHash(manifest) -> string`
+  - computes the canonical code-point-ordered manifest integrity hash used by persistence and tests
+- `buildSourceContext(map, query, { root, maxLines?, maxChars?, seeds? }) -> Promise<ContextResult>`
+  - selects lexical matches (exact IDs/names take precedence), then expands one direct graph hop using the bounded `read` navigation rules
+  - for partial queries, ranks callable candidates using missing query words in their current source bodies and expands the strongest ties; inspects at most the 50 lexical candidates, with per-term occurrence counts capped at three
+  - skips reference-only class neighbors and counts them as omitted navigation; an explicitly selected class still expands normally
+  - includes up to four exact/framework-derived incoming file-level calls/references outside test files; a file of at most 80 lines is included in full, otherwise the mapped site has eight context lines on either side, within the shared budgets
+  - after primary source and file references, includes up to four outgoing exact/framework-derived dependencies of direct outgoing neighbors: functions or variables with bodies of at most 80 lines, calls before references; does not recurse or expand incoming callers
+  - defaults: 3 matches (1..5), 800 source lines (1..2000), 32,000 source characters including separators (256..64000)
+  - verifies paths, hashes and ranges for source-ranking candidates, selected symbols and file references; coalesces overlapping/adjacent source intervals
+  - returns `{ query, matches, moreMatches, selected, snippets, omitted, fileReferences, tests, omittedNavigation, usedLines, usedChars, limits }`
+  - `snippets` contain `{ file, startLine, endLine, source }`; `omitted` lists unread source ranges and symbol/file IDs excluded by the shared budget; file IDs are navigation targets, so read their printed source ranges directly
+  - test call sites are bounded navigation hints; omitted-navigation counts sum entries excluded by each seed's navigation limits, the shared test-site limit, and the small-dependency size/count limits
+  - the API validates selected source files; the CLI `context` also checks full map freshness before calling it
+- `formatSourceContext(result) -> string`
+  - renders numbered source windows once per contiguous range, with bounded selection/test/omission metadata; metadata is additional to the source budgets
+- `readSymbolSource(map, id, { root, limit?, offset? }) -> Promise<ReadSourceResult>`
+  - requires an exact stable ID; reads current source with two context lines per side
+  - `root` is the project root; `limit` defaults to 80 (integer 1..200); `offset` defaults to zero within that window
+  - returns `{ id, file, symbolRange, startLine, endLine, source, truncated, nextOffset?, navigation? }`
+  - at offset zero, `navigation` contains `{ links, tests, omittedLinks, omittedTests }`; continuation pages omit it
+  - each link has `{ direction, type, id, file, startLine, endLine, classification }`; exact and framework-derived internal neighbors only, deduplicated by direction and ID
+  - `tests` contains exact incoming call sites `{ file, line }` in `*.test.*`, `*.spec.*`, or `__tests__/` paths; this is a navigation hint, not a coverage claim
+  - limits navigation to eight links, four test sites, and fewer than 4,000 compact JSON characters; omission counts refer to eligible unique neighbors/sites excluded by these limits
+  - verifies source path containment and indexed file hash; rejects symbolic files, stale source, invalid offsets, and pages over 12,000 characters
+  - does not validate all project dependencies; use `checkFreshness` before navigation
+- `showSymbol(map, selector) -> ShowResult`
+  - selectors: exact ID, `kind:name`, `path#name`, exact name/path
+  - returns all matching symbols and full relation records; no display filtering
+- `formatShowResult(result, options?) -> string`
+  - compact by default: up to five symbols and 12 relation groups in total, with omission counts
+  - options: `{ full?: boolean, limit?: number }`; `limit` is an integer 1..50
+  - `{ full: true }` preserves the previous verbose text view
+- `findSymbols(map, query, options?) -> SymbolSearchResult`
+  - searches indexed names and paths; returns stable IDs and source ranges
+  - options: `{ limit?: number }`, default 10, integer 1..50; invalid limits throw `RangeError`
+  - empty/whitespace query throws; no matches returns an empty array
+  - returns `{ query, total, truncated, matches: [{ id, name, kind, file, range, unmatchedTerms? }] }`
+  - deterministic lexical ranking and bounded typo hints; does not resolve guessed names as exact symbols
+  - word matching normalizes common English plurals and favors name matches over path matches
+  - whitespace-separated queries with at least three distinct normalized words may return partial matches after full matches and typo hints; at least two words and half the query must match, including a word in the symbol name
+  - only partial matches include `unmatchedTerms`, listing normalized query words absent from that symbol's name and path; this is lexical overlap, not semantic equivalence
+  - qualified file selectors remain restricted to that file; partial matching does not broaden them
+
+## Analyzer constructors
+
+- `createAnalyzer({ analyzers?, parser?, semanticResolver? })`
+  - returns `{ analyzers, parser, scan(...) }`
+- `scanProject` uses analyzer defaults: `CoreAnalyzer`, `ReactAnalyzer`
+- Optional analyzers are available:
+  - `NextJsAnalyzer`
+  - `NestJsAnalyzer`
+
+## Parser adapters
+
+- `TypeScriptParserAdapter` and `FallbackParserAdapter`
+- Custom parser adapters implement `SyntaxParserAdapter` and can be passed into `scanProject`/`createAnalyzer`.
+
+## Semantic resolver
+
+- `TypeScriptSemanticResolver` is the compiler-backed default.
+- TypeScript `Program`/`TypeChecker` facts remain authoritative even when a syntax adapter is supplied.
+- Parser and semantic implementations never enter persisted Code Map records. Display names/versions are recorded, while a separate producer record and capability fingerprint determine default-pipeline reuse eligibility. Explicit built-in parser equivalence requires a directly registered, unmodified adapter instance; proxies, subclasses, and method overrides remain custom.
+- Public `SemanticResolver` contracts are additive:
+  - `SemanticResolveInput` has optional `compilerUnit`
+  - `SemanticResolution` may return an optional unit-anchored `resolveModule` helper
+  - `SemanticResolution` may return an optional `semanticInputs()` closure containing raw-byte file/toolchain hashes plus typed resolution probes, directory listings, and symlink mappings scoped to `project` or `toolchain`; omitted observation scope defaults to `project` for extension compatibility
+- Coordinator may invoke resolver once per owning compiler unit; custom analyzers receive unit-scoped `Program` and `TypeChecker`.
+- Rooted host/type/module resolution is used to avoid caller working-directory effects.
+- Text contributed by custom parsers, resolvers, and analyzers is sanitized before persistence; unsafe structural paths supplied by an extension fail schema validation rather than escaping the selected-root boundary. Supplied analyzer trust is resolved through registered instance identity at each invocation, so proxies and overridden instances receive isolated persistence context.
+
+## Types exported
+
+The package exports major record/contract types including:
+
+- `CodeMap`, `CodeMapConfig`, `ManifestRecord`, `ProjectRecord`
+- `FileRecord`, `SymbolRecord`, `RelationRecord`, `DiagnosticRecord`
+- `CompilerUnitRecord`, `ProducerRecord`, `SemanticInputRecord`, `ArtifactIntegrityRecord`
+- `ScanResult`, `FreshnessResult`, `ShowResult`, `ShowFormatOptions`
+- `SymbolSearchResult`, `SymbolSearchOptions`, `SymbolSearchMatch`
+- `ScanOptions`, `LoadCodeMapOptions`, `AnalysisContext`
+
+## Example
+
+```ts
+import {
+  initProject,
+  scanProject,
+  checkFreshness,
+  loadCodeMap,
+  showSymbol,
+  NextJsAnalyzer,
+  createAnalyzer,
+  TypeScriptParserAdapter,
+} from "ai-code-map";
+
+await initProject({ root: process.cwd() });
+const scan = await scanProject({ root: process.cwd(), strict: false });
+console.log(scan.counts);
+
+const fresh = await checkFreshness({ root: process.cwd() });
+console.log(fresh.current, fresh.reasons);
+
+const map = await loadCodeMap({ root: process.cwd() });
+console.log(showSymbol(map, "component:UserList").matches[0]?.symbol.kind);
+
+const analyzer = createAnalyzer({
+  analyzers: [new NextJsAnalyzer()],
+  parser: new TypeScriptParserAdapter(),
+});
+await analyzer.scan({ root: process.cwd() });
+```

package/docs/architecture/ADR-0001-hybrid-syntax-and-semantics.md

@@ -0,0 +1,140 @@
+# ADR-0001: Hybrid syntax candidates and TypeScript semantics
+
+- Status: accepted for alpha
+- Date: 2026-08-06
+- Decision owners: project maintainers
+
+## Context
+
+The scanner needs error-tolerant syntax discovery without weakening facts that only the TypeScript compiler can prove. Parsing every TypeScript file twice in every one-shot scan would add installation, memory, and maintenance cost before it has demonstrated a repository-level benefit.
+
+The public Code Map IR must not expose Tree-sitter nodes, ast-grep objects, TypeScript AST objects, or library-specific IDs.
+
+## Decision
+
+The target pipeline is:
+
+```text
+source files
+  -> replaceable syntax-candidate adapter
+  -> normalized syntax facts
+  -> TypeScript Program / TypeChecker semantic confirmation
+  -> versioned framework analyzers
+  -> versioned Code Map IR
+```
+
+For the alpha production path, the TypeScript `Program` supplies both its reusable syntax tree and authoritative semantic layer. This avoids a second parse. A custom `SyntaxParserAdapter` is opt-in; failure or a fatal parse result falls back to the compiler without aborting the scan. Adapter error text is not persisted because third-party errors may contain source text, absolute paths, or environment-derived values.
+
+`@ast-grep/napi@0.45.0` is the selected bounded Tree-sitter prototype. It is pinned as a development dependency, exercised only by the parser microbenchmark, and is not in the published runtime dependency set. It provides built-in TypeScript and TSX languages and substantially less visitor/rule boilerplate than a raw Tree-sitter binding.
+
+Tree-sitter is therefore **deferred as a default production pass**. The public adapter and normalized IR are in place; the compiler-only path remains the safe fallback and default.
+
+### Milestone 1 and 1.1 closure updates
+
+- Persisted schema is now `v4`; v3 added semantic-input closure, producer provenance, companion
+  integrity hashes, and collision-safe unit IDs, while v4 adds redundant per-source compiler
+  ownership and line counts for direct-load integrity. Existing maps require a rescan.
+- A bounded config walk now discovers and fingerprints `tsconfig`/`jsconfig` candidates and resolves transitive `extends` and `references`; workspace/config manifests participate in ownership and freshness.
+- Ownership is assigned only via parsed `fileNames` and chooses the deepest validated boundary in priority order:
+  - deepest shared validated workspace/package boundary,
+  - deepest config directory ancestor,
+  - lexical normalized config path fallback.
+- One compiler `Program` is built per non-empty owning compiler unit. Programs are processed sequentially and only owned files are analyzed/persisted; zero-owned solution nodes remain graph metadata, and unit facts are merged after normalizing root-relative paths.
+- File ownership is enforced by a single compiler unit per scanned file, with exactly one `fallback` unit when no configured owner exists.
+- The source import graph is resolved in-module during scan. Direct referenced packages use parsed project references plus static package metadata to resolve back to in-root source when an emitted `.d.ts` target is absent.
+- TypeScript remains the semantic authority; Tree-sitter/ast-grep remains development-only for now.
+- `manifest.configHash` includes normalized scanner semantics, ownership/config graph inputs, and versioned tool/parser/analyzer/TS/schema vectors. A separate deterministic closure records additional in-root files TypeScript consumed plus typed resolution probes, directory listings, symlink mappings, and raw-byte file hashes scoped to the selected project or active TypeScript library root.
+- A current default scan reuses the complete persisted map only after every companion's raw bytes match the manifest integrity index and all schemas/cross-record invariants validate. Stale semantic inputs, invalid/missing companions, or custom analysis components use the full compiler path.
+- Initial and freshness source identities are SHA-256 over identical raw bytes; UTF-8 decoding is analysis input only.
+- External call identities use import provenance where it is provable (`external:react#useState`); unknown module provenance remains explicit and heuristic (`external:unresolved#...`).
+- Generated and configured compiler-unit IDs have disjoint structural prefixes. Persisted paths are repository-relative POSIX values, with cross-platform absolute import text redacted at the persistence boundary.
+
+Compatibility notes:
+
+- `ProjectRecord.tsconfig` and `ProjectRecord.pathAliases` are retained as compatibility projections.
+- `CompilerUnitRecord.pathAliases` is authoritative for unit analysis.
+- Bounded host/type/module resolution avoids caller working-directory dependence.
+- The manifest integrity index is a deterministic corruption/tamper signal, not a cryptographic signature over an untrusted producer.
+
+## Fact ownership
+
+| Layer                                    | Responsibility                                                                                                                                          | Authority label                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Syntax adapter / future Tree-sitter pass | Error-tolerant candidates for calls, hooks, JSX, decorators, and file conventions                                                                       | candidate only; never semantic proof                         |
+| TypeScript `Program` / `TypeChecker`     | Symbol identity, definitions, aliases, re-exports, module resolution, types, public signatures, overloads, references, calls, and JSX symbol resolution | exact when resolved                                          |
+| React rule pack                          | Components, props, hooks, state/effects/dependencies, and rendered JSX derived from compiler nodes and imports                                          | `framework-derived`, or `heuristic` when not fully confirmed |
+| Next.js / NestJS rule packs              | Convention and decorator facts after semantic confirmation                                                                                              | experimental and default-off in alpha                        |
+| Relation normalizer                      | Inverse edges and canonical endpoint replacement                                                                                                        | `derived`                                                    |
+
+Persisted relations carry `confidence` plus an `origin` containing repository-relative file, line, explanation, evidence classification, and analyzer version identity. The canonical format remains independent of parser implementation.
+
+## Prototype comparison
+
+### `@ast-grep/napi` (selected prototype)
+
+- Version: exactly `0.45.0`.
+- Grammars: built-in `Lang.TypeScript` and `Lang.Tsx`.
+- Distribution: N-API native optional packages for macOS x64/arm64, Windows x64/arm64/ia32, and Linux x64/arm64 glibc plus x64/arm64 musl.
+- Local darwin-arm64 install observation: approximately 392 KiB for the JavaScript/type package and 6.8 MiB for the platform binary package on disk.
+- Benefit: concise query/traversal API and prebuilt binaries, without a local `node-gyp` build in the tested install.
+- Risk: native optional-package coverage and corporate/supply-chain policies still require CI verification on every supported OS/architecture.
+
+### Raw native `tree-sitter`
+
+Evaluated versions were `tree-sitter@0.25.1` and `tree-sitter-typescript@0.23.2`. The grammar declares a peer range around the older `tree-sitter` line, while the native binding has install/build-tooling costs. This combination was not added to the alpha because it increases packaging risk without reducing the amount of rule code.
+
+### `web-tree-sitter`
+
+`web-tree-sitter@0.26.11` with vendored TypeScript/TSX WASM grammars avoids platform-native binaries and remains the portability fallback. It was not selected for the first prototype because the package must explicitly locate and ship loader/grammar WASM assets, initialize them, and keep ABI compatibility tested.
+
+References:
+
+- [ast-grep JavaScript API](https://ast-grep.github.io/guide/api-usage/js-api.html)
+- [ast-grep performance guidance](https://ast-grep.github.io/guide/api-usage/performance-tip.html)
+- [Tree-sitter web binding](https://github.com/tree-sitter/tree-sitter/blob/master/lib/binding_web/README.md)
+- [Node Tree-sitter binding](https://github.com/tree-sitter/node-tree-sitter)
+- [TypeScript grammar](https://github.com/tree-sitter/tree-sitter-typescript)
+
+## Bounded microbenchmark
+
+Command:
+
+```bash
+pnpm benchmark
+```
+
+Environment for the checkpoint below: Node `v22.16.0`, darwin-arm64, TypeScript `5.9.3`, `@ast-grep/napi@0.45.0`; 5 warmups and 30 measured in-process parse iterations. Candidate inspection is outside the timed samples. RSS is observed for the shared process, not an isolated parser peak.
+
+| Fixture               | Normalized candidates agree | Error nodes agree | TypeScript warm median | ast-grep warm median |
+| --------------------- | --------------------------: | ----------------: | ---------------------: | -------------------: |
+| valid TS              |                         yes |             0 / 0 |               0.292 ms |             0.069 ms |
+| valid TSX             |                         yes |             0 / 0 |               0.186 ms |             0.076 ms |
+| partially invalid TSX |                         yes |             1 / 1 |               0.152 ms |             0.073 ms |
+| syntax-error TSX      |                         yes |             1 / 1 |               0.013 ms |             0.010 ms |
+
+This result demonstrates a promising parser-only candidate pass on four small fixtures. It does **not** demonstrate faster repository scans: a production hybrid would still pay TypeScript program construction and would add a second tree. It also does not establish representative peak memory, cold package-load cost, watch performance, or cross-platform installation success.
+
+## Promotion gates
+
+Tree-sitter or ast-grep may become an optional production observer only after all of the following are measured:
+
+1. Representative React, Next.js, NestJS, malformed-source, monorepo, and project-reference repositories.
+2. Cold one-shot scan time, warm/watch time, peak RSS in isolated processes, output/map diff, and precision/recall.
+3. macOS, Linux glibc/musl, and Windows installation and package tests on supported architectures.
+4. A demonstrated maintenance or performance improvement after including the still-required TypeScript semantic pass.
+5. Byte-identical canonical output when the candidate layer contributes no new confirmed facts.
+6. Compiler fallback coverage for missing binaries, unsupported languages, parse failures, and partial trees.
+
+Until those gates pass, the default remains compiler-only and no Tree-sitter object enters the public IR.
+
+## Reuse decisions in the alpha
+
+- Commander, fast-glob, Node crypto, Vitest, tsup, and sorted JSONL remain in place.
+- `@manypkg/get-packages` is behind `WorkspaceDiscovery`; selected-root and realpath containment are enforced before workspace metadata is persisted.
+- `ignore` is behind `IgnoreAdapter`; discovery disables symlink following and verifies realpaths.
+- Zod schemas own configuration and every persisted record type. TypeScript types are inferred from them, runtime reads/writes are validated, and checked-in Draft 2020-12 JSON Schemas are generated with `z.toJSONSchema`.
+- The TypeScript semantic layer is behind `SemanticResolver`; its normalized public outputs remain Code Map records rather than compiler objects.
+
+## Consequences
+
+The alpha retains a reliable installation and one authoritative semantic model. It accepts that a syntax-only speedup has not yet been realized and that malformed-file recovery is currently limited by TypeScript's tolerant parser. The adapter boundary makes the experiment replaceable without rewriting framework analyzers or changing persisted artifacts.

package/docs/artifacts.md

@@ -0,0 +1,156 @@
+# Artifacts and output schema
+
+All persisted artifacts are written as JSON or line-delimited JSON under the selected output directory (default `.ai/code-map`).
+
+## `manifest.json`
+
+Source inventory and analyzer provenance used for freshness:
+
+- `schemaVersion`
+- `analyzerVersion`
+- `producer`
+  - `id`: centrally assigned built-in/custom pipeline identity
+  - `kind`: `built-in` or `custom`
+  - `fingerprint`: stable capability/component fingerprint used by default-map reuse
+- `semanticResolver`
+  - `name`
+  - `version`
+- `syntaxParser`
+  - `name`
+  - `version`
+- `analyzers`: stable list of enabled analyzers and versions
+- `configHash`: serialized analysis configuration and project metadata hash
+- `sourceFiles`: `[{ path, hash, compilerUnit, lines }]` for all persisted source files; ownership
+  and line count redundantly cross-check `files.jsonl`
+- `semanticInputs`: deterministic compiler-observed closure
+  - consumed file: `{ path, kind: "file", hash }`, where `hash` is SHA-256 of the exact raw bytes
+  - typed lookup: `{ path, kind: "resolution-probe", scope, targetKind, exists }`, where `scope` is `project` or `toolchain` and `targetKind` is `file`, `directory`, or `readable-file`
+  - child-directory enumeration: `{ path, kind: "directory-listing", scope, hash }`
+  - scoped lexical-to-realpath mapping: `{ path, kind: "symlink", scope, target }`; an out-of-scope target is the opaque `<outside-root>` marker
+  - TypeScript standard-library input: `{ path, kind: "toolchain-file", hash }`, relative to the active TypeScript library directory
+- `artifacts`: SHA-256 of the exact raw bytes of every companion artifact
+- `integrityHash`: SHA-256 binding all other manifest fields, including producer identity, semantic inputs, and companion hashes
+
+Freshness inputs now include:
+
+- normalized scanner semantics, config graph structure, ownership resolution, and all `tsconfig`/`jsconfig` / `extends` / `references` inputs
+- selected root/workspace manifests (including workspace dependency ranges), lockfiles, and tool/analyzer/parser/TypeScript/schema version identities
+- additional in-root sources, declarations, nested package scopes, package metadata, readable/unreadable candidates, child-directory enumerations, symlink targets, and failed/present resolution candidates actually observed by TypeScript
+- exact TypeScript library files plus failed/present toolchain probes observed by the active compiler, so same-version patched, restored, or replaced library inputs invalidate reuse
+
+The minimum complete map is `manifest.json` plus `overview.md`, `project.json`, `files.jsonl`, `symbols.jsonl`, `relations.jsonl`, and `diagnostics.json`. An unchanged default scan opens, hashes, parses, schema-validates, and cross-validates the complete set before reuse. Missing, invalid, incompatible, inconsistent, or hash-mismatched companions force full analysis and repair rather than trusting `manifest.json` alone.
+
+The manifest is the commit marker and is written last. Companion hashes and `integrityHash` are tamper-evident for ordinary corruption or partial edits; they are not authenticated signatures against an actor able to rewrite the whole map coherently. Source remains authoritative.
+
+Loading and reuse additionally enforce cross-record invariants: canonical compiler-unit IDs/references,
+manifest-to-file compiler ownership and line counts, exact symbol ownership, import-to-relation
+agreement, internal import targets, record counts, local endpoints, range/line bounds, relation
+evidence origin, and containment/export ownership. Schema v4 is intentionally incompatible with v3;
+existing maps must be rescanned.
+
+## `project.json`
+
+Project context:
+
+- `schemaVersion`
+- `name`
+- `packageManager` (if present)
+- `frameworks`: detected and selected frameworks
+- `tsconfig` (if found): compatibility projection of the primary configured unit
+- `pathAliases`: compatibility projection from the default compatibility compiler unit
+- `compilerUnits[]`:
+  - `id` (`compiler-unit:configured:<config-path>` or structurally distinct `compiler-unit:generated:<name>`)
+  - `kind` (`configured` | `fallback`)
+  - `root`
+  - `config?` (normalized selected config path)
+  - `references` (compiler-unit-level `references` paths)
+  - `extends` (compiler-unit-level `extends` values)
+  - `pathAliases` (authoritative per-unit aliases)
+- exactly one `fallback` compiler unit exists (it may own zero files)
+- `entryPoints`, `workspaces`
+- `counts`: number of files/symbols/relations/diagnostics
+
+## `files.jsonl`
+
+One JSON object per scanned source file (`FileRecord`):
+
+- `schemaVersion`
+- `id` (`file:<path>`)
+- `path`
+- `language`
+- `frameworks`
+- `compilerUnit` (required)
+- `hash` (content hash)
+- `lines`
+- `imports` (`[{ source, specifiers, resolved, external, kind, line }]`)
+- `exports` (`[{ name, local, source, default, typeOnly }]`)
+- `symbolIds` (sorted)
+- `env` (identifier names only)
+- `operations` (filesystem/http/database/queue usage)
+- `syntax` summary (`parser`, `factCount`, `hadErrors`, optional `fallbackFrom`)
+- paths are repository-relative POSIX strings; unresolved absolute module specifiers are replaced by an opaque marker instead of being persisted
+- alias targets with absolute, drive, UNC, or parent-traversal syntax are omitted before host-native
+  path resolution; valid relative wildcard targets remain portable
+
+## `symbols.jsonl`
+
+One JSON object per symbol (`SymbolRecord`):
+
+- `schemaVersion`
+- `id` (stable)
+- `name`
+- `kind` (`function`, `react-component`, `next-page`, `nest-controller`, ...)
+- `file`
+- `range`
+- `exported`
+- `defaultExport` (optional)
+- `signature` (source-derived)
+- `documentation` (optional; not emitted by the base scanner)
+- `facts` (framework-aware structured facts)
+- `sourceHash`
+
+## `relations.jsonl`
+
+Directed edges between files and symbols:
+
+- `schemaVersion`
+- `from`
+- `to`
+- `type` (e.g. `calls`, `instantiates`, `renders`, `uses-hook`, `handles-route`, `injects`, ...)
+- `confidence` (must be between `0` and `1`)
+- `origin.file`
+- `origin.line`
+- `origin.range`
+- `origin.explanation`
+- `origin.classification` (`exact`, `framework-derived`, `heuristic`, `derived`)
+- `origin.analyzer`
+
+Unresolved heuristic edges continue to receive deterministic `used-by` inverses for graph
+traversal. Their unresolved external endpoint remains present on the inverse, so audits can identify
+the uncertainty from either direction. Future default compact context excludes heuristic/unresolved
+edges unless explicitly requested.
+
+## `diagnostics.json`
+
+Validation and analysis issues:
+
+- `schemaVersion`
+- `code` (`parse-error`, `unresolved-import`, `invalid-config`, `unsupported-file`,
+  `analysis-error`, `parser-fallback`, `compiler-config`)
+- `severity` (`info`, `warning`, `error`)
+- `message`
+- `file`/`line`/`column` (optional)
+
+## `overview.md`
+
+Human-readable summary containing project names, frameworks, counts, entry points, and an indexed file listing.
+
+## Ordering and determinism
+
+Records are sorted deterministically before write:
+
+- files by path
+- symbols by ID
+- relations by endpoint, type, evidence file, and full evidence range
+
+Mtime stability is preserved by avoiding rewrites when the map is unchanged.

package/docs/backlog.md

@@ -0,0 +1,43 @@
+# Delivery backlog
+
+`PROJECT.md` is the product source of truth. This page records implementation sequencing; it is not a promise that later capabilities exist in the alpha.
+
+## Alpha contract
+
+- Deterministic local TypeScript/JavaScript and React scanning.
+- TypeScript compiler-authoritative semantic facts.
+- Replaceable syntax and semantic boundaries with safe fallback.
+- `init`, `scan`, `check`, and `show` only.
+- Zod-owned configuration/persisted schemas, stable IDs, evidence, confidence, hashes, and freshness.
+- Deterministic compiler units for multiple TypeScript configs, project references, workspace
+  boundaries, and unowned-file fallback analysis.
+- Focused security, malformed-source, determinism, API, and CLI behavioral tests.
+
+## Next milestone: bounded context foundation
+
+1. Add a deterministic, structured query API with strict output budgets, ranking, truncation, and omission accounting.
+2. Compare compact map context with relevant source slices and return the smaller useful representation.
+3. Keep the alpha.2 peak-memory regression gates while expanding query capabilities.
+4. Mature and independently validate the existing experimental Next.js and NestJS analyzers before enabling either by default.
+5. Run the parser evaluation corpus on representative repositories and supported CI platforms; decide whether ast-grep stays dev-only, becomes optional, or becomes a default candidate observer.
+6. Add accuracy fixtures and precision/recall reporting for framework rule packs.
+7. Only after bounded retrieval is validated, add rebuildable local impact indexes, watch mode, lexical search, and an official-SDK read-only stdio MCP adapter.
+
+## Deferred adapters
+
+- Graphology as a rebuildable in-memory index; JSONL remains canonical.
+- MiniSearch for deterministic local lexical search.
+- Chokidar for a long-lived watcher.
+- Official MCP TypeScript SDK over local stdio.
+- SCIP import/export and SARIF output.
+- Safe optional importers for OpenAPI, GraphQL, coverage, CODEOWNERS, Storybook, and existing generated artifacts.
+
+## Explicitly not core
+
+- LLMs, embeddings, API keys, network calls, or telemetry in deterministic map generation.
+- Model-interpreted natural-language tasks. The bounded `context` command uses lexical matches and stored graph edges only.
+- Web UI, cloud service, billing, authentication, or deployment in this package.
+- ts-morph, dependency-cruiser, or react-docgen as authoritative analyzers.
+- Next.js private internals or NestJS runtime reflection.
+- SQLite, Neo4j, or a vector database before profiling demonstrates a need.
+- Dynamic execution/loading of scanned application modules or configuration.

package/docs/limitations.md

@@ -0,0 +1,82 @@
+# Known limitations and backlog
+
+## In-scope alpha
+
+- CLI commands are `init`, `scan`, `check`, `show`, `find`, `read`, `map`, and `context`.
+- `scan` output is static analysis only; no code execution.
+- No remote service, account linking, or telemetry is part of the alpha.
+- Framework analyzers included by default are TypeScript/Node and React only.
+
+## Next.js and NestJS
+
+- Analyzer classes for Next.js and NestJS are exported and callable through the programmatic API.
+- These analyzers are considered **experimental** and are **not enabled by default** in CLI.
+- They are intentionally not part of the minimal default analyzer contract.
+
+## Parser extensibility
+
+- TypeScript compiler parser is authoritative in this alpha.
+- The parser adapter interface supports custom adapters and fallback wrappers.
+- A bounded `@ast-grep/napi` spike and fixture microbenchmark are present, but the adapter is development-only and is not enabled in production scans.
+- `TypeScript` compiler semantics are the authoritative source of truth for persisted facts.
+- Evidence and confidence still require explicit provenance in output and freshness contracts.
+- Freshness tracks indexed raw-byte hashes, the deterministic compiler-observed semantic closure, config/package inputs, producer identity, and tool identities.
+
+## Not yet implemented
+
+- No global search/context query language in CLI.
+- No impact/risk scoring commands.
+- No source snippet persistence in public artifacts.
+- No runtime evidence importer layer.
+- No watch/incremental compiler mode. Current default maps are validated and reused, but stale scans rebuild compiler state from scratch.
+- No multi-process Program reuse between scans.
+
+## Dependencies and scan exclusions
+
+- Default source discovery excludes `**/node_modules/**`. Dependency files are not indexed as
+  project files or symbols.
+- Source exclusion does not prohibit compiler reads. TypeScript still needs dependency declarations
+  and package metadata to resolve imports and types; consumed inputs participate in freshness checks.
+- Keep installed dependencies inside the selected project root. Replacing `node_modules` with a
+  symlink to another checkout can cause unresolved imports because the bounded compiler host does
+  not follow dependency paths outside that root.
+- The repository's `node_modules/` Git ignore rule already covers nested dependency directories.
+  Git ignore rules do not remove the compiler's need for dependency type information.
+
+## Non-goals for this baseline
+
+- No task-planner reasoning is provided by the map itself.
+- No cloud CI/reporting extension is assumed from the local alpha artifacts.
+
+## Milestone risks and limitations
+
+- Package-manager dependency symlinks outside the selected root are not indexed or read by the bounded host.
+- The fallback compiler unit mixes unowned files with conservative defaults.
+- Every fallback-owned JavaScript/JSX-family file receives a portable reason diagnostic and is still
+  analyzed exactly once.
+- Direct in-root project-reference package imports are mapped from static package metadata back to referenced source when declaration outputs are absent. Complex conditional exports and references outside the selected root remain bounded and may be unresolved.
+- Project/toolchain-scoped typed resolution probes, directory listings, symlink mappings, and consumed TypeScript library hashes make warm validation proportional to the compiler-observed semantic closure rather than only the indexed file count. Warm scans remain much faster than fresh scans, but are slower than Milestone 1's incomplete freshness check.
+- Custom extensions are treated as untrusted persistence contributors: their textual symbol facts, names, signatures, documentation, diagnostics, and relation metadata are path-sanitized. Structural file/config paths still must satisfy the public relative-path schemas, and invalid custom records make the scan fail instead of being persisted.
+- Portable alias persistence intentionally drops absolute, Windows-drive, UNC, and parent-traversing
+  targets before host-native resolution. This stricter policy can omit an otherwise in-root
+  parent-relative TypeScript alias; direct relative wildcard targets remain supported.
+- Heuristic/unresolved forward relations retain derived `used-by` inverses for graph traversability.
+  The unresolved endpoint remains machine-visible in either direction, and these relations are
+  excluded from future default compact context unless explicitly requested.
+- Schema v4 redundancy detects ordinary and one-sided coherent corruption, including false compiler
+  ownership and line counts. It is not a cryptographic signature against rewriting every redundant
+  ownership record and integrity hash.
+- Default scans use a separate sequential worker for each compiler unit. Each worker exits before
+  the next unit starts. A local V8 inspector session collects unreachable compiler objects before
+  the result is cloned into the parent; it opens no network port. This releases compiler memory
+  before normalization and persistence, but adds collection and
+  startup overhead, particularly for small projects with many configs. A single large compiler unit
+  can still use substantial memory; there is no fixed heap cap or partial-analysis fallback.
+- Custom analyzers, parsers, and semantic resolvers run in-process to preserve extension behavior.
+  Their memory use is not covered by the default-pipeline resource guarantee. Full JSDoc remains
+  available to custom analyzers; default workers parse only the JSDoc needed for type information.
+- The [alpha.2 release benchmark](../benchmarks/results/release-alpha-2-2026-11-01.md) records the
+  current resource measurements. August source commits were restored with copied installed
+  dependencies; those dependency trees are not claimed to reproduce the August installation.
+- Next.js and NestJS analyzers remain experimental and default-off.
+- Any future Tree-sitter production path is still explicitly off for this milestone.