@raymondchins/agentmap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raymond Surya Chin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,439 @@
+# agentmap
+
+**The repo map your coding agent is _forced_ to use.**
+
+A queryable, ranked code-relationship map for TypeScript/JavaScript repos — personalized
+PageRank importance, Aider-style symbol ranking, a token-budgeted digest, and a single
+`--any` router (file → symbol → feature → live git-grep) — wired straight into the agent
+loop so it actually gets used, not just published.
+
+<!-- badges (placeholder — wire up once published) -->
+[![npm](https://img.shields.io/npm/v/@raymondchins/agentmap)](https://www.npmjs.com/package/@raymondchins/agentmap)
+[![CI](https://img.shields.io/badge/CI-pending-lightgrey)](#)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](#)
+
+> One file, one dependency (`ts-morph`). No vector DB, no embedding API, no server.
+> `npx @raymondchins/agentmap --any <query>` and you have a ranked answer.
+
+---
+
+## Why it's different
+
+Most "repo context" tools are one-shot: they pack the repository (or a slice of it) into a
+prompt and stop there. agentmap is a **queryable, ranked, and self-refreshing** map that an
+agent can interrogate flag-by-flag — and, crucially, is **wired into the agent loop** via a
+post-commit auto-refresh and a `PreToolUse` hook that nudges the agent to use the map
+*before* it falls back to serial grep.
+
+| | **agentmap** | Aider repo map | RepoMapper | Repomix | code2prompt |
+| --- | --- | --- | --- | --- | --- |
+| **Ranking algorithm** | Personalized PageRank (file + symbol graphs) | PageRank (graph ranking) | Importance heuristics | None (file order) | None (file order) |
+| **Languages** | TS/JS (via ts-morph) | Many (tree-sitter) | Many (tree-sitter) | Language-agnostic (text) | Language-agnostic (text) |
+| **Token-budget output** | Yes — `--map [--tokens N]` ranked digest | Yes (built into Aider's context) | Partial | Yes (size caps) | Yes (templates/caps) |
+| **Agent-loop integration** | **Yes — post-commit auto-refresh + PreToolUse hook** | In-process (Aider only) | No | No | No |
+| **Dependencies** | `ts-morph` only | Python + tree-sitter stack | Python + tree-sitter | Node | Rust binary |
+| **Install** | `npx @raymondchins/agentmap` | `pip install aider` | `pip install` | `npx`/global | `cargo`/binary |
+
+What that table is **not** claiming: agentmap is TS/JS-only (the others are multi-language),
+and it's a **file-level import graph**, not a full call-site/reference resolver (see
+[Scope & limitations](#scope--limitations)). The differentiators are narrow and honest:
+**(1)** the `--any` router, and **(2)** the agent-loop wiring. Everything else is table stakes.
+
+---
+
+## Quickstart
+
+No install needed:
+
+```bash
+npx @raymondchins/agentmap --any <query>
+```
+
+…or run it directly from a checkout:
+
+```bash
+node repomap.mjs --any <query>
+```
+
+The first run builds and caches the map to `.claude/repomap.json` (add it to
+`.gitignore`). Subsequent runs serve the cache when the tree is clean and `HEAD` is
+unchanged, and silently rebuild from disk when there are uncommitted `.ts/.tsx/.js/...`
+edits — so queries always reflect your in-flight work.
+
+Run with no flag to build + print a one-line summary:
+
+```
+$ node repomap.mjs
+repomap: 154 files | 4 features | top hub: lib/utils.ts (deg 52, pr 0.105171)
+```
+
+---
+
+## The `--any` router
+
+One flag, no flag-picking. `--any <query>` resolves your query through a cascade and
+returns the first layer that hits:
+
+```
+--any <query>
+   │
+   ├─ 1. FILE     exact path → unique basename → unique substring
+   ├─ 2. SYMBOL   exported name contains the query (across all files)
+   ├─ 3. FEATURE  app/-router feature name contains the query
+   └─ 4. CONTENT  live `git grep` (tracked + untracked) — never stale
+```
+
+Layers 1–3 read the cached structural map (fast, ranked). Layer 4 is a **live disk read**
+via `git grep -F`, so raw strings, copy, Tailwind classes, and config values the structural
+graph never indexes still resolve instead of coming up empty.
+
+**Symbol hit** (query resolved to a symbol → full block):
+
+```
+$ node repomap.mjs --any cn
+[structure] 1 symbol, 0 feature match for "cn"
+  lib/utils.ts → cn (FunctionDeclaration)
+```
+
+**Ambiguous file hit** (query matched multiple files → narrow it):
+
+```
+$ node repomap.mjs --any utils
+[structure] "utils" matched 3 files — narrow it:
+  lib/utils.ts
+  lib/db/utils.ts
+  tests/prompts/utils.ts
+```
+
+**Content fallback** (no file/symbol/feature match → live git-grep):
+
+```
+$ node repomap.mjs --any streamText
+[content] 13 lines:
+app/(chat)/api/chat/route.ts:8:  streamText,
+app/(chat)/api/chat/route.ts:194:        const result = streamText({
+artifacts/code/server.ts:1:import { streamText } from "ai";
+artifacts/code/server.ts:18:    const { fullStream } = streamText({
+artifacts/code/server.ts:40:    const { fullStream } = streamText({
+artifacts/sheet/server.ts:1:import { streamText } from "ai";
+artifacts/sheet/server.ts:11:    const { fullStream } = streamText({
+```
+
+---
+
+## Commands
+
+Every snippet below is **verbatim output** from running agentmap against the public
+154-file Next.js repo [vercel/ai-chatbot](https://github.com/vercel/ai-chatbot) (sha 2becdb4).
+
+### `--any <q>` — the router (file → symbol → feature → live content)
+
+See [The `--any` router](#the---any-router) above. Default first move for any
+"where/what/who" question.
+
+### `--find <q>` — reuse-before-rebuild symbol search
+
+Find every exported symbol whose name contains the query. Use it before writing a new util
+or component to check what already exists.
+
+```
+$ node repomap.mjs --find Message
+find "Message": 55 match
+  hooks/use-messages.tsx → useMessages (FunctionDeclaration)
+  lib/errors.ts → getMessageByErrorCode (FunctionDeclaration)
+  lib/types.ts → messageMetadataSchema (VariableDeclaration)
+  lib/types.ts → MessageMetadata (TypeAliasDeclaration)
+  lib/types.ts → ChatMessage (TypeAliasDeclaration)
+  lib/utils.ts → convertToUIMessages (FunctionDeclaration)
+  lib/utils.ts → getTextFromMessage (FunctionDeclaration)
+  tests/helpers.ts → generateTestMessage (FunctionDeclaration)
+  app/(chat)/actions.ts → generateTitleFromUserMessage (FunctionDeclaration)
+  …
+```
+
+### `--relates <path>` — blast radius + transitive relevance
+
+The file's own block (exports / imports / direct dependents) **plus** a random-walk
+relevance list (personalized PageRank on the bidirectional import graph) — the files most
+related to the target, transitively, not just its direct importers.
+
+```
+$ node repomap.mjs --relates lib/db/schema.ts
+relates: lib/db/schema.ts  (pr 0.073744)
+exports (14): user(VariableDeclaration), User(TypeAliasDeclaration), chat(VariableDeclaration), Chat(TypeAliasDeclaration), message(VariableDeclaration), DBMessage(TypeAliasDeclaration), …
+imports (0): —
+dependents (21): hooks/use-active-chat.tsx, lib/types.ts, lib/utils.ts, components/chat/artifact.tsx, components/chat/message.tsx, lib/db/queries.ts, app/(chat)/api/chat/route.ts, …
+related (random-walk relevance):
+  lib/utils.ts (0.0476)
+  lib/types.ts (0.0376)
+  components/chat/artifact.tsx (0.0372)
+  components/chat/icons.tsx (0.0264)
+  components/chat/message.tsx (0.0237)
+  lib/db/queries.ts (0.0225)
+  app/(chat)/api/chat/route.ts (0.0218)
+  …
+```
+
+### `--feature <name>` — files that make up a feature
+
+Resolves a Next.js `app/`-router feature to its file set, plus the external files that
+depend on it.
+
+```
+$ node repomap.mjs --feature api
+feature "api": 11 files
+  app/(chat)/api/chat/route.ts
+  app/(chat)/api/chat/schema.ts
+  app/(chat)/api/document/route.ts
+  app/(chat)/api/history/route.ts
+  app/(chat)/api/messages/route.ts
+  app/(chat)/api/models/route.ts
+  app/(chat)/api/suggestions/route.ts
+  app/(chat)/api/vote/route.ts
+  app/(auth)/api/auth/guest/route.ts
+  app/(chat)/api/files/upload/route.ts
+  app/(chat)/api/chat/[id]/stream/route.ts
+external dependents (0): —
+```
+
+### `--features` — list features by size
+
+```
+$ node repomap.mjs --features
+features (4):
+  api (11 files)
+  login (1 files)
+  register (1 files)
+  chat (1 files)
+```
+
+### `--hubs` — most important files (PageRank)
+
+The files that matter most, ranked by PageRank importance (raw dependent degree shown
+alongside).
+
+```
+$ node repomap.mjs --hubs
+repomap: 154 files (sha 2becdb4)
+hubs (PageRank importance):
+  lib/utils.ts (deg 52, pr 0.105171)
+  lib/db/schema.ts (deg 21, pr 0.073744)
+  lib/types.ts (deg 23, pr 0.067589)
+  components/chat/artifact.tsx (deg 15, pr 0.036882)
+  components/chat/icons.tsx (deg 27, pr 0.035378)
+  lib/errors.ts (deg 9, pr 0.032787)
+  lib/db/queries.ts (deg 14, pr 0.030085)
+  …
+```
+
+### `--symbols [N]` — top ranked symbols (Aider-style)
+
+The most important individual symbols across the repo, ranked by the identifier graph
+(defaults to 30).
+
+```
+$ node repomap.mjs --symbols 10
+top 10 ranked symbols (Aider-style):
+  0.109902  lib/utils.ts → cn (FunctionDeclaration)
+  0.036013  lib/types.ts → ChatMessage (TypeAliasDeclaration)
+  0.025686  components/chat/artifact.tsx → ArtifactKind (TypeAliasDeclaration)
+  0.022461  lib/errors.ts → ChatbotError (ClassDeclaration)
+  0.021068  lib/types.ts → CustomUIDataTypes (TypeAliasDeclaration)
+  0.020872  lib/db/schema.ts → Document (TypeAliasDeclaration)
+  0.020555  components/ai-elements/suggestion.tsx → Suggestion (VariableDeclaration)
+  0.020555  lib/db/schema.ts → Suggestion (TypeAliasDeclaration)
+  0.018124  lib/db/schema.ts → DBMessage (TypeAliasDeclaration)
+  0.015034  lib/errors.ts → ErrorCode (TypeAliasDeclaration)
+```
+
+### `--map [--tokens N] [--focus <path>]` — token-budgeted ranked digest
+
+The token-budgeted digest (Aider's killer feature): a ranked, files-and-symbols summary
+that fits a token budget. Default budget is 8192 (1024 with `--focus`). `--focus <path>`
+personalizes the ranking toward a file you're working on.
+
+```
+$ node repomap.mjs --map --tokens 400
+# repomap (154 files, sha 2becdb4) — focus: global, budget ~400 tok
+
+lib/utils.ts:
+  cn (FunctionDeclaration)
+  generateUUID (FunctionDeclaration)
+
+lib/types.ts:
+  ChatMessage (TypeAliasDeclaration)
+  CustomUIDataTypes (TypeAliasDeclaration)
+  ChatTools (TypeAliasDeclaration)
+  Attachment (TypeAliasDeclaration)
+
+components/chat/artifact.tsx:
+  ArtifactKind (TypeAliasDeclaration)
+  UIArtifact (TypeAliasDeclaration)
+  Artifact (VariableDeclaration)
+
+lib/errors.ts:
+  ChatbotError (ClassDeclaration)
+  ErrorCode (TypeAliasDeclaration)
+
+lib/db/schema.ts:
+  Document (TypeAliasDeclaration)
+  Suggestion (TypeAliasDeclaration)
+  DBMessage (TypeAliasDeclaration)
+
+# ~387 tokens (14 files shown)
+```
+
+Focused on a working file — the ranking re-centers on what `lib/db/queries.ts` actually touches:
+
+```
+$ node repomap.mjs --map --focus lib/db/queries.ts --tokens 350
+# repomap (154 files, sha 2becdb4) — focus: lib/db/queries.ts, budget ~350 tok
+
+lib/utils.ts:
+  cn (FunctionDeclaration)
+  generateUUID (FunctionDeclaration)
+  getDocumentTimestampByIndex (FunctionDeclaration)
+  fetcher (VariableDeclaration)
+  getTextFromMessage (FunctionDeclaration)
+  convertToUIMessages (FunctionDeclaration)
+  fetchWithErrorHandlers (FunctionDeclaration)
+  sanitizeText (FunctionDeclaration)
+
+lib/db/schema.ts:
+  DBMessage (TypeAliasDeclaration)
+  Suggestion (TypeAliasDeclaration)
+  Document (TypeAliasDeclaration)
+  Chat (TypeAliasDeclaration)
+  User (TypeAliasDeclaration)
+  chat (VariableDeclaration)
+  document (VariableDeclaration)
+  message (VariableDeclaration)
+
+lib/errors.ts:
+  ChatbotError (ClassDeclaration)
+  ErrorCode (TypeAliasDeclaration)
+
+# ~324 tokens (8 files shown)
+```
+
+### `--print` — full map as JSON
+
+Dumps the cached map (`hubs`, `features`, `rankedSymbols`, `files`) as one JSON object —
+for piping into other tools.
+
+```
+$ node repomap.mjs --print | jq '.hubs[0]'
+"lib/utils.ts (deg 52, pr 0.105171)"
+```
+
+---
+
+## The agent loop (the actual point)
+
+A repo map only helps if the agent uses it. agentmap ships two hooks (in [`./hooks/`](./hooks/))
+that close the loop: the map refreshes itself after every commit, and the agent gets nudged
+to query the map before it serial-greps.
+
+### 1. Auto-refresh on commit
+
+[`hooks/post-commit`](./hooks/post-commit) rebuilds `.claude/repomap.json` after each
+commit, detached + silenced so it never slows the commit. It skips during
+rebase/merge/cherry-pick and no-ops if Node is missing.
+
+```bash
+# from your repo root
+cp hooks/post-commit .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+The hook auto-locates the builder: a local `repomap.mjs`, then `scripts/repomap.mjs`, then
+the installed `agentmap` binary, then `npx @raymondchins/agentmap`.
+
+### 2. Force the agent to use it — `PreToolUse` hook
+
+[`hooks/repomap-nudge.mjs`](./hooks/repomap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
+hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
+reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
+denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
+sweeps — so it's high-signal, not nagging.
+
+Wire it up in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          { "type": "command", "command": "node ./hooks/repomap-nudge.mjs" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That's the "forced to use it" in the tagline: the map stays current on its own, and the
+agent is steered to it the moment it reaches for a dependency-shaped grep.
+
+---
+
+## Scope & limitations
+
+Honesty first — this is deliberately a small, sharp tool, not a universal code-graph.
+
+- **TS/JS only, by design.** Built on `ts-morph`. No Python, Go, Rust, etc. If your repo
+  isn't TypeScript/JavaScript, use a tree-sitter-based tool instead.
+- **File-level import graph, not a full reference graph.** Edges come from static
+  `import` / re-export declarations and the named symbols crossing them. It does **not**
+  do call-site or full reference resolution — `--relates` tells you which files import a
+  module, not every line that calls a given function.
+- **PageRank + symbol ranking are real and implemented** (damping 0.85, deterministic
+  power iteration; personalized variants for `--relates` and `--map --focus`). The symbol
+  ranking is a faithful port of Aider's identifier-graph approach (credit:
+  [Aider](https://github.com/Aider-AI/aider), Apache-2.0).
+- **Feature detection assumes the Next.js `app/` router.** `--feature` / `--features`
+  derive features from the first real route segment under `app/` (or `src/app/`), skipping
+  route groups `(...)`, dynamic `[...]`, and parallel `@...` segments. Repos without an
+  `app/` directory simply report zero features — every other command still works.
+- **Token counts are estimates** (`chars / 4`), not a real BPE tokenizer. Treat
+  `--map`/`--tokens` budgets as approximate (±10%).
+- The PreToolUse hook is **Claude Code-specific** (it speaks Claude Code's hook JSON). The
+  post-commit hook is generic git.
+
+---
+
+## Benchmark
+
+Against the public **154-file Next.js repo (vercel/ai-chatbot, sha 2becdb4)**:
+
+- **70.3% fewer tokens across 3 scenarios (5598 → 1664 tokens)**:
+  - **A. Understand file deps** (`lib/utils.ts`): baseline 583 tok → agentmap 517 tok (11.3% saved)
+  - **B. Find symbol** (`ChatMessage`): baseline 1950 tok → agentmap 20 tok (99% saved)
+  - **C. Repo overview** (tree + 3 hub files): baseline 3065 tok → agentmap 1127 tok (63.2% saved)
+- Cold build (parse + PageRank + symbol graph): **~1.2s**. Warm cached query (`--hubs`,
+  clean tree): **~0.2s**.
+
+Caveat: these numbers measure context efficiency (tokens sent to the model per task), **not**
+end-to-end retrieval accuracy — there's no "did the agent fix the bug faster" eval yet.
+
+Full methodology, commands, and caveats: **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. High-value directions:
+
+- An end-to-end retrieval/accuracy eval (the benchmark is context-efficiency only today).
+- A real tokenizer behind the `--map` budget.
+- Hardening feature detection for non-`app/`-router layouts.
+
+Keep the dependency footprint minimal — `ts-morph` is the only runtime dep, and that's a
+feature.
+
+## License
+
+[MIT](./LICENSE). Symbol-ranking algorithm credit: [Aider](https://github.com/Aider-AI/aider) (Apache-2.0).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@raymondchins/agentmap",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "The repo map your coding agent is forced to use. A queryable, ranked ts-morph code-relationship map for TypeScript/JavaScript repos — PageRank hubs, Aider-style symbol ranking, a token-budgeted digest, and a single --any router (file → symbol → feature → live git-grep), wired into the agent loop via post-commit auto-refresh and a PreToolUse hook.",
+  "type": "module",
+  "bin": {
+    "agentmap": "./repomap.mjs"
+  },
+  "main": "repomap.mjs",
+  "files": [
+    "repomap.mjs"
+  ],
+  "scripts": {
+    "map": "node repomap.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ts-morph": "28.0.0"
+  },
+  "keywords": [
+    "repo-map",
+    "repomap",
+    "code-map",
+    "ts-morph",
+    "typescript",
+    "javascript",
+    "pagerank",
+    "static-analysis",
+    "ast",
+    "code-graph",
+    "dependency-graph",
+    "ai-agent",
+    "coding-agent",
+    "llm",
+    "claude",
+    "aider",
+    "context"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raymondchins/agentmap.git"
+  },
+  "homepage": "https://github.com/raymondchins/agentmap#readme",
+  "bugs": {
+    "url": "https://github.com/raymondchins/agentmap/issues"
+  },
+  "author": "Raymond Surya Chin",
+  "license": "MIT"
+}

package/repomap.mjs

@@ -0,0 +1,461 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// ============================================================================
+//  agentmap — the repo map your coding agent is *forced* to use.
+//
+//  A ts-morph code-relationship map for TypeScript/JavaScript repos. Unlike
+//  one-shot "pack the repo into a prompt" tools, this is a QUERYABLE, RANKED
+//  map: PageRank importance (ported from Aider's repo map), Aider-style
+//  symbol ranking, a token-budgeted `--map` digest, and a single `--any`
+//  router (file → symbol → feature → live git-grep) — wired into the agent
+//  loop via a post-commit auto-refresh + a PreToolUse hook.
+//
+//  Near-zero deps (ts-morph only). Runs in the target repo's cwd.
+//  Algorithm credit: Aider's repo map (Apache-2.0) — github.com/Aider-AI/aider
+// ============================================================================
+import { Project } from "ts-morph";
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { execSync, execFileSync } from "node:child_process";
+
+const MAP = ".claude/repomap.json";
+const SCHEMA_VERSION = 2;
+const sh = (c) => { try { return execSync(c, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; } };
+
+// Live content search for the --any fallback. `git grep` over tracked +
+// untracked files (skips gitignored paths like node_modules). Reads DISK, so
+// never stale. -F = fixed-string so literals like "bg-[#faf8f2]" aren't regex.
+const contentSearch = (q) => {
+  try {
+    return execFileSync("git", ["grep", "-F", "--untracked", "-n", "-i", "-I", "-e", q, "--", ".", ":!.claude/repomap.json"], { encoding: "utf8" }).trim();
+  } catch { return ""; }
+};
+const currentSha = () => sh("git rev-parse --short HEAD");
+const dirtyCount = () =>
+  sh("git status --porcelain").split("\n").filter(Boolean).filter((l) => {
+    let p = l.slice(3);                                  // strip "XY " status prefix
+    if (p.includes(" -> ")) p = p.split(" -> ").pop();   // rename: keep the new path
+    p = p.replace(/^"|"$/g, "");                         // unquote space/special paths
+    return /\.(ts|tsx|mjs|cjs|jsx|js)$/.test(p);
+  }).length;
+const tokEst = (s) => Math.ceil((s || "").length / 4); // rough chars/4 estimate
+
+// Feature = first real route segment under app/ (or src/app/), skipping route
+// groups (parens), dynamic segments ([id]) and parallel routes (@slot).
+function featureOf(path) {
+  const m = path.match(/(?:^|.*\/)(?:src\/)?app\/(.+)/);
+  if (!m) return null;
+  for (const p of m[1].split("/").slice(0, -1)) {
+    if (p.startsWith("(") || p.startsWith("[") || p.startsWith("@")) continue;
+    return p;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Personalized PageRank — dependency-free power iteration. Deterministic
+// (stable node order, no PRNG). Edges = [{from, to, weight}]. Rank flows
+// from→to, so with importer→imported edges, heavily-imported hubs rank high.
+// Dangling-node mass + teleport both go to the personalization vector
+// (matches Aider's `dangling=personalization`). Returns { node: score }.
+// ---------------------------------------------------------------------------
+function pagerank(nodes, edges, { personalization = null, damping = 0.85, tol = 1e-6, maxIter = 100 } = {}) {
+  const N = nodes.length;
+  if (N === 0) return {};
+  const idx = new Map(nodes.map((n, i) => [n, i]));
+  const outW = new Float64Array(N);
+  const adj = Array.from({ length: N }, () => []);
+  for (const e of edges) {
+    const a = idx.get(e.from), b = idx.get(e.to);
+    if (a === undefined || b === undefined || a === b) continue; // skip self-loops
+    const w = e.weight > 0 ? e.weight : 1;
+    adj[a].push([b, w]); outW[a] += w;
+  }
+  // teleport vector p (normalized personalization, or uniform)
+  const p = new Float64Array(N);
+  if (personalization) {
+    let s = 0;
+    for (const [k, v] of Object.entries(personalization)) {
+      const i = idx.get(k);
+      if (i !== undefined && v > 0) { p[i] = v; s += v; }
+    }
+    if (s === 0) p.fill(1 / N); else for (let i = 0; i < N; i++) p[i] /= s;
+  } else p.fill(1 / N);
+  let r = Float64Array.from(p);
+  for (let iter = 0; iter < maxIter; iter++) {
+    let dangling = 0;
+    for (let i = 0; i < N; i++) if (outW[i] === 0) dangling += r[i];
+    const next = new Float64Array(N);
+    for (let i = 0; i < N; i++) next[i] = (1 - damping) * p[i] + damping * dangling * p[i];
+    for (let i = 0; i < N; i++) {
+      if (outW[i] === 0) continue;
+      const ri = damping * r[i];
+      for (const [j, w] of adj[i]) next[j] += ri * (w / outW[i]);
+    }
+    let diff = 0;
+    for (let i = 0; i < N; i++) diff += Math.abs(next[i] - r[i]);
+    r = next;
+    if (diff < tol) break;
+  }
+  const out = {};
+  for (let i = 0; i < N; i++) out[nodes[i]] = r[i];
+  return out;
+}
+
+// Aider-style identifier edge-weight multipliers. `mentioned` = focus/query
+// idents (boosted). Rarity is approximated by the >5-definers penalty.
+function identMul(ident, defineCount, mentioned) {
+  let mul = 1.0;
+  const hasAlpha = /[a-zA-Z]/.test(ident);
+  const isSnake = ident.includes("_") && hasAlpha;
+  const isKebab = ident.includes("-") && hasAlpha;
+  const isCamel = /[a-z]/.test(ident) && /[A-Z]/.test(ident);
+  if (mentioned && mentioned.has(ident)) mul *= 10;
+  if ((isSnake || isKebab || isCamel) && ident.length >= 8) mul *= 10;
+  if (ident.startsWith("_")) mul *= 0.1;
+  if (defineCount > 5) mul *= 0.1;
+  return mul;
+}
+
+// Construct a ts-morph Project robustly: use tsconfig.json when present + valid;
+// else (missing / malformed / solution-style references that index 0 files) fall
+// back to broad source globs so the tool degrades gracefully instead of crashing.
+function makeProject() {
+  let project;
+  if (existsSync("tsconfig.json")) {
+    try { project = new Project({ tsConfigFilePath: "tsconfig.json" }); }
+    catch { project = new Project({ compilerOptions: { allowJs: true } }); }
+  } else {
+    project = new Project({ compilerOptions: { allowJs: true } });
+  }
+  // tsconfig `include` usually omits build/pipeline scripts — add by path.
+  project.addSourceFilesAtPaths(["scripts/**/*.mjs", "scripts/**/*.cjs", "scripts/**/*.js", "*.mjs", "*.cjs"]);
+  // Fallback: nothing indexed (no / empty / references-only tsconfig) → broad globs.
+  if (project.getSourceFiles().length === 0)
+    project.addSourceFilesAtPaths([
+      "src/**/*.{ts,tsx,js,jsx}", "app/**/*.{ts,tsx,js,jsx}",
+      "components/**/*.{ts,tsx,js,jsx}", "lib/**/*.{ts,tsx,js,jsx}",
+      "pages/**/*.{ts,tsx,js,jsx}", "*.{ts,tsx,js,jsx}",
+    ]);
+  return project;
+}
+
+// ---------------------------------------------------------------------------
+// build() — parse the repo, extract file imports/exports (+ which named
+// symbols cross each edge), compute file PageRank, run the Aider-style
+// identifier graph to rank individual symbols, and persist repomap.json.
+// ---------------------------------------------------------------------------
+function build() {
+  const project = makeProject();
+  const cwd = process.cwd().replace(/\\/g, "/");
+  const rel = (p) => p.replace(cwd + "/", "");
+  const files = {}, dependents = {}, features = {};
+
+  for (const sf of project.getSourceFiles()) {
+    const path = rel(sf.getFilePath());
+    if (path.includes("node_modules") || path.includes(".next")) continue;
+    const exports = [...sf.getExportedDeclarations()].map(([name, d]) => ({
+      name: name === "default" ? (d[0]?.getName?.() ?? "default") : name,
+      kind: d[0]?.getKindName?.() ?? "?",
+    }));
+    // Dependency edges from static imports + re-export barrels, with the set
+    // of named symbols crossing each edge (used for edge weights + the ident
+    // graph). importedSymbols[targetPath] = [names...].
+    const importedSymbols = {};
+    const addEdge = (tp, names) => {
+      if (tp.includes("node_modules")) return;
+      (importedSymbols[tp] ??= []).push(...names);
+    };
+    for (const imp of sf.getImportDeclarations()) {
+      const t = imp.getModuleSpecifierSourceFile();
+      if (!t) continue;
+      const names = imp.getNamedImports().map((n) => n.getName());
+      if (imp.getDefaultImport()) names.push("default"); // canonical: local alias never matches the export name
+      if (imp.getNamespaceImport()) names.push("*");
+      addEdge(rel(t.getFilePath()), names.length ? names : ["*"]);
+    }
+    for (const exp of sf.getExportDeclarations()) {
+      const t = exp.getModuleSpecifierSourceFile();
+      if (!t) continue;
+      addEdge(rel(t.getFilePath()), exp.getNamedExports().map((n) => n.getName()));
+    }
+    const imports = Object.keys(importedSymbols);
+    for (const tp of imports) (dependents[tp] ??= []).push(path);
+    files[path] = { exports, imports, importedSymbols };
+    const feat = featureOf(path);
+    if (feat) (features[feat] ??= []).push(path);
+  }
+  for (const p in files) files[p].dependents = dependents[p] ?? [];
+
+  // --- File PageRank: edges importer→imported, weighted by # symbols crossed.
+  const nodes = Object.keys(files);
+  const fileEdges = [];
+  for (const [p, f] of Object.entries(files))
+    for (const tp of f.imports)
+      if (files[tp]) fileEdges.push({ from: p, to: tp, weight: (f.importedSymbols[tp] || []).length || 1 });
+  const fileRank = pagerank(nodes, fileEdges);
+  for (const p of nodes) files[p].pagerank = +(fileRank[p] || 0).toFixed(6);
+
+  // --- Symbol ranking (Aider-style): identifier graph from named imports.
+  const rankedSymbols = rankSymbols(files, null);
+
+  // hubs: now PageRank-ranked (raw dependent count shown alongside).
+  const hubs = nodes
+    .map((p) => [p, files[p].pagerank, files[p].dependents.length])
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 15)
+    .map(([p, pr, deg]) => `${p} (deg ${deg}, pr ${pr})`);
+
+  const out = {
+    schema: SCHEMA_VERSION, generatedSha: currentSha(), dirty: dirtyCount(), fileCount: nodes.length,
+    hubs, features, rankedSymbols: rankedSymbols.slice(0, 80), files,
+  };
+  mkdirSync(".claude", { recursive: true });
+  writeFileSync(MAP, JSON.stringify(out));
+  return out;
+}
+
+// Build the Aider-style identifier graph from the file map and return a
+// ranked list of { file, name, kind, rank }. `focus` (Set of paths) +
+// derived mentioned idents personalize the ranking when given.
+function rankSymbols(files, focus) {
+  const defines = new Map();      // ident -> Set(file)
+  const references = new Map();   // ident -> [file...] (multiplicity)
+  const definition = new Map();   // `${file}|${ident}` -> {file, name, kind}
+  for (const [p, f] of Object.entries(files)) {
+    for (const e of f.exports) {
+      (defines.get(e.name) ?? defines.set(e.name, new Set()).get(e.name)).add(p);
+      definition.set(`${p}|${e.name}`, { file: p, name: e.name, kind: e.kind });
+    }
+  }
+  for (const [p, f] of Object.entries(files))
+    for (const tp of f.imports)
+      for (const name of f.importedSymbols[tp] || [])
+        if (name !== "*" && name !== "default") (references.get(name) ?? references.set(name, []).get(name)).push(p);
+
+  // mentioned idents from focus files' exports + their basenames
+  let mentioned = null;
+  if (focus && focus.size) {
+    mentioned = new Set();
+    for (const p of focus) {
+      for (const e of (files[p]?.exports || [])) mentioned.add(e.name);
+      const base = p.split("/").pop().replace(/\.[^.]+$/, "");
+      mentioned.add(base);
+    }
+  }
+
+  const nodes = Object.keys(files);
+  const edges = [];
+  for (const ident of defines.keys()) {
+    if (!references.has(ident)) continue;
+    const mul = identMul(ident, defines.get(ident).size, mentioned);
+    const counts = new Map();
+    for (const refFile of references.get(ident)) counts.set(refFile, (counts.get(refFile) || 0) + 1);
+    for (const [refFile, n] of counts)
+      for (const defFile of defines.get(ident)) {
+        if (refFile === defFile) continue;
+        let useMul = mul;
+        if (focus && focus.has(refFile)) useMul *= 50;
+        edges.push({ from: refFile, to: defFile, weight: useMul * Math.sqrt(n), ident });
+      }
+  }
+  // personalization seeds: focus files + files whose name matches a mention
+  let pers = null;
+  if (focus && focus.size) {
+    pers = {};
+    const unit = 100 / nodes.length;
+    for (const p of nodes) {
+      let v = 0;
+      if (focus.has(p)) v += unit;
+      const parts = new Set([...p.split("/"), p.split("/").pop(), p.split("/").pop().replace(/\.[^.]+$/, "")]);
+      if (mentioned && [...parts].some((x) => mentioned.has(x))) v += unit;
+      if (v > 0) pers[p] = v;
+    }
+    if (!Object.keys(pers).length) pers = null;
+  }
+  const rank = pagerank(nodes, edges, pers ? { personalization: pers } : {});
+
+  // redistribute each file's rank across its out-edges onto (defFile, ident)
+  const out = new Map();      // `${file}|${ident}` -> total weight
+  const totalW = new Map();
+  for (const e of edges) totalW.set(e.from, (totalW.get(e.from) || 0) + e.weight);
+  for (const e of edges) {
+    const share = (rank[e.from] || 0) * e.weight / (totalW.get(e.from) || 1);
+    const k = `${e.to}|${e.ident}`;
+    out.set(k, (out.get(k) || 0) + share);
+  }
+  return [...out.entries()]
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+    .map(([k, r]) => ({ ...(definition.get(k) || { file: k.slice(0, k.lastIndexOf("|")), name: k.slice(k.lastIndexOf("|") + 1), kind: "?" }), rank: +r.toFixed(6) }))
+    .filter((d) => !(focus && focus.has(d.file)));
+}
+
+// Serve the cached map only when provably current: same HEAD, known schema,
+// clean tree. A dirty tree REBUILDS from disk so queries reflect in-flight edits.
+function ensureFresh() {
+  const sha = currentSha();
+  if (existsSync(MAP)) {
+    try {
+      const cached = JSON.parse(readFileSync(MAP, "utf8"));
+      // Trust cache only if: same HEAD, known schema, it was built CLEAN
+      // (cached.dirty === 0 — never trust a map built mid-edit, even after a
+      // revert returns the tree to clean), AND the tree is clean right now.
+      if (sha && cached.generatedSha === sha && cached.schema === SCHEMA_VERSION && cached.dirty === 0 && dirtyCount() === 0) return cached;
+    } catch {}
+  }
+  return build();
+}
+
+// Resolve a query to a file key: exact path → unique basename → unique substring.
+function resolveFile(keys, filesObj, q) {
+  if (filesObj[q]) return { key: q };
+  const base = keys.filter((k) => k.split("/").pop() === q);
+  if (base.length === 1) return { key: base[0] };
+  const subs = keys.filter((k) => k.toLowerCase().includes(q.toLowerCase()));
+  if (subs.length === 1) return { key: subs[0] };
+  return { key: null, candidates: subs };
+}
+
+function fileBlock(key, f) {
+  console.log(`exports (${f.exports.length}): ${f.exports.map((e) => `${e.name}(${e.kind})`).join(", ") || "—"}`);
+  console.log(`imports (${f.imports.length}): ${f.imports.join(", ") || "—"}`);
+  console.log(`dependents (${f.dependents.length}): ${f.dependents.join(", ") || "—"}`);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const arg = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+
+if (has("--any")) {
+  // Unified router: cached structure (file → symbol → feature) then a LIVE
+  // git-grep fallback for data/copy/string-literals the graph never indexes.
+  const raw = arg("--any") || "";
+  if (!raw) { console.log('--any needs a query, e.g. `--any PremiumCard` or `--any "multi-modal"`'); }
+  else {
+    const q = raw.toLowerCase();
+    const data = ensureFresh();
+    const keys = Object.keys(data.files);
+    const { key: fileKey, candidates } = resolveFile(keys, data.files, raw);
+    const symHits = [];
+    for (const [path, f] of Object.entries(data.files))
+      for (const e of f.exports)
+        if (e.name.toLowerCase().includes(q)) symHits.push(`  ${path} → ${e.name} (${e.kind})`);
+    const featNames = Object.keys(data.features || {}).filter((k) => k.toLowerCase().includes(q));
+    if (fileKey) {
+      console.log(`[structure:file] ${fileKey}  (pr ${data.files[fileKey].pagerank ?? "—"})`);
+      fileBlock(fileKey, data.files[fileKey]);
+    } else if (symHits.length || featNames.length) {
+      console.log(`[structure] ${symHits.length} symbol, ${featNames.length} feature match for "${raw}"`);
+      if (symHits.length) console.log(symHits.join("\n"));
+      if (featNames.length) console.log("features: " + featNames.map((n) => `${n} (${data.features[n].length})`).join(", "));
+    } else if (candidates && candidates.length > 1) {
+      console.log(`[structure] "${raw}" matched ${candidates.length} files — narrow it:`);
+      for (const k of candidates) console.log(`  ${k}`);
+    } else {
+      const res = contentSearch(raw);
+      if (!res) console.log(`[content] 0 match for "${raw}" (git grep, tracked + untracked)`);
+      else {
+        const lines = res.split("\n");
+        console.log(`[content] ${lines.length} line${lines.length > 1 ? "s" : ""}${lines.length > 40 ? " (showing 40)" : ""}:`);
+        console.log(lines.slice(0, 40).join("\n"));
+      }
+    }
+  }
+} else if (has("--find")) {
+  const raw = arg("--find") || "", q = raw.toLowerCase();
+  const data = ensureFresh();
+  const hits = [];
+  for (const [path, f] of Object.entries(data.files))
+    for (const e of f.exports)
+      if (e.name.toLowerCase().includes(q)) hits.push(`  ${path} → ${e.name} (${e.kind})`);
+  console.log(`find "${raw}": ${hits.length} match`);
+  if (hits.length) console.log(hits.join("\n"));
+} else if (has("--relates")) {
+  const q = arg("--relates") || "";
+  const data = ensureFresh();
+  const keys = Object.keys(data.files);
+  const { key, candidates } = resolveFile(keys, data.files, q);
+  if (!key) {
+    if (candidates && candidates.length > 1) { console.log(`relates: "${q}" matched ${candidates.length} files — narrow it:`); for (const k of candidates) console.log(`  ${k}`); }
+    else console.log(`relates: no file matching "${q}"`);
+  } else {
+    const f = data.files[key];
+    console.log(`relates: ${key}  (pr ${f.pagerank ?? "—"})`);
+    fileBlock(key, f);
+    // query-focused relevance: personalized PageRank (random-walk-with-restart)
+    // on a BIDIRECTIONAL graph → files most related to the target, transitively.
+    const biEdges = [];
+    for (const [p, ff] of Object.entries(data.files))
+      for (const tp of ff.imports) if (data.files[tp]) { biEdges.push({ from: p, to: tp, weight: 1 }); biEdges.push({ from: tp, to: p, weight: 1 }); }
+    const rel = pagerank(keys, biEdges, { personalization: { [key]: 1 } });
+    const top = Object.entries(rel).filter(([k]) => k !== key).sort((a, b) => b[1] - a[1]).slice(0, 10);
+    console.log(`related (random-walk relevance):`);
+    for (const [k, r] of top) console.log(`  ${k} (${r.toFixed(4)})`);
+  }
+} else if (has("--map")) {
+  // Token-budgeted ranked digest (Aider's killer feature). --focus <path>
+  // personalizes toward a file; default budget 1024, ×8 with no focus.
+  const data = ensureFresh();
+  const focusArg = arg("--focus");
+  const tk = parseInt(arg("--tokens") ?? "", 10);
+  const budget = Number.isFinite(tk) && tk > 0 ? tk : (focusArg ? 1024 : 8192);
+  let ranked = data.rankedSymbols || [];
+  let focusLabel = "global";
+  if (focusArg) {
+    const { key, candidates } = resolveFile(Object.keys(data.files), data.files, focusArg);
+    if (key) { ranked = rankSymbols(data.files, new Set([key])); focusLabel = key; }
+    else console.error(`# warning: --focus "${focusArg}" matched ${(candidates && candidates.length) || 0} files — using global ranking`);
+  }
+  // Fallback for default-export-heavy repos (sparse named-symbol graph): build
+  // the digest from file PageRank so --map is never empty.
+  if (!ranked.length)
+    ranked = Object.entries(data.files)
+      .sort((a, b) => (b[1].pagerank || 0) - (a[1].pagerank || 0))
+      .flatMap(([file, f]) => (f.exports || []).map((e) => ({ file, name: e.name, kind: e.kind, rank: f.pagerank || 0 })));
+  console.log(`# repomap (${data.fileCount} files, sha ${data.generatedSha}) — focus: ${focusLabel}, budget ~${budget} tok`);
+  let used = 0, shown = 0;
+  const byFile = new Map();
+  for (const s of ranked) { if (!byFile.has(s.file)) byFile.set(s.file, []); byFile.get(s.file).push(s); }
+  for (const [file, syms] of byFile) {
+    const line = `\n${file}:\n` + syms.slice(0, 8).map((s) => `  ${s.name} (${s.kind})`).join("\n");
+    const t = tokEst(line);
+    if (used + t > budget) break;
+    used += t; shown++; console.log(line);
+  }
+  console.log(`\n# ~${used} tokens (${shown} files shown)`);
+} else if (has("--symbols")) {
+  const data = ensureFresh();
+  const sn = parseInt(arg("--symbols") ?? "", 10); const n = Number.isFinite(sn) && sn > 0 ? sn : 30;
+  console.log(`top ${n} ranked symbols (Aider-style):`);
+  for (const s of (data.rankedSymbols || []).slice(0, n)) console.log(`  ${s.rank}  ${s.file} → ${s.name} (${s.kind})`);
+} else if (has("--feature")) {
+  const raw = arg("--feature") || "", q = raw.toLowerCase();
+  const data = ensureFresh();
+  const name = Object.keys(data.features).find((k) => k.toLowerCase() === q) || Object.keys(data.features).find((k) => k.toLowerCase().includes(q));
+  if (!name) console.log(`feature: no match for "${raw}" — run --features to list them.`);
+  else {
+    const fl = data.features[name], set = new Set(fl), exts = new Set();
+    for (const p of fl) for (const dep of (data.files[p]?.dependents || [])) if (!set.has(dep)) exts.add(dep);
+    console.log(`feature "${name}": ${fl.length} files`);
+    for (const p of fl) console.log(`  ${p}`);
+    console.log(`external dependents (${exts.size}): ${[...exts].join(", ") || "—"}`);
+  }
+} else if (has("--features")) {
+  const data = ensureFresh();
+  const list = Object.entries(data.features).map(([k, v]) => [k, v.length]).sort((a, b) => b[1] - a[1]);
+  console.log(`features (${list.length}):`);
+  for (const [k, n] of list) console.log(`  ${k} (${n} files)`);
+} else if (has("--hubs")) {
+  const data = ensureFresh();
+  console.log(`repomap: ${data.fileCount} files (sha ${data.generatedSha})`);
+  console.log("hubs (PageRank importance):");
+  for (const h of data.hubs) console.log(`  ${h}`);
+} else if (has("--print")) {
+  const data = ensureFresh();
+  console.log(JSON.stringify({ hubs: data.hubs, features: data.features, rankedSymbols: data.rankedSymbols, files: data.files }));
+} else {
+  const out = build();
+  console.log(`repomap: ${out.fileCount} files | ${Object.keys(out.features).length} features | top hub: ${out.hubs[0] || "—"}`);
+}