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

package/AGENTS.md

@@ -0,0 +1,26 @@
+# Agent instructions
+
+## Code navigation
+
+- Use `ai-code-map` to locate relevant symbols when their source location is unknown.
+- Run commands from the project root.
+- Before using the map, run `pnpm exec ai-code-map check`.
+- If the map is missing or stale (exit code 2), run
+  `pnpm exec ai-code-map scan`.
+- Read the beginning of `.ai/code-map/overview.md` only when broader project
+  structure is needed. Skip it for a focused task with a known area of the code.
+- Find symbols with `pnpm exec ai-code-map find 'search words'`.
+- After `find` identifies a relevant symbol, use `pnpm exec ai-code-map read '<stable-id>'`.
+  This reads current source through the map, with two context lines and at most
+  80 source lines per call. Follow the printed continuation only if needed.
+- Reuse IDs and source already returned. Do not repeat `find` for a known symbol
+  or read its entire file just to see that symbol. Expand to a specific dependency
+  only when an unresolved question requires it.
+- Use `pnpm exec ai-code-map show '<stable-id>'` only to answer an unresolved
+  question about symbol relations. Use an ID returned by `find`; do not call
+  `show` merely to redisplay a symbol whose source location is already known.
+- Do not load entire `manifest.json`, `symbols.jsonl`, or `relations.jsonl`
+  files into context. Select only the records relevant to the task.
+- Source code is the source of truth. Check it before making changes.
+- If the map does not help or a command fails, use regular search with `rg`.
+- The map is optional for a simple edit in a known file.

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+## 2026-11-01
+
+### 0.1.0-alpha.3
+
+- Add bounded `context` / `buildSourceContext` packets with current source, direct symbol links, file-level references, and up to four small outgoing dependencies.
+- Add a reproducible token benchmark with fixed budgets, raw usage accounting, and manual paired quality review; accept recursive map exclusions in search commands.
+- Token savings remain experimental: the latest 12-attempt, three-project comparison saved 0.9% overall and failed two paired quality comparisons. This release does not claim savings above 10% or quality non-degradation.
+
+- Add `map` to check freshness and return the complete structural graph in one call, with short references and grouped relation counts.
+
+- Include bounded direct symbol links and test call sites on the first `read` page, with reusable IDs and omission counts.
+
+- Add map-guided `read` / `readSymbolSource` with bounded source pages, freshness checks, and continuation; update and package agent navigation instructions and a reusable Codex skill.
+
+- Improve multiword symbol search with common plural normalization, name-aware ranking, and explicitly labeled partial matches.
+
+- Add compact text `show` with full source ranges, grouped relations, and explicit omission counts.
+- Preserve verbose output through `show --full` and complete records through `show --json`.
+- Add `find` / `findSymbols` for bounded symbol discovery and typo suggestions on failed `show` selectors.
+
 ## 2026-11-01
 
 ### 0.1.0-alpha.2

package/README.md

@@ -9,7 +9,7 @@ AI Code Map is a local, deterministic code understanding layer for TypeScript, J
 - **Compiler-authoritative**: TypeScript compiler is the trusted semantic layer for symbols, references, imports, and types.
 - **Evidence-backed facts**: relations carry a source range, analyzer, classification, and confidence; source code remains authoritative.
 - **No network/telemetry by default**: no outbound upload is part of a standard scan.
-- **Small CLI**: `init`, `scan`, `check`, `show`.
+- **Small CLI**: `init`, `scan`, `check`, `find`, `show`.
 
 ## Quick start
 
@@ -18,17 +18,20 @@ pnpm install
 pnpm exec ai-code-map init
 pnpm exec ai-code-map scan
 pnpm exec ai-code-map check
+pnpm exec ai-code-map find "calculator"
 pnpm exec ai-code-map show Calculator
 ```
 
 ### Exit codes
 
-| Command | Success          | Failure behavior                                    |
-| ------- | ---------------- | --------------------------------------------------- |
-| `init`  | `0`              | invalid configuration or environment errors -> `1`  |
-| `scan`  | `0`              | parser errors with `--strict` -> `3`, otherwise `0` |
-| `check` | `0` when current | stale map -> `2`, missing map -> `2`                |
-| `show`  | `0`              | no match -> `1`                                     |
+| Command | Success                   | Failure behavior                                           |
+| ------- | ------------------------- | ---------------------------------------------------------- |
+| `init`  | `0`                       | invalid configuration or environment errors -> `1`         |
+| `scan`  | `0`                       | parser errors with `--strict` -> `3`, otherwise `0`        |
+| `check` | `0` when current          | stale map -> `2`, missing map -> `2`                       |
+| `map`   | `0` when current          | stale, missing, or invalid map -> `2`; other errors -> `1` |
+| `show`  | `0`                       | no match -> `1`                                            |
+| `find`  | `0`, including no matches | invalid query or limit -> `1`                              |
 
 ## CLI command matrix
 
@@ -59,6 +62,38 @@ Compares the persisted `manifest.json` against current state and config:
 
 Returns `Current` or `Stale` with machine-readable reasons and change lists.
 
+### `ai-code-map map`
+
+Prints the complete structural map in one call. It checks freshness internally;
+no separate `check` call is needed. If the map is missing, stale, or invalid, it
+returns exit code 2 without printing the graph. Run `scan` to rebuild it.
+
+```bash
+pnpm exec ai-code-map map
+pnpm exec ai-code-map map --json
+```
+
+The output includes every indexed file and symbol, plus every relation endpoint.
+Files, symbols, and other endpoints receive short references (`f1`, `s1`, `e1`)
+used in the relation table. Symbols also show their stable IDs and source lines.
+Use the stable ID with `read`; short references apply only to this output and may
+change after a rescan.
+
+Relations are grouped by source, type, and evidence classification. A target such
+as `s2*3` represents three occurrence records. All classifications are retained,
+including heuristic and derived links; these must not be interpreted as exact
+calls. Source text, signatures, facts, and per-occurrence evidence are excluded.
+Use `show --json` for detailed evidence and `read` for current source.
+
+There is no pagination or silent row limit. The `End of map` marker confirms that
+the CLI reached the end; a calling tool may still truncate a large response.
+The whole map can exceed an agent's output or context limit. One call does not
+guarantee fewer tokens than focused navigation. Redirect to a file when needed:
+
+```bash
+pnpm exec ai-code-map map > /tmp/project-map.txt
+```
+
 ### `ai-code-map show <selector>`
 
 Displays indexed symbol(s) by:
@@ -68,7 +103,105 @@ Displays indexed symbol(s) by:
 - `path` or `path#name`
 - exact symbol name
 
-Shows symbol details plus inbound/outbound relation IDs and confidence.
+Default text is compact: up to five symbols, full source ranges, signatures capped at 240
+characters, and up to 12 relation groups across the response. Repeated relations of the same
+direction, type, and endpoint are grouped with occurrence counts. Internal links come first.
+Heuristic/unresolved relations, derived inverse links, containment/export edges, and references
+that duplicate a more specific relation are filtered. Each symbol reports shown/omitted groups
+and filtered record counts. Documentation and facts are available in the full view.
+
+- `--limit <1..50>` changes the total relation-group limit for compact text.
+- `--full` preserves the previous verbose text view.
+- `--json` preserves the complete `ShowResult`, including all relation evidence.
+
+These are row and signature limits, not a token budget. A failed selector suggests up to five
+indexed candidates; it never silently selects a different symbol.
+
+### `ai-code-map find <query>`
+
+Searches indexed symbol names and paths. Quote multiword queries, for example
+`ai-code-map find "manager change"`. Exact names/IDs rank first, followed by prefix/substring,
+word matches, and bounded typo matching. Word matching normalizes common English plurals
+and favors matches in symbol names over paths. Whitespace-separated queries with at least three distinct words
+can also return partial matches: at least two words and half the query must match, including
+one word in the symbol name. These rank below full matches and typo hints. Partial results
+show which normalized terms were unmatched. This is lexical search, not semantic search;
+`read` is not treated as a synonym of `viewed`. For example, `notification mark read` can
+find `markNotificationsAsViewed` through `notification` and `mark`.
+
+Read the selected symbol with `ai-code-map read '<id>'`. Use `show` when symbol relations are needed.
+
+Results include stable IDs usable by `show`, kinds, and full source ranges. The default is ten
+matches; `--limit <1..50>` adjusts this. `--json` returns `{ query, total, truncated, matches }`.
+No matches is a successful empty search. Use `rg` for source text or symbols outside the index.
+
+### `ai-code-map context <query>`
+
+Collects current source for a quoted lexical query or exact symbol ID and its direct
+exact/framework-derived graph neighbors in one call. It checks freshness first;
+missing or stale maps return exit code 2. No model, embeddings, or network is used.
+
+The default selects up to three matches and favors behavior over partial type matches.
+For partial queries, it checks missing query words in the current bodies of up to
+50 lexical candidates. It expands the strongest callable matches when source
+evidence distinguishes them. This lexical ranking does not infer intent or synonyms.
+An exact name or ID takes precedence. Each selected match expands once using the
+bounded navigation rules of `read`; reference-only class neighbors are counted as
+omitted, so a namespace reference does not load every method. Explicit class
+queries remain supported. Source windows include two context lines.
+Up to four incoming file-level call/reference sites are also included, such as
+route registrations outside any function. Files of at most 80 lines are read in
+full; larger files use eight lines on each side of the mapped site. These windows
+share the same budgets and source validation as symbol windows.
+After those windows, remaining budget can include up to four small functions or
+values referenced by direct outgoing neighbors. Their bodies must be at most 80
+lines; calls take priority over references. This extra step does not recurse or
+expand incoming callers, and cannot displace the primary source windows.
+Overlapping and adjacent ranges in the same file are emitted together with original
+line numbers. Shared budgets are 800 source lines and 32,000 source characters
+(including line separators); headers and bounded metadata are additional.
+
+Options: `--seeds <1..5>`, `--max-lines <1..2000>`, `--max-chars <256..64000>`,
+`--json`. Partial lexical matches keep their unmatched terms. Omitted source ranges,
+other search-match count, and omitted navigation entries are explicit. Test call
+sites are hints, not proof of coverage. A packet is a bounded local neighborhood,
+not a claim to contain every dependency or every fact needed for the task.
+
+For example: `ai-code-map context 'notification mark read'`. Reuse the returned
+source and read only a specific missing range or dependency next. The existing
+`find`, `read`, and `show` commands remain available for narrower requests.
+
+### `ai-code-map read <id>`
+
+Reads current source using an exact stable ID returned by `find`. Includes two lines
+of context on each side of the symbol. Output is numbered and limited to 80 source
+lines by default; `--limit <1..200>` changes the page size. Long symbols provide an
+explicit `--offset` continuation within the same window. Reuse what you have already
+read; follow a continuation or another symbol only for an unresolved question.
+
+The first page also lists up to eight direct symbol neighbors and four exact incoming
+call sites in test paths (`*.test.*`, `*.spec.*`, or `__tests__/`). Neighbors include
+reusable IDs, source ranges, direction, relation type, and evidence classification.
+Repeated neighbors are merged. Heuristic and derived inverse relations, containment,
+exports, and unresolved or external endpoints are excluded. Test paths are navigation
+hints, not proof of test coverage. Missing entries do not prove that no tests exist.
+The block stays below 4,000 compact JSON characters and reports eligible entries
+omitted by its limits. Continuation pages do not repeat it. Use `show '<id>'` for
+more relations when needed.
+
+The file must be inside the project root, regular, and match its indexed hash.
+Changed files require `scan` before reading. Source pages over 12,000 characters are
+rejected: reduce `--limit`, or use targeted source search for an oversized single line.
+`--json` includes source, range, truncation, continuation metadata, and first-page
+`navigation`. Source is read
+on demand and is not added to persisted map artifacts. Run `check` before navigation;
+this command validates the selected source file, not every project dependency.
+
+The packaged `AGENTS.md` describes this navigation workflow. A reusable Codex skill
+is included at `skills/ai-code-map/SKILL.md`. Copy the `ai-code-map` folder to your
+Codex skills directory and invoke `$ai-code-map`. It guides combined context retrieval,
+relation lookups, and targeted fallback for unindexed tests; it also supports older
+CLI versions without `read` by using the returned source ranges directly.
 
 ## Generated artifacts