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

package/docs/api.md

@@ -0,0 +1,103 @@
+# 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
+- `computeManifestIntegrityHash(manifest) -> string`
+  - computes the canonical code-point-ordered manifest integrity hash used by persistence and tests
+- `showSymbol(map, selector) -> ShowResult`
+  - selectors: exact ID, `kind:name`, `path#name`, exact name/path
+
+## 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`
+- `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.
+- Natural-language CLI commands or `context "task" --budget`.
+- 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,70 @@
+# Known limitations and backlog
+
+## In-scope alpha
+
+- CLI commands are limited to `init`, `scan`, `check`, `show`.
+- `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.
+
+## 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.