ai-code-map 0.1.0-alpha.2 → 0.1.0-alpha.3

package/docs/api.md

@@ -29,10 +29,58 @@ one-sided coherent corruption; a rescan is required.
   - 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
 
@@ -68,7 +116,8 @@ The package exports major record/contract types including:
 - `CodeMap`, `CodeMapConfig`, `ManifestRecord`, `ProjectRecord`
 - `FileRecord`, `SymbolRecord`, `RelationRecord`, `DiagnosticRecord`
 - `CompilerUnitRecord`, `ProducerRecord`, `SemanticInputRecord`, `ArtifactIntegrityRecord`
-- `ScanResult`, `FreshnessResult`, `ShowResult`
+- `ScanResult`, `FreshnessResult`, `ShowResult`, `ShowFormatOptions`
+- `SymbolSearchResult`, `SymbolSearchOptions`, `SymbolSearchMatch`
 - `ScanOptions`, `LoadCodeMapOptions`, `AnalysisContext`
 
 ## Example

package/docs/backlog.md

@@ -35,7 +35,7 @@
 ## Explicitly not core
 
 - LLMs, embeddings, API keys, network calls, or telemetry in deterministic map generation.
-- Natural-language CLI commands or `context "task" --budget`.
+- 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.

package/docs/limitations.md

@@ -2,7 +2,7 @@
 
 ## In-scope alpha
 
-- CLI commands are limited to `init`, `scan`, `check`, `show`.
+- 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.
@@ -31,6 +31,18 @@
 - 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.

package/docs/post-alpha-roadmap.md

@@ -287,6 +287,22 @@ Compare at least:
 
 Use the same model, instructions, tool access, repository revision, and context ceiling. Randomize task order where practical and keep evaluators blind to the arm.
 
+### Pilot setup lessons (2026-11-01)
+
+- Check CLI/model compatibility before collecting task results. Codex CLI `0.135.0` rejected
+  `gpt-6-astra`; the pilot used CLI `0.166.0` in a temporary directory without changing the global
+  installation. Preserve the selected model when repairing the runner.
+- Use physical dependency copies inside each temporary project root, preserving internal package
+  symlinks. An external `node_modules` symlink increased unresolved-import diagnostics and invalidated
+  the initial setup. After replacing it, all six map companion artifacts matched the reference
+  byte for byte. Source discovery must still exclude dependency files.
+- Fix tasks, scoring criteria, repeats, and a stopping budget before measured runs. Record failed
+  setup attempts separately; do not hide their overhead or mix them with valid A/B results. Keep
+  the original deadline when repairing the environment.
+- Record actual input, cached-input, and output usage. Cached input is a subset of input, not an
+  additional token count. Report map construction separately when using prebuilt maps.
+- Keep private source excerpts and raw agent logs out of public benchmark reports.
+
 ### Primary metrics
 
 - input and output tokens measured by the actual model/tokenizer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-code-map",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Local, deterministic semantic code maps for AI coding agents",
   "type": "module",
   "sideEffects": false,
@@ -39,6 +39,8 @@
     "docs",
     "examples",
     "README.md",
+    "AGENTS.md",
+    "skills",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -74,6 +76,7 @@
     "schema:generate": "node --import tsx scripts/generate-schemas.ts",
     "schema:check": "node --import tsx scripts/generate-schemas.ts --check",
     "benchmark": "node --import tsx scripts/benchmark-parsers.ts",
-    "benchmark:real-world": "node --import tsx scripts/benchmark-real-world.ts"
+    "benchmark:real-world": "node --import tsx scripts/benchmark-real-world.ts",
+    "benchmark:tokens": "node --import tsx scripts/benchmark-tokens.ts"
   }
 }

package/skills/ai-code-map/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ai-code-map
+description: Use when tracing TypeScript or JavaScript behavior in a project indexed by ai-code-map, or when the user requests map-guided navigation.
+---
+
+# Retrieve source through the map
+
+Run from the source project root with its installed CLI. Do not install or upgrade
+it just to navigate. Source establishes behavior; graph relations are navigation
+hints, and missing edges do not prove absence.
+
+For an unknown flow, start with `ai-code-map context 'action subject words'`.
+Include the action as well as the subject, for example `notification mark read`.
+This command checks freshness and returns matching
+source plus direct neighbors, merging ranges under one shared budget. A separate
+`check` or overview is unnecessary before it. Partial matches name unmatched words;
+judge relevance from the returned source.
+
+Use that packet to answer or identify a specific missing fact. Reuse its source.
+Read a printed omitted range only if it matters. For one dependency outside the
+packet, use `read '<stable-id>'` or its bounded source range. If its ID and source
+location are unknown, use `find 'qualified symbol name'` first. Do not use another
+`context` call merely to read a helper: it also expands callers and neighbors.
+Batch independent
+reads; combine needed ranges in the same file. Avoid traversing every neighbor or
+splitting one useful file window into many tiny symbol reads.
+
+Use targeted `rg` for file-level facts such as route registration, configuration
+and test discovery, or for a failed/irrelevant lookup. Discover paths with
+`rg --files -g 'pattern'` before reading them. Use
+`show '<id>'` only for an unresolved relation question. Do not dump the complete
+map for an ordinary source task. Stop when the requested claims have evidence.
+In the answer, connect each requested entry point to its inputs, state changes,
+error path and caller effects. Keep navigation-status commentary brief.
+
+If `context` is unavailable, check freshness once, then use `find` and `read` or
+bounded source ranges. If stale, scan only when writing generated artifacts is
+allowed; otherwise use source search. Cite original file and line numbers.
+Do not claim token savings without a measured comparison.