agentmap.mjs

#!/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 (approach 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 { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, readdirSync, lstatSync, chmodSync, realpathSync } from "node:fs";
import { execSync, execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { createRequire } from "node:module";
import { homedir } from "node:os";
import { fileURLToPath } from "node:url";
import { join, dirname, resolve } from "node:path";

// Lazy ts-morph: its ~105ms module init only fires on a COLD rebuild. Warm cache
// queries (the common case) never construct a Project, so they skip the load
// entirely (~2x faster warm). createRequire keeps it synchronous — no async to
// thread through build()/makeProject().
const _require = createRequire(import.meta.url);
let _tsm = null;
const tsMorph = () => (_tsm ??= _require("ts-morph"));

const MAP = ".claude/agentmap/map.json";
const MAP_LEGACY = ".claude/agentmap.json"; // pre-namespacing path; read for migration
const MAP_DIRTY = ".claude/agentmap/map.dirty.json"; // dirty-tree build cache, keyed by dirtyFingerprint (Batch 3 Tier 1)
const FACTS = ".claude/agentmap/facts.json"; // raw per-file facts snapshot for incremental rebuild (Batch 3 Tier 2)
// Call-edge index, written ONLY by `--build-edges` (which the post-commit hook
// runs in the background). Deliberately a SEPARATE file from map.json, not a new
// field on it: building it costs ~4x a normal build (the type-checker's
// go-to-definition per call site is irreducible — measured 5.9s vs 1.5s on a
// 250-file repo even after prefiltering), and every other command
// (--relates/--find/--hubs/--map) must not pay that. A missing or stale sidecar
// is never an error: --callers silently falls back to the live ts-morph walk it
// has always used, so this is a pure speedup with no new failure mode.
const EDGES = ".claude/agentmap/calledges.json";
// Version of the EDGE ROW FORMAT, independent of SCHEMA_VERSION (which versions
// map.json). Bump on any change to what a row means or contains — otherwise an
// upgrade silently serves a sidecar written by older logic, and since a missing
// edge just looks like "no caller", the failure is a confident wrong answer with
// no symptom. Bumped to 2 when rows gained export-alias names.
const EDGES_FORMAT = 4;
// Bumped 2 → 3: Vue SFC support. `.vue` files now appear in the map and the
// source-discovery / freshness checks treat them as first-class source files.
// Bumped 3 → 4: per-file `locals` (non-exported top-level declarations) now
// persisted for --find/--any discovery. Old caches (which lack `locals`) rebuild
// on upgrade so a private helper becomes findable without waiting for the next commit.
// Bumped 5 → 6: per-export `definedIn`/`external` (the real declaration site behind
// a re-export barrel) and per-file `typeOnlyImports`/`typeOnlyDependents` (edges a
// fully `import type` declaration used to drop on the floor). Both are spread
// conditionally, so a repo with no barrels and no type-only imports serialises
// byte-identically to schema 5; caches rebuild once on upgrade.
// Bumped 6 → 7: truncation accounting (`incomplete` / `skippedCount` / `skipped` /
// `skippedTruncated`). Spread conditionally, so a repo that indexes every file
// serialises byte-identically to schema 6. The bump is what forces a rebuild of
// caches written BEFORE this feature — those could already be missing files with no
// way to tell, which is the exact bug being fixed, so serving them unchanged would
// leave the lie in place until HEAD happened to move.
// Bumped 7 → 8: `tryResolveAt` gained the emitted-extension rung, so a NodeNext
// `~/x.js` alias specifier now resolves to `x.ts` instead of dropping the edge.
// The map SHAPE is unchanged — this bump exists because the CONTENT is not: a
// cache written by an older build is keyed only by HEAD sha, so on a repo whose
// sha has not moved it would keep serving the missing edges (and a `dependents (0)`
// on a file with real importers) indefinitely after upgrade. Same reasoning as the
// 6 → 7 bump: the stale cache encodes exactly the bug being fixed.
const SCHEMA_VERSION = 8;

// --- .agentmapignore + .d.ts default-exclude (config-file / flag scoping) ------
// The map-cache path used when --include-dts is set. Kept SEPARATE from map.json
// so the two modes never collide: the default (`.d.ts` excluded) map.json — the
// one the post-commit hook writes and every normal query reads — stays untouched
// and byte-identical, while --include-dts builds/reads its own cache.
const MAP_DTS = ".claude/agentmap/map.dts.json"; // --include-dts full-build cache
const AGENTMAPIGNORE = ".agentmapignore";        // repo-root ignore file (gitignore-ish)
// Module-scoped backend config, (re)resolved at the start of every extractFacts()
// so importing this module stays side-effect-free and each build() re-reads
// .agentmapignore from disk. main() flips INCLUDE_DTS via --include-dts.
let INCLUDE_DTS = false;
// Non-exported TOP-LEVEL declarations (module-scope function/class/interface/type/
// enum/const) are always indexed into each file's `locals` at build time and
// surfaced ONLY by --find / --any — they are NEVER ranked (rankSymbols / --map /
// --symbols / --hubs read only `exports`), so the focused digest stays byte-identical.
// --no-locals flips this OFF as a query-time filter that hides them from --find/--any.
let INCLUDE_LOCALS = true;

// Minimal, dependency-free .agentmapignore matcher. Reads repo-root
// `.agentmapignore` (gitignore-STYLE, a documented SUBSET — see below) and returns
// a predicate `(relPath) => boolean` (true ⇒ ignore). Returns null when the file
// is absent/empty so callers skip matching entirely (byte-identical to today).
// Supported subset (kept deliberately small + predictable):
//   • blank lines and `#` comments are skipped;
//   • a leading `/` anchors the pattern to the repo root (else it matches at any
//     depth — the path OR any `/`-bounded segment prefix);
//   • a trailing `/` marks a directory prefix (matches everything under it);
//   • `*` matches any run of non-`/` chars; no `**`, `?`, `[...]`, or negation.
// Anything outside this subset is treated literally. Documented in README.
function loadIgnoreMatcher() {
  let raw;
  try { raw = readFileSync(AGENTMAPIGNORE, "utf8"); } catch { return null; }
  const rules = [];
  for (let line of raw.split(/\r?\n/)) {
    line = line.trim();
    if (!line || line.startsWith("#")) continue;
    const anchored = line.startsWith("/");
    if (anchored) line = line.slice(1);
    const dir = line.endsWith("/");
    if (dir) line = line.slice(0, -1);
    if (!line) continue;
    // ReDoS guard: this glob subset has NO `**` semantics, so a run of `*` means
    // the same as one `*`. Collapse runs BEFORE translating — otherwise adjacent
    // `[^/]*[^/]*…` groups backtrack catastrophically (a `*`×50 line hung the
    // matcher ~80s, freezing build + the post-commit hook + the MCP server). Also
    // skip a pathologically long pattern outright.
    if (line.length > 512) continue;
    line = line.replace(/\*{2,}/g, "*");
    // Escape regex metachars in the literal, then turn `*` into `[^/]*`. Anchored
    // ⇒ `^pat`; unanchored ⇒ match the whole path OR any `/`-bounded segment
    // prefix so a bare `dist` ignores `pkg/dist/x` too.
    const body = line.replace(/[.+^$(){}|\[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
    const tail = dir ? "(?:/|$)" : "$";
    const re = anchored ? new RegExp("^" + body + tail)
                        : new RegExp("(?:^|/)" + body + tail);
    rules.push(re);
  }
  if (!rules.length) return null;
  return (p) => rules.some((re) => re.test(p));
}

// ---------------------------------------------------------------------------
// Tuning constants — KEEP THESE VALUES IDENTICAL (output + marketing must not
// shift). Hoisted out of inline literals so the algorithm is self-documenting.
// ---------------------------------------------------------------------------
const DAMPING = 0.85;            // PageRank damping (Aider parity)
const TOL = 1e-6;                // power-iteration convergence tolerance
const MAX_ITER = 100;            // power-iteration iteration cap
const IDENT_BOOST = 10;          // weight ×: mentioned ident, or long multi-word ident
const RARE_PENALTY = 0.1;        // weight ×: ident defined in >RARE_DEFINERS files (too common)
const UNDERSCORE_PENALTY = 0.1;  // weight ×: private-ish `_`-prefixed ident
const MIN_IDENT_LEN = 8;         // min length for the long-multi-word ident boost
const RARE_DEFINERS = 5;         // >this many definers ⇒ ident is too common ⇒ penalize
const FOCUS_BOOST = 50;          // ref-edge weight × when refFile is in the focus set
const DEFAULT_BUDGET = 8192;     // --map token budget with no --focus
const FOCUS_BUDGET = 1024;       // --map token budget when --focus is given
const HUBS_LIMIT = 15;           // # of hubs persisted/printed
const RANKED_SYMBOLS_LIMIT = 80; // # of ranked symbols persisted
const CONTENT_LINES_LIMIT = 40;  // # of git-grep lines shown in the --any content fallback
const SYMBOL_MATCH_LIMIT = 50;   // max --find/--any symbol matches shown (ranked by PageRank), else token blowup
const DEPTH_CAP = 5;             // hard ceiling on --callers/--calls --depth (transitive call graph)
const CLOSURE_FRONTIER_CAP = 200; // per-level frontier cap for --depth traversal (hub-explosion guard)
const CLOSURE_TOTAL_CAP = 500;   // global emitted-node cap across all --depth levels
const BM25_K1 = 1.2;             // BM25 term-frequency saturation (classic default)
const BM25_B = 0.75;            // BM25 length normalization (classic default)
const PR_WEIGHT = 0.5;          // PageRank fusion strength: finalScore = bm25 * (1 + PR_WEIGHT*normPR)
const LEXICAL_DOC_LIMIT = 5000; // max symbol-docs indexed into map.json (monorepo bloat guard)
const LEXICAL_STOPWORDS = new Set(["the", "a", "an", "that", "which", "is", "of", "for", "to", "where", "in", "and", "or"]);
const RELATED_LIMIT = 10;        // # of related files shown by --relates
const SYMS_PER_FILE = 8;         // per-file symbol cap in the --map digest
const EXPORT_NODE_CAP = 60;      // max nodes in --export dot/mermaid (top-N by pagerank) so a big repo stays readable
const DEFAULT_SYMBOLS = 30;      // default count for --symbols with no n
const SKIPPED_LIST_LIMIT = 100;  // max per-file skip records persisted (skippedCount stays exact)
const MAXBUF = 64 * 1024 * 1024; // child_process maxBuffer — avoid ENOBUFS on big git output

// ---------------------------------------------------------------------------
// TS/JS backend descriptor — the single source of truth for which extensions
// this backend handles. Hoisted out of the 5 sites that used to hardcode the
// list (dirty-check, source fingerprint, ts-morph discovery, non-git glob
// fallback, specifier resolution) so a second-language backend can be a drop-in
// later (Batch 2 seam). Regex alternation order is irrelevant here — each source
// path ends in exactly one extension — so one canonical list stays behavior-
// identical to the old per-site orderings.
//
//   CODE_EXT   — extensions ts-morph parses directly. `.vue` is deliberately
//                NOT here: a Vue SFC is not TS/JS, so it's indexed via a virtual
//                `.vue.ts`/`.vue.js` source (see extractVueScripts), not handed
//                to ts-morph raw.
//   SOURCE_EXT — everything that counts as a "source file" for freshness / dirty
//                detection. INCLUDES `.vue` so editing an SFC busts the cache.
// ---------------------------------------------------------------------------
const CODE_EXT = ["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"];
const SOURCE_EXT = [...CODE_EXT, "vue"];
const extBrace = (list) => `{${list.join(",")}}`;                 // glob brace body
const CODE_EXT_RE = new RegExp(`\\.(${CODE_EXT.join("|")})$`);    // ts-morph-parseable files
const SOURCE_EXT_RE = new RegExp(`\\.(${SOURCE_EXT.join("|")})$`); // any source file (incl. .vue)

// ---------------------------------------------------------------------------
// Language census — the demand instrument.
//
// The old plan gated multi-language work on "post-distribution demand actually
// asks for Python". That gate could never fire: it waited for an ISSUE, and a
// user whose repo agentmap cannot read gets a useless map and leaves without
// filing anything. Two people forked to add a language (agentmap-go,
// agentmap-php) rather than ask for one — the demand was real and the detector
// was pointed the wrong way.
//
// So: count what is actually in the repo, and when a language agentmap does not
// support dominates, say so plainly and point at one countable place to vote.
// No telemetry, ever (ROADMAP Phase 1A) — the count is computed locally, printed
// locally, and never leaves the machine. That is a deliberate trade: the signal
// is lagging and loudness-biased, and that is still better than the trust cost
// of phoning home from a dev tool.
//
// Not exhaustive, and deliberately so — this is a ballot, not a taxonomy. Only
// languages a ts-morph-shaped tool could plausibly grow a backend for.
const FOREIGN_EXT = {
  py: "Python", pyi: "Python",
  go: "Go",
  rs: "Rust",
  java: "Java",
  kt: "Kotlin", kts: "Kotlin",
  rb: "Ruby",
  php: "PHP",
  cs: "C#",
  swift: "Swift",
  scala: "Scala",
  dart: "Dart",
  ex: "Elixir", exs: "Elixir",
  c: "C", h: "C",
  cpp: "C++", cc: "C++", cxx: "C++", hpp: "C++", hh: "C++",
};
// A single unsupported language must be at least this share of all counted
// source files before agentmap says anything. Set so a repo with a handful of
// build scripts in another language stays quiet.
const CENSUS_MIN_SHARE = 0.3;
const VOTE_URL = "https://github.com/raymondchins/agentmap/issues/43";

// Bucket the repo's source files by language. Counts ONLY code — a docs- or
// fixture-heavy repo must not tip the census on .md/.json/.lock/images.
// Returns null when there is nothing to say.
function languageCensus(files) {
  let supported = 0;
  const foreign = new Map();
  for (const f of files) {
    const ext = f.slice(f.lastIndexOf(".") + 1).toLowerCase();
    if (SOURCE_EXT.includes(ext)) { supported++; continue; }
    const lang = FOREIGN_EXT[ext];
    if (lang) foreign.set(lang, (foreign.get(lang) ?? 0) + 1);
  }
  let total = supported;
  for (const n of foreign.values()) total += n;
  if (!total) return null;
  let top = null;
  for (const [lang, count] of foreign) if (!top || count > top.count) top = { lang, count };
  if (!top || top.count / total < CENSUS_MIN_SHARE) return null;
  return { ...top, supported, total, share: top.count / total };
}

const sh = (c) => { try { return execSync(c, { stdio: ["ignore", "pipe", "ignore"], maxBuffer: MAXBUF }).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.
// -i = case-insensitive BY DESIGN (discovery ergonomics, matches --find which
// lowercases its query): a "content" hit may differ in case from the query as
// typed, but every match is printed verbatim with file:line so the true casing
// is always visible — results are a superset, never a falsified exact-case hit.
// stderr ignored so "fatal: not a git repository" stays quiet in non-git repos.
// Exclude sensitive files from the --untracked sweep so a local .env / key /
// secrets file never gets scanned and surfaced (and via MCP fed to an LLM).
// Mix of path globs (env/key/cert/SSH-key shapes) and case-insensitive name
// matches (anything *secret* / *credential* / *password*). These are pathspecs,
// not regexes — git applies them as exclusions to the search tree.
const SENSITIVE_EXCLUDES = [
  ":!.env", ":!.env.*", ":!**/.env", ":!**/.env.*",
  // also any *.env (e.g. prod.env, .env.local already covered above) at any depth
  ":!*.env", ":!**/*.env",
  ":!*.pem", ":!*.key", ":!*.p12", ":!*.pfx", ":!*.crt", ":!id_rsa*",
  // more private-key / keystore shapes + SSH key variants beyond id_rsa.
  ":!*.p8", ":!*.jks", ":!*.keystore", ":!id_ed25519*", ":!id_ecdsa*",
  // conventionally-named credential dotfiles (root + any depth). Deliberately NOT
  // a broad `*token*` name match — that would over-exclude source files like
  // tokenizer.ts / token.ts / useToken.tsx from the content search.
  ":!.npmrc", ":!**/.npmrc", ":!.netrc", ":!**/.netrc",
  ":!.git-credentials", ":!**/.git-credentials", ":!.pgpass", ":!**/.pgpass",
  ":!.htpasswd", ":!**/.htpasswd", ":!.pypirc", ":!**/.pypirc",
  // name-substring matches: `*password*` (not `*.password*`) so a plain
  // password.txt / passwords.json is excluded, not just foo.password.ts.
  ":(exclude,icase)*secret*", ":(exclude,icase)*credential*", ":(exclude,icase)*password*",
];
// Neutralise terminal control sequences in content-search output. These lines are
// the ONLY place agentmap echoes raw repository bytes back out — everything else it
// prints is its own metadata. `git grep -I` already skips binary files, so what is
// left is a TEXT file with escapes deliberately embedded in it: an ESC[2J or a
// cursor-up run can blank the terminal or overwrite the file:line prefix, making a
// hit appear to come from a file it did not. Replaces C0 controls (keeping \t) and
// DEL with U+FFFD, so the line count and column alignment survive and the escape
// becomes visible instead of executable. Applied inside contentSearch() rather than
// at the two print sites, so prose AND --json get the same sanitised bytes — a JSON
// consumer that parses and echoes a line is exposed to exactly the same trick, and
// MCP's JSON.stringify escaping protects the model but not that consumer.
// eslint-disable-next-line no-control-regex
const CONTROL_CHARS = /[\x00-\x08\x0B-\x1F\x7F]/g;
const sanitizeContentLines = (s) => s.replace(CONTROL_CHARS, "�");
const contentSearch = (q) => {
  try {
    return sanitizeContentLines(execFileSync("git", ["-c", "core.quotePath=off", "grep", "-F", "--untracked", "-n", "-i", "-I", "-e", q, "--", ".", ":!.claude/agentmap/", ...SENSITIVE_EXCLUDES], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: MAXBUF }).trim());
  } catch { return ""; }
};
const currentSha = () => sh("git rev-parse --short HEAD");
// git ls-files (tracked + untracked-not-ignored) as an array. `-z` (NUL-separated)
// so non-ASCII / space / special-char filenames come back RAW — the default
// newline output C-quotes them (`"src/caf\303\251.ts"`), which fails the extension
// check and silently drops those files from the map. Returns [] on any git error.
const gitListFiles = () => {
  try { return execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: MAXBUF }).split("\0").filter(Boolean); }
  catch { return []; }
};
// Parse `git status --porcelain` into entries { code, path, oldPath? }. One parse
// feeds both the dirty-SOURCE list (dirtyFiles) and the dirty-CONFIG list
// (dirtyConfigFiles), so the freshness gate + cache key can't diverge.
// - RAW (UNTRIMMED) output: `sh()` trims, which strips the leading space of an
//   unstaged " M path" line and shifts the fixed-column parse (dropping the path's
//   first char); the fingerprint needs the true path for lstat.
// - core.quotePath=off so non-ASCII paths come back as UTF-8, not C-quoted octal
//   (`"src/caf\303\251.ts"`) — otherwise those files silently escape detection.
// - --untracked-files=all so a new file inside a brand-new untracked DIR is listed
//   individually (default "all" folds it to "?? newdir/" and the regex misses it).
function parsePorcelain() {
  let raw;
  try { raw = execFileSync("git", ["-c", "core.quotePath=off", "status", "--porcelain", "--untracked-files=all"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: MAXBUF }); }
  catch { return []; } // not a git repo / git failure → treat as no dirty files
  const out = [];
  for (const l of raw.split("\n")) {
    if (!l) continue;
    const code = l.slice(0, 2);                          // porcelain status code (XY)
    let p = l.slice(3);                                  // strip "XY " status prefix
    let oldPath;
    // only rename/copy entries use the ` old -> new ` form — gating on the status
    // code avoids falsely splitting a plain file whose NAME contains " -> ".
    if (/[RC]/.test(code) && p.includes(" -> ")) {
      const parts = p.split(" -> ");
      oldPath = parts[0].replace(/^"|"$/g, "");          // rename/copy: remember old path
      p = parts.pop();                                   // …keep new path
    }
    p = p.replace(/^"|"$/g, "");                         // unquote any residual (literal quote/newline)
    out.push({ code, path: p, oldPath });
  }
  return out;
}
// tsconfig.json / jsconfig.json (any name e.g. tsconfig.build.json), at any depth.
const CONFIG_DIRTY_RE = /(^|\/)(tsconfig|jsconfig)(\.[\w.-]+)?\.json$/;
// Dirty SOURCE files — the Tier-2 changed-set + Tier-1 fingerprint input. BOTH
// sides of a rename count: a source file renamed to a NON-source name (git mv
// a.ts a.txt) still removes it from the map, so the cache must bust.
function dirtyFiles() {
  return parsePorcelain().filter((e) => SOURCE_EXT_RE.test(e.path) || (e.oldPath && SOURCE_EXT_RE.test(e.oldPath)));
}
// Dirty tsconfig/jsconfig files. These aren't SOURCE (nothing to reparse for their
// own text) but editing them silently changes alias/path RESOLUTION for every
// file, so they must bust the cache WITHOUT entering the source changed-set (which
// would make Tier-2 try to parse JSON as TS). Gate freshness + fingerprint only.
function dirtyConfigFiles() {
  return parsePorcelain().filter((e) => CONFIG_DIRTY_RE.test(e.path) || (e.oldPath && CONFIG_DIRTY_RE.test(e.oldPath)));
}
const dirtyCount = () => dirtyFiles().length;
const tokEst = (s) => Math.ceil((s || "").length / 4); // rough chars/4 estimate

// get-or-init a Map value (readable replacement for the dense `m.get(k) ?? m.set(...)` idiom).
const getOrSet = (m, k, make) => { let v = m.get(k); if (v === undefined) { v = make(); m.set(k, v); } return v; };

// Project a stored export entry into a --find/--any match. Barrel provenance rides
// along so an agent is sent to the file it can actually edit rather than to the
// index.ts that only forwards the name. Defined once because --find and --any each
// have a CLI copy AND an MCP copy, and a four-way copy-paste is how a fix lands in
// one path and silently misses the other three.
const symMatch = (file, e) => ({
  file, name: e.name, kind: e.kind,
  ...(e.definedIn ? { definedIn: e.definedIn } : {}),
  ...(e.external ? { external: true } : {}),
});

// Human-readable suffix for a match/export entry that came through a barrel.
const originNote = (e) => (e.definedIn ? ` → defined in ${e.definedIn}` : e.external ? " → defined outside the repo" : "");

// Compile-time-only relationships, emitted next to (never merged into) the runtime
// ones. Omitted entirely when empty so a repo without type imports is unchanged.
const typeOnlyOut = (f) => ({
  ...(f.typeOnlyImports?.length ? { typeOnlyImports: f.typeOnlyImports } : {}),
  ...(f.typeOnlyDependents?.length ? { typeOnlyDependents: f.typeOnlyDependents } : {}),
});

// Rank symbol matches ({file,name,kind}): real declaration sites first, then by
// their containing file's PageRank (desc), tie-broken by path then name for a
// stable order. A broad --find/--any on a large repo can match thousands of
// exports; showing them all defeats the token-savings point, so callers slice the
// ranked list to SYMBOL_MATCH_LIMIT and surface a "showing N of M" footer.
//
// The declaration-first tier exists because PageRank alone actively works against
// the question --find answers. A barrel is imported by everything, so index.ts
// outranks the file that actually declares the symbol — and the top-1 answer sends
// the agent to a line that only forwards the name. EVAL.md's own caveat (3) named
// this as why top-1 trailed top-3, and it is the one measured place where naive
// grep beat agentmap.
//
// `!definedIn && !external` is the predicate, not `!definedIn` alone: a re-export
// of something outside the repo carries `external: true` and NO `definedIn`, so
// the naive form would promote exactly the rows that cannot be edited at all.
const isDeclarationSite = (m) => !m.definedIn && !m.external;
const rankMatches = (files, matches) =>
  matches.slice().sort((a, b) =>
    (isDeclarationSite(b) ? 1 : 0) - (isDeclarationSite(a) ? 1 : 0)
    || (files[b.file]?.pagerank ?? 0) - (files[a.file]?.pagerank ?? 0)
    || (a.file < b.file ? -1 : a.file > b.file ? 1 : a.name < b.name ? -1 : a.name > b.name ? 1 : 0));

// Split an identifier / path segment into lowercased subtokens on camelCase,
// snake_, kebab-, and digit boundaries. `rankMatches`→[rank,matches];
// `authRetry`→[auth,retry]; `src/lib/http2Client`→[src,lib,http,client]. The
// SINGLE tokenizer used by BOTH the lexical corpus and the query, so they can
// never drift.
function splitIdent(s) {
  return String(s)
    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")    // camelCase boundary
    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2") // HTTPClient → HTTP Client
    .split(/[^a-zA-Z0-9]+|(?<=[a-zA-Z])(?=[0-9])|(?<=[0-9])(?=[a-zA-Z])/)
    .map((t) => t.toLowerCase())
    .filter(Boolean);
}

// BM25 lexical retrieval over the persisted per-symbol index (`data.lexical`),
// fused with file PageRank so a strong hit in an important file wins ties. Answers
// vague NL queries ("where's the auth retry logic") that exact --find/--any miss.
// Pure + dependency-free. Returns { matches:[{file,name,kind,score}], total }.
function bm25Search(lexical, files, rawQuery, { limit = SYMBOL_MATCH_LIMIT } = {}) {
  if (!lexical || !lexical.docs || !lexical.docs.length) return { matches: [], total: 0 };
  const qToks = splitIdent(rawQuery).filter((t) => !LEXICAL_STOPWORDS.has(t));
  if (!qToks.length) return { matches: [], total: 0 };
  const { N, avgdl, df, docs } = lexical;
  let maxPr = 0;
  for (const p in files) maxPr = Math.max(maxPr, files[p].pagerank || 0);
  const scored = [];
  for (const d of docs) {
    let s = 0;
    for (const t of qToks) {
      const tf = d.tf[t];
      if (!tf) continue;
      const n = df[t] || 0;
      const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
      s += idf * (tf * (BM25_K1 + 1)) / (tf + BM25_K1 * (1 - BM25_B + BM25_B * (d.len / (avgdl || 1))));
    }
    if (s <= 0) continue;
    const normPr = maxPr ? (files[d.file]?.pagerank || 0) / maxPr : 0;
    scored.push({ file: d.file, name: d.name, kind: d.kind, score: +(s * (1 + PR_WEIGHT * normPr)).toFixed(6) });
  }
  scored.sort((a, b) => b.score - a.score
    || (a.file < b.file ? -1 : a.file > b.file ? 1 : a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
  return { matches: scored.slice(0, limit), total: scored.length };
}

// Best-effort source fingerprint for NON-git repos (sha == ""). Hash of sorted
// "path:mtimeMs:size" for source files so the cache can be trusted between runs
// without a full reparse. Skips node_modules/.git/.next. Any error ⇒ "" (caller
// falls through to build, i.e. current behavior). Never used on the git path.
// SOURCE_EXT_RE includes `.vue` so editing a Vue SFC invalidates the cache too.
// The one recursive source walk. Two callers needed exactly this traversal and
// differed only in what they do with a file, so it existed twice with the safety
// rules restated in both — the failure mode being a fix applied to one copy. The
// rules are load-bearing and each is here for a specific reason:
//   • depth cap 40 — don't fully walk a pathologically deep tree;
//   • per-directory try/catch — one permission-denied subdir must NOT abort the
//     WHOLE walk. In sourceFingerprint() that would return "" and silently
//     disable caching, which looks like a performance mystery, not an error;
//   • lstatSync, NOT statSync, so a symlink reports as itself rather than its
//     target, and symlinked entries are skipped entirely — never recursed into,
//     never stat'd through — so a circular symlink cannot recurse until the
//     stack overflows;
//   • node_modules/.git/.next pruned before any stat.
// `onFile(fullPath, name, stat)` is called for every non-directory survivor.
function walkSources(dir, onFile, depth = 0) {
  if (depth > 40) return;
  let names; try { names = readdirSync(dir); } catch { return; }
  for (const name of names) {
    if (name === "node_modules" || name === ".git" || name === ".next") continue;
    const full = dir + "/" + name;
    let st; try { st = lstatSync(full); } catch { continue; }
    if (st.isSymbolicLink()) continue;
    if (st.isDirectory()) walkSources(full, onFile, depth + 1);
    else onFile(full, name, st);
  }
}

function sourceFingerprint() {
  try {
    const entries = [];
    walkSources(".", (full, name, st) => {
      if (SOURCE_EXT_RE.test(name)) entries.push(`${full}:${st.mtimeMs}:${st.size}`);
    });
    entries.sort();
    return createHash("sha1").update(entries.join("\n")).digest("hex");
  } catch { return ""; }
}

// Fingerprint of the DIRTY working-tree state for the dirty-map cache (Tier 1).
// sha1 over HEAD sha + sorted per-dirty-file tokens: an existing file →
// "path:mtimeMs:size" (mirrors sourceFingerprint, and only lstat's the handful
// of dirty files, not the whole tree); a deleted/unstattable file → "CODE:path";
// a rename additionally appends "R:old->new" so it can't collide with an
// independent add+delete. HEAD is included so the same edit against a different
// HEAD keys differently. The key changes iff the dirty rebuild's output would.
function dirtyFingerprint(sha, list, configList = []) {
  const toks = [];
  // Source dirty files, plus dirty configs (c: marker) so a tsconfig/jsconfig edit
  // — changes resolution but isn't reparsed as source — still re-keys the cache.
  const entries = [...list, ...configList.map((e) => ({ ...e, _cfg: true }))];
  for (const { code, path, oldPath, _cfg } of entries) {
    let tok = _cfg ? "c:" : "";
    try { const st = lstatSync(path); tok += `${path}:${st.mtimeMs}:${st.size}`; }
    catch { tok += `${(code || "").trim() || "?"}:${path}`; }   // deleted / unstattable
    if (oldPath) tok += `\0R:${oldPath}->${path}`;         // rename ≠ add+delete
    toks.push(tok);
  }
  toks.sort();
  return createHash("sha1").update("HEAD:" + sha + "\n" + toks.join("\n")).digest("hex");
}

// =============================================================================
// Vue Single File Component support — best-effort, zero-dependency.
//
// agentmap is TS/JS-first. Vue `.vue` SFCs are NOT TypeScript; the Vue compiler
// (`@vue/compiler-sfc`) is intentionally NOT a dependency (CONTRIBUTING near-
// zero-deps rule). Instead we extract ONLY the `<script>` / `<script setup>`
// block text with a conservative regex and feed it to ts-morph as a VIRTUAL
// source file (e.g. `App.vue.ts`). A virtual→real path map (see build())
// rewrites every user-facing path back to the real `.vue` path so no
// `.vue.ts` / `.vue.js` ever leaks into JSON or prose.
//
// Non-goals: no template AST, no `<style>` parsing, no Nuxt auto-import
// resolution, no Svelte/Astro. Only `<script>` blocks that look like JS/TS.
// =============================================================================

// Find the first top-level `<script ...>` block (optionally `<script setup ...>`)
// whose opening tag does NOT carry `src="..."` (external script reference —
// the actual JS lives in another file agentmap already indexes on its own).
// Handles single + double quoted lang/src attributes and `lang="ts"`/`ts`.
// Returns { lang, setup, text } for the matched block, or null if none.
//
// Greedy-free: stops at the FIRST `</script>` on its own. Vue forbids nested
// `<script>` tags, so a non-greedy match up to `</script>` is safe. We do NOT
// support `<script>` + `<script setup>` in the same SFC for indexing — we pick
// the richer one: prefer `setup` block if present, else the normal block.
function extractVueScripts(text) {
  const blocks = [];
  // Open-tag matcher is QUOTE-AWARE: attribute values may legitimately contain
  // `>` (e.g. `<script setup lang="ts" generic="T extends Record<string, unknown>">`
  // — a common Vue 3 idiom for typed generic components). We require all
  // attributes to be either bare (`setup`) or quoted (`name="value"` or
  // `name='value'`), which matches valid SFC syntax. Bareword and unquoted forms
  // are intentionally not matched because they're not valid HTML and would
  // almost certainly indicate a parsing bug we want to surface, not silently
  // misparse.
  const re = /<script(\s+[a-zA-Z][\w-]*(\s*=\s*(?:"[^"]*"|'[^']*'))?)*\s*\/?>/gi;
  let m;
  while ((m = re.exec(text)) !== null) {
    const attrs = (m[0].slice(7, -1) || "").trim(); // strip <script…> wrapper
    // find body: text after the opening tag up to </script>
    const openEnd = m.index + m[0].length;
    const closeStart = text.toLowerCase().indexOf("</script>", openEnd);
    if (closeStart === -1) break; // unterminated — stop scanning
    const body = text.slice(openEnd, closeStart);
    // external script reference → skip (the target file is indexed directly).
    if (/\bsrc\s*=\s*["'][^"']+["']/i.test(attrs)) continue;
    if (!body.trim()) continue; // empty body (e.g. <script/>) — not useful
    const setup = /\bsetup\b/i.test(attrs);
    const lang = (attrs.match(/\blang\s*=\s*["']([^"']+)["']/i) || [])[1] || "js";
    blocks.push({ lang: lang.toLowerCase(), setup, text: body });
    re.lastIndex = closeStart + "</script>".length; // resume after </script>
  }
  if (!blocks.length) return null;
  // Prefer a setup block (the modern idiom) when present; else the plain block.
  return blocks.find((b) => b.setup) || blocks[0];
}

// Virtual file path mapping for a `.vue` source. The virtual path is what
// ts-morph sees (so `.ts`/`.js` parsing kicks in); the real path is what every
// user-facing output shows. `lang="ts"` → `.vue.ts`, otherwise `.vue.js`.
function vueVirtualPath(realPath, lang) {
  return lang === "ts" ? `${realPath}.ts` : `${realPath}.js`;
}

// 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;
}

// React Server/Client boundary — read the directive PROLOGUE (compiler-accurate,
// not a text grep): the leading string-literal ExpressionStatements. Returns
// 'client' for `'use client'`, 'server' for `'use server'`, else null. Tolerates
// other prologue directives (`'use strict'`) and stops at the first non-directive
// statement. `SyntaxKind` is passed in so this stays a pure module-scope helper.
function rscBoundary(sf, SyntaxKind) {
  for (const st of sf.getStatements()) {
    if (st.getKind() !== SyntaxKind.ExpressionStatement) break; // prologue ended
    const e = st.getExpression();
    if (e.getKind() !== SyntaxKind.StringLiteral) break;
    const v = e.getLiteralText();
    if (v === "use client") return "client";
    if (v === "use server") return "server";
  }
  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 = DAMPING, tol = TOL, maxIter = MAX_ITER } = {}) {
  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 *= IDENT_BOOST;
  if ((isSnake || isKebab || isCamel) && ident.length >= MIN_IDENT_LEN) mul *= IDENT_BOOST;
  if (ident.startsWith("_")) mul *= UNDERSCORE_PENALTY;
  if (defineCount > RARE_DEFINERS) mul *= RARE_PENALTY;
  return mul;
}

// posix-join that resolves ./ .. and returns an absolute-ish path; passes an
// already-absolute `b` through. Used to anchor a tsconfig baseUrl to the dir of
// the config that DEFINED it (module-scope twin of the joinPosix inside extractFacts).
function joinPosixAbs(a, b) {
  if (/^(\/|[A-Za-z]:[\\/])/.test(b)) return b.replace(/\\/g, "/"); // already absolute
  const abs = a.replace(/\\/g, "/");
  const parts = (abs + "/" + b).split("/"); const st = [];
  for (const seg of parts) { if (seg === "" || seg === ".") continue; if (seg === "..") st.pop(); else st.push(seg); }
  return (abs.startsWith("/") ? "/" : "") + st.join("/");
}

// Read baseUrl+paths from a tsconfig/jsconfig file. Returns null when absent.
// Follows `extends` recursively (depth-capped) so a package tsconfig that only
// `extends` a shared base (Turborepo tsconfig.base.json holding all `paths`)
// still contributes its inherited baseUrl/paths. Child overrides parent.
function readTsconfigAliasOpts(cfgPath, _depth = 0, _memo = new Map()) {
  // Terminating condition for `extends`: read each config AT MOST ONCE per
  // top-level call. Without this, `extends` fans out as branch^depth and the
  // `_depth < 10` cap below bounds DEPTH but not WORK: since TS 5.0 `extends`
  // may be an array, so one self-referencing file (`extends: ["./tsconfig.json"
  // ×4]`) is 4^10 readFileSync+JSON.parse calls and spins a core indefinitely.
  // It is a synchronous loop, so the process never reaches a signal handler —
  // SIGTERM is ignored and only SIGKILL stops it. The in-flight `null` doubles
  // as the cycle guard. A fresh Map per top-level call keeps every acyclic,
  // non-duplicated config — i.e. every real repo — byte-identical.
  const _key = cfgPath.replace(/\\/g, "/");
  if (_memo.has(_key)) return _memo.get(_key);
  _memo.set(_key, null);
  try {
    const raw = JSON.parse(readFileSync(cfgPath, "utf8")) || {};
    const co = raw.compilerOptions || {};
    const here = dirname(cfgPath).replace(/\\/g, "/");
    // Resolve inherited opts from `extends` first (parent), then layer self on top.
    let inherited = null;
    if (raw.extends && _depth < 10) {
      const exts = Array.isArray(raw.extends) ? raw.extends : [raw.extends];
      for (const ext of exts) {
        if (typeof ext !== "string" || !ext) continue;
        // Only resolve path-like extends (./, ../, absolute). Bare package
        // extends (e.g. "@tsconfig/strict") live in node_modules and don't
        // carry repo-local `paths`, so skip them safely.
        if (!/^(\.\.?\/|\/)/.test(ext)) continue;
        let base = join(here, ext);
        if (!existsSync(base) && existsSync(base + ".json")) base += ".json";
        else if (!/\.json$/.test(base) && existsSync(join(base, "tsconfig.json"))) base = join(base, "tsconfig.json");
        if (!existsSync(base)) continue;
        const parent = readTsconfigAliasOpts(base, _depth + 1, _memo);
        if (parent) inherited = { ...(inherited || {}), ...parent };
      }
    }
    const self = {};
    // Anchor baseUrl to THIS config's own dir at read time — before it's merged
    // into a child via `extends`. Once absolute it resolves correctly no matter
    // which dir a downstream consumer pairs it with (fixes inherited baseUrl/paths
    // resolving against the child config's dir instead of the base's origin).
    if (co.baseUrl) self.baseUrl = joinPosixAbs(here, co.baseUrl);
    if (co.paths) self.paths = co.paths;
    const out = { ...(inherited || {}), ...self };
    if (!Object.keys(out).length) return null;
    _memo.set(_key, out);
    return out;
  } catch { return null; }
}

// vite.config / webpack config file names we probe for a `resolve.alias` literal.
const VITE_CONFIG_RE = /(^|\/)(vite|vitest|webpack)\.config\.(js|ts|mts|cts|mjs|cjs)$/; // .mts/.cts are valid config extensions and were silently skipped
// Extract STRING→STRING `resolve.alias` object-literal entries from a bundler config
// WITHOUT executing it (untrusted repo code). ts-morph parses the file to an AST and
// we read only string-literal keys/values off the `alias` object literal — no eval,
// no import, no require of the config. Function/regex/URL-idiom aliases are skipped
// (deferred). The common Vite idiom `'@': path.resolve(__dirname, 'src')` is handled
// by taking the LAST string-literal argument of a path.resolve()/join() call. Returns
// { find: replacement, … } (raw, dir-relative) or null when nothing usable is found.
function readBundlerAliasEntries(cfgPath) {
  let text; try { text = readFileSync(cfgPath, "utf8"); } catch { return null; }
  let SyntaxKind, Project;
  try { ({ SyntaxKind, Project } = tsMorph()); } catch { return null; }
  let sf;
  // Parse in an in-memory FS so the config file is never added to the real project.
  try {
    const p = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
    sf = p.createSourceFile("bundler.config.ts", text, { overwrite: true });
  } catch { return null; }
  const strLit = (node) => {
    const k = node?.getKind?.();
    if (k === SyntaxKind.StringLiteral || k === SyntaxKind.NoSubstitutionTemplateLiteral) {
      try { return node.getLiteralText(); } catch { return null; }
    }
    return null;
  };
  // last string-literal ARG of a path.resolve/join(__dirname, X) style call.
  const callTail = (call) => {
    let args; try { args = call.getArguments(); } catch { return null; }
    let last = null;
    for (const a of args) { const s = strLit(a); if (s !== null) last = s; }
    return last;
  };
  const out = {};
  let props; try { props = sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment); } catch { return null; }
  for (const p of props) {
    let name; try { name = p.getName(); } catch { continue; }
    // getName() keeps quotes for string-literal keys; accept both quoted + bare `alias`.
    if (name !== "alias" && name !== "'alias'" && name !== '"alias"' && name !== "`alias`") continue;
    let init; try { init = p.getInitializer(); } catch { continue; }
    // object-literal form only; the array `[{ find, replacement }]` form is deferred.
    if (!init || init.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
    for (const entry of init.getProperties()) {
      if (entry.getKind() !== SyntaxKind.PropertyAssignment) continue; // skip spreads/methods
      let rawKey; try { rawKey = entry.getName(); } catch { continue; }
      const key = rawKey.replace(/^['"`]|['"`]$/g, ""); // strip surrounding quotes
      if (!key) continue;
      let val; try { val = entry.getInitializer(); } catch { continue; }
      if (!val) continue;
      let target = strLit(val);
      if (target === null && val.getKind() === SyntaxKind.CallExpression) target = callTail(val);
      if (target === null) continue; // function/regex/URL alias → defer (never execute)
      out[key] = target;
    }
  }
  return Object.keys(out).length ? out : null;
}

// Normalize raw bundler alias entries → the same `paths` shape tsconfig uses, keyed
// dir-relative so it resolves against baseUrl = the config's own dir. A vite alias is
// PREFIX-based (`@/foo` → `<repl>/foo`) and also matches the BARE find (`@` → `<repl>`),
// so each entry emits BOTH an exact `find` and a wildcard `find/*` — resolveAlias's
// exact-beats-wildcard precedence then does the right thing. `__dirname`-relative
// targets like `./src/components` collapse via the shared joinPosix in resolveAlias.
function bundlerAliasToPaths(entries) {
  const paths = {};
  for (const [find, repl] of Object.entries(entries)) {
    if (!find || repl == null) continue;
    const target = repl.replace(/^\.\//, ""); // drop a leading ./ (baseUrl-relative anyway)
    paths[find] = [target];
    paths[`${find}/*`] = [`${target}/*`];
  }
  return paths;
}

// Normalize a package.json Node "imports" map (self-referencing internal subpath
// specifiers — keys ALWAYS start with `#`, e.g. `#lib/util`, `#internal/*`) → the
// same `paths` shape tsconfig uses, keyed against baseUrl = the package's own dir
// (where its package.json lives; "imports" targets are package-dir-relative). A
// value may be a plain string OR a conditions object ({ import, default, node, … });
// impLeaf() pulls the ESM/source target out — prefer `import`, then `default`, then
// any string leaf (same order discoverWorkspacePackages uses for "exports"). "imports"
// targets point at the EMITTED file (`./dist/x.js`, `./src/x.js`); to reach SOURCE we
// emit an extensionless TWIN first (drop a trailing code ext) so tryResolveAt's
// extension ladder lands the `.ts`/`.tsx` source, with the raw target kept as a
// fallback. Non-`#` keys, non-string leaves, and function/URL conditions are skipped
// (never executed). Returns { "#foo": [...], "#foo/*": [...], … } or {} when empty.
function packageImportsToPaths(imports) {
  if (!imports || typeof imports !== "object" || Array.isArray(imports)) return {};
  const impLeaf = (c) => {
    if (typeof c === "string") return c;
    if (c && typeof c === "object") { for (const k of ["import", "default"]) if (typeof c[k] === "string") return c[k]; for (const k in c) if (typeof c[k] === "string") return c[k]; }
    return null;
  };
  // strip a leading ./ (package-dir-relative anyway) + a trailing code ext for the
  // source-preferred extensionless twin. Keeps a `*` intact (`src/x/*.js`→`src/x/*`).
  const stripExt = (t) => t.replace(CODE_EXT_RE, ""); // derive from CODE_EXT (:158) — a second hand-written copy silently stops matching the day a 9th extension is added
  const paths = {};
  for (const key of Object.keys(imports)) {
    if (typeof key !== "string" || !key.startsWith("#")) continue; // "imports" keys are always #-prefixed
    const leaf = impLeaf(imports[key]);
    if (typeof leaf !== "string" || !leaf) continue;
    const raw = leaf.replace(/^\.\//, "");
    const bare = stripExt(raw);
    paths[key] = bare === raw ? [raw] : [bare, raw]; // source-preferred (extensionless) first
  }
  return paths;
}

// Collect package-level alias configs from tsconfig/jsconfig files in the repo.
// Deepest-dir-first sort so nearestAliasConfig can pick the longest prefix match.
function discoverPackageAliasConfigs(rootAbs, listed) {
  const root = rootAbs.replace(/\\/g, "/");
  const configs = [];
  const cfgRels = listed.length
    ? listed.filter((f) => /(^|\/)tsconfig\.json$/.test(f) || /(^|\/)jsconfig\.json$/.test(f))
    : [];
  for (const rel of cfgRels) {
    const full = join(root, rel);
    if (!existsSync(full)) continue;
    const opts = readTsconfigAliasOpts(full);
    if (!opts) continue;
    const cfgDir = join(root, dirname(rel)).replace(/\\/g, "/");
    configs.push({
      dir: cfgDir,
      // baseUrl from readTsconfigAliasOpts is already absolute (anchored at read
      // time); the fallback is this config's own dir, not the literal ".".
      baseUrl: opts.baseUrl || cfgDir,
      paths: opts.paths || {},
    });
  }
  // Bundler (vite/webpack) resolve.alias configs. Read WITHOUT executing the config
  // (readBundlerAliasEntries parses the AST only). Normalized to the tsconfig `paths`
  // shape with baseUrl = the config's own dir. tsconfig WINS on conflict: when a
  // tsconfig config already exists at the SAME dir AND is anchored to that dir
  // (baseUrl === cfgDir, the `baseUrl: "."` default), vite paths merge UNDER it
  // ({ ...vite, ...tsconfig }); otherwise the vite entry is appended separately AFTER
  // the tsconfig one so the tsconfig still wins the nearest-config pick.
  const cfgFiles = listed.length ? listed.filter((f) => VITE_CONFIG_RE.test(f)) : [];
  for (const rel of cfgFiles) {
    const full = join(root, rel);
    if (!existsSync(full)) continue;
    const entries = readBundlerAliasEntries(full);
    if (!entries) continue;
    const vitePaths = bundlerAliasToPaths(entries);
    if (!Object.keys(vitePaths).length) continue;
    const cfgDir = join(root, dirname(rel)).replace(/\\/g, "/");
    const sameDirTs = configs.find((c) => c.dir === cfgDir && c.baseUrl === cfgDir);
    if (sameDirTs) sameDirTs.paths = { ...vitePaths, ...sameDirTs.paths }; // tsconfig keys win
    else configs.push({ dir: cfgDir, baseUrl: cfgDir, paths: vitePaths });
  }
  // package.json Node "imports" maps (self-referencing `#internal/*` subpaths). Read
  // WITHOUT executing the package.json (JSON.parse only). Normalized to the tsconfig
  // `paths` shape with baseUrl = the package's own dir ("imports" targets are always
  // package-dir-relative). `#`-keyed, so they never collide with `@/`/`~/` tsconfig or
  // vite aliases; a `#`-prefixed specifier already routes to resolveAlias (it's non-
  // relative and no workspace name starts with `#`), so this needs no resolver change.
  // Merge into an aligned same-dir config (baseUrl === pkgDir — the common `baseUrl:"."`
  // / no-baseUrl case) so nearestAliasConfig's one-config-per-dir pick still sees the
  // imports keys; otherwise append a standalone config anchored at the package dir.
  const pkgFiles = listed.length ? listed.filter((f) => /(^|\/)package\.json$/.test(f) && !f.split("/").includes("node_modules")) : [];
  for (const rel of pkgFiles) {
    const full = join(root, rel);
    if (!existsSync(full)) continue;
    let pkg; try { pkg = JSON.parse(readFileSync(full, "utf8")); } catch { continue; }
    const impPaths = packageImportsToPaths(pkg && pkg.imports);
    if (!Object.keys(impPaths).length) continue;
    const cfgDir = join(root, dirname(rel)).replace(/\\/g, "/");
    const sameDir = configs.find((c) => c.dir === cfgDir && c.baseUrl === cfgDir);
    if (sameDir) sameDir.paths = { ...impPaths, ...sameDir.paths }; // existing (tsconfig/vite) keys win on the impossible collision
    else configs.push({ dir: cfgDir, baseUrl: cfgDir, paths: impPaths });
  }
  configs.sort((a, b) => b.dir.length - a.dir.length);
  return configs;
}

// Collect workspace cross-package resolution targets from every tracked
// package.json that declares a "name" (pnpm/npm/yarn workspaces). Maps the
// Look up a requested subpath in a package's declared `exports` map. An exact key
// wins; otherwise Node's subpath PATTERNS apply ("./wild/*": "./src/wild/*.ts"),
// where the matched text replaces every `*` in the target. Without this the lookup
// was exact-match only, so every wildcard subpath in a workspace package silently
// produced no edge at all.
//
// Selection follows Node's own patternKeyCompare, verified against Node v26:
// longest prefix before the `*` wins, and on a TIE the longer FULL key wins —
// declaration order never decides. That tie is not exotic: Node's own docs use
// `"./lib/*"` alongside `"./lib/*.js"` for extension-optional exports, and picking
// by key order there resolves to the wrong file.
//
// An EMPTY fill is rejected. Node raises ERR_PACKAGE_PATH_NOT_EXPORTED when the
// specifier is exactly prefix+suffix with nothing between, so accepting it would
// invent an edge for an import that throws at runtime.
function matchSubpath(subpaths, sub) {
  if (subpaths[sub] !== undefined) return subpaths[sub];
  let best = null, bestPre = -1, bestKey = -1;
  for (const key in subpaths) {
    const star = key.indexOf("*");
    if (star < 0) continue;
    const pre = key.slice(0, star), post = key.slice(star + 1);
    if (sub.length <= pre.length + post.length) continue; // no empty match
    if (!sub.startsWith(pre) || !sub.endsWith(post)) continue;
    if (pre.length < bestPre || (pre.length === bestPre && key.length <= bestKey)) continue;
    bestPre = pre.length; bestKey = key.length;
    const fill = sub.slice(pre.length, sub.length - post.length);
    best = subpaths[key].map((t) => t.split("*").join(fill));
  }
  return best;
}

// package NAME → { dir, entries, subpaths } where `dir` is the package's absolute
// posix directory, `entries` are the raw "." source-entry candidates in
// preference order (SOURCE over dist): "exports"["."] → "module" → "main" →
// "./index", and `subpaths` maps a declared "exports" subpath (`./button`) to its
// source target. Actual file resolution is deferred to the resolver's
// tryResolveAt (which needs the ts-morph project), so a `dist/index.js` entry
// with no source sibling still can't wrongly resolve — it just misses, same as
// today. Any package.json with no "name" (root/private shells) contributes
// nothing. node_modules is path-segment excluded. Empty when no NAMED
// package.json is tracked, so a single-package repo stays byte-identical (the
// workspace branch never fires).
function discoverWorkspacePackages(rootAbs, listed) {
  const root = rootAbs.replace(/\\/g, "/");
  const pkgs = Object.create(null);
  const pkgRels = listed.length
    ? listed.filter((f) => /(^|\/)package\.json$/.test(f) && !f.split("/").includes("node_modules"))
    : [];
  for (const rel of pkgRels) {
    const full = join(root, rel);
    if (!existsSync(full)) continue;
    let pkg; try { pkg = JSON.parse(readFileSync(full, "utf8")); } catch { continue; }
    const name = pkg && typeof pkg.name === "string" ? pkg.name : "";
    if (!name) continue;                              // unnamed / root shell → not a resolution target
    const dir = join(root, dirname(rel)).replace(/\\/g, "/");
    // "." entry candidates, SOURCE-first & deduped, plus a subpath map from any
    // declared "exports" subpaths.
    //
    // Order matters and mirrors TypeScript's own preference: the `types` /
    // `typings` field wins over `main`. In a monorepo the published entry
    // (`main`) points at BUILT output that usually isn't in the repo, while
    // `types` points at source or at a .d.ts next to it — so consulting `main`
    // first resolved a workspace import to a `dist/` path that does not exist
    // and dropped the cross-package edge entirely. Measured: a package declaring
    // `main: "dist/index.js", types: "src/index.ts"` reported ZERO dependents.
    const entries = [];
    const subpaths = Object.create(null);
    const push = (v) => { if (typeof v === "string" && v && !entries.includes(v)) entries.push(v); };
    // Pull a string target out of a string OR a conditions object. `types` is
    // checked first for the same reason as above — TypeScript resolves the
    // "types" export condition ahead of "import"/"require"/"default", and in a
    // source repo that condition is the one pointing at code that exists.
    // Recursive: Node allows conditions to nest to any depth ({"node":{"import":…}}),
    // and only reading one level down made a nested map resolve to nothing at all.
    // Returns EVERY candidate in precedence order, not just the first, because an
    // array target is Node's fallback list ("try each until one resolves") and only
    // the caller knows what exists on disk. The "." entry already worked this way
    // via `entries`; subpaths held a single string and so could never fall back.
    // Walks SOURCE-first (`types`/`typings` before `import`/`default`), which is
    // deliberately NOT Node's runtime precedence: this tool never executes the
    // package, and a published `require`/`import` target usually points at a
    // gitignored dist/. Same reasoning as 05ef8dc.
    const condTargets = (c, depth = 0, out = []) => {
      if (typeof c === "string") { if (c && !out.includes(c)) out.push(c); return out; }
      if (depth > 8) return out; // pathological nesting; no real package goes near this
      if (Array.isArray(c)) { for (const v of c) condTargets(v, depth + 1, out); return out; }
      if (c && typeof c === "object") {
        for (const k of ["types", "typings", "import", "default"]) if (k in c) condTargets(c[k], depth + 1, out);
        for (const k in c) condTargets(c[k], depth + 1, out);
      }
      return out; // `null` (a deliberately blocked subpath) falls through to []
    };
    // Ahead of `exports`/`module`/`main` below.
    push(pkg.types);
    push(pkg.typings);
    const exp = pkg.exports;
    if (typeof exp === "string") push(exp);
    else if (exp && typeof exp === "object") {
      for (const key of Object.keys(exp)) {
        const targets = condTargets(exp[key]);
        if (!targets.length) continue;
        if (key === ".") for (const t of targets) push(t);
        else if (key.startsWith("./")) subpaths[key.slice(2)] = targets; // "./button" → "button"
      }
      // A bare conditions object (no "." and no "./x" keys) is itself the "." entry.
      if (!Object.keys(exp).some((k) => k === "." || k.startsWith("."))) for (const t of condTargets(exp)) push(t);
    }
    push(pkg.module);
    push(pkg.main);
    // Conventional last resorts, tried only after every DECLARED entry has failed
    // to land on an indexed file. `./index` was already here; `./src/index` earns
    // its place the same way. In a monorepo `main`/`exports` name the PUBLISHED
    // artifact — `dist/index.js` — and `dist/` is normally gitignored, so a
    // package with no `types` field resolved to a path that is not in the repo and
    // the cross-package edge vanished. The source it was built from is right
    // there. This cannot outrank a declared entry, so a package that really does
    // ship its source from somewhere else is unaffected.
    push("./index");
    push("./src/index");
    pkgs[name] = { dir, entries, subpaths };
  }
  return pkgs;
}

// Longest matching tsconfig dir wins (monorepo package boundary).
function nearestAliasConfig(fromAbsDir, configs, rootAbs, rootOpts) {
  const norm = fromAbsDir.replace(/\\/g, "/");
  let best = null;
  for (const c of configs) {
    const d = c.dir;
    if (norm === d || norm.startsWith(d + "/")) { best = c; break; } // configs sorted deepest-first
  }
  if (best) return best;
  return { dir: rootAbs, baseUrl: rootOpts.baseUrl || rootAbs, paths: rootOpts.paths || {} };
}

// 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(inc = null) {
  const { Project } = tsMorph();
  // skipFileDependencyResolution: ~40% faster build, verified identical edge
  // set (we resolve module specifiers explicitly below, never via the implicit
  // dependency graph). allowJs so .js/.jsx are parsed.
  const FAST = { skipFileDependencyResolution: true };
  // Read tsconfig/jsconfig baseUrl+paths defensively so "@/…"/"~/…" alias
  // imports still resolve when tsconfig is absent/broken. Any failure ⇒ none.
  const aliasOpts = (() => {
    for (const cfg of ["tsconfig.json", "jsconfig.json"]) {
      try {
        if (!existsSync(cfg)) continue;
        const opts = readTsconfigAliasOpts(cfg);
        if (opts) return opts;
      } catch { /* ignore — proceed without paths */ }
    }
    return {};
  })();

  // ---- Tier 2 INCREMENTAL project construction --------------------------------
  // Parse ONLY the changed files (real content); add empty ts-morph stubs for
  // every OTHER cached key so a changed file's import edges resolve to exactly the
  // same keys a full build would — without paying to parse unchanged content.
  // tsconfig is intentionally NOT auto-loaded (that eagerly parses the whole tree,
  // the cost we're avoiding); alias resolution still works via aliasOpts +
  // packageAliasConfigs. Vue `<script>` blocks for changed .vue files are parsed
  // as virtual sources; unchanged .vue keys become resolution-only vueReal marks.
  if (inc) {
    const cwdp = process.cwd().replace(/\\/g, "/");
    const seg = (f) => { const s = f.split("/"); return s.includes("node_modules") || s.includes(".next"); };
    const project = new Project({ compilerOptions: { allowJs: true, ...aliasOpts }, ...FAST });
    const changedSet = new Set(inc.changed);
    const vueFiles = [];
    const changedCode = [];
    for (const f of inc.changed) {
      if (seg(f)) continue;
      if (CODE_EXT_RE.test(f)) changedCode.push(f);
      else if (f.endsWith(".vue")) vueFiles.push(f);
    }
    if (changedCode.length) project.addSourceFilesAtPaths(changedCode);
    const vueMap = Object.create(null);
    const vueReal = Object.create(null);
    for (const key of inc.cachedKeys) {
      if (changedSet.has(key) || seg(key)) continue;
      if (key.endsWith(".vue")) vueReal[`${cwdp}/${key}`] = true;                       // resolution target only
      else if (CODE_EXT_RE.test(key)) { try { project.createSourceFile(`${cwdp}/${key}`, "", { overwrite: true }); } catch {} }
    }
    // Config discovery must see the SAME input as a full build (git ls-files
    // includes package.json/tsconfig.json, which the source-only cachedKeys don't)
    // so monorepo alias resolution matches. Cheap — no source parsing.
    const listed = gitListFiles();
    const packageAliasConfigs = discoverPackageAliasConfigs(cwdp, listed);
    const workspacePackages = discoverWorkspacePackages(cwdp, listed);
    for (const f of vueFiles) {
      let text; try { text = readFileSync(f, "utf8"); } catch { continue; }
      const block = extractVueScripts(text);
      if (!block || !block.text.trim()) continue;
      const vpath = vueVirtualPath(f, block.lang);
      project.createSourceFile(`${cwdp}/${vpath}`, block.text, { overwrite: true });
      vueMap[`${cwdp}/${vpath}`] = `${cwdp}/${f}`;
      vueReal[`${cwdp}/${f}`] = true;
    }
    return { project, vueMap, vueReal, aliasOpts, packageAliasConfigs, workspacePackages };
  }
  // ---- end incremental --------------------------------------------------------

  let project;
  if (existsSync("tsconfig.json")) {
    try { project = new Project({ tsConfigFilePath: "tsconfig.json", ...FAST }); }
    catch {
      // tsconfig present but unreadable/malformed — don't silently degrade.
      console.error("# warning: tsconfig.json unreadable, using source globs");
      project = new Project({ compilerOptions: { allowJs: true, ...aliasOpts }, ...FAST });
    }
  } else {
    project = new Project({ compilerOptions: { allowJs: true, ...aliasOpts }, ...FAST });
  }
  // tsconfig `include` usually omits build/pipeline scripts — add by path.
  project.addSourceFilesAtPaths([
    "scripts/**/*.{mjs,cjs,js}", "*.mjs", "*.cjs",
  ]);
  // Catch source files a narrow tsconfig `include` misses (monorepo / subdir-
  // scoped) WITHOUT an expensive full-tree FS glob (which cost ~600ms to find a
  // handful of files). Enumerate cheaply via `git ls-files` (tracked + untracked-
  // not-ignored — node_modules etc. excluded by --exclude-standard) and add only
  // files not already loaded. Non-git repos fall back to the broad globs.
  const loaded = new Set(project.getSourceFiles().map((s) => s.getFilePath()));
  const cwdp = process.cwd().replace(/\\/g, "/");
  const listed = gitListFiles();
  const packageAliasConfigs = discoverPackageAliasConfigs(cwdp, listed);
  const workspacePackages = discoverWorkspacePackages(cwdp, listed);
  // `.vue` discovery: same channel as TS/JS (git ls-files when available, else
  // a broad glob fallback). We do NOT hand `.vue` straight to ts-morph (it is
  // not TS/JS). Instead, for each `.vue` file we read its `<script>` block via
  // extractVueScripts() and register it as a VIRTUAL source file
  // (`App.vue.ts` / `App.vue.js`). A virtual→real path map is returned alongside
  // the project so build() can rewrite every user-facing path back to `.vue`.
  const vueFiles = [];
  if (listed.length) {
    const missing = [];
    for (const f of listed) {
      if (CODE_EXT_RE.test(f)) {
        const segs = f.split("/");
        if (segs.includes("node_modules") || segs.includes(".next")) continue;
        if (!loaded.has(`${cwdp}/${f}`)) missing.push(f);
      } else if (f.endsWith(".vue")) {
        const segs = f.split("/");
        if (segs.includes("node_modules") || segs.includes(".next")) continue;
        vueFiles.push(f);
      }
    }
    if (missing.length) project.addSourceFilesAtPaths(missing);
  } else {
    // non-git fallback: broad globs (mts/cts/mjs/cjs per base dir included).
    const g = extBrace(CODE_EXT); // e.g. {ts,tsx,mts,cts,js,jsx,mjs,cjs}
    project.addSourceFilesAtPaths([
      `src/**/*.${g}`, `app/**/*.${g}`,
      `components/**/*.${g}`, `lib/**/*.${g}`,
      `pages/**/*.${g}`, `*.${g}`,
    ]);
    // Non-git `.vue` fallback: same traversal as sourceFingerprint(), different leaf.
    try {
      walkSources(".", (full, name) => {
        if (name.endsWith(".vue")) vueFiles.push(full.replace(/^\.\//, ""));
      });
    } catch { /* ignore — proceed without Vue */ }
  }
  // Build the virtual→real map and register each `<script>` block as a virtual
  // ts-morph source. Files without a usable `<script>` block are silently
  // skipped (template/style-only SFCs contribute nothing to the import graph).
  const vueMap = Object.create(null); // virtualPath → realPath
  const vueReal = Object.create(null); // realPath → true (for resolver)
  for (const f of vueFiles) {
    let text; try { text = readFileSync(f, "utf8"); } catch { continue; }
    const block = extractVueScripts(text);
    if (!block || !block.text.trim()) continue;
    const vpath = vueVirtualPath(f, block.lang);
    project.createSourceFile(`${cwdp}/${vpath}`, block.text, { overwrite: true });
    vueMap[`${cwdp}/${vpath}`] = `${cwdp}/${f}`;
    vueReal[`${cwdp}/${f}`] = true;
  }
  return { project, vueMap, vueReal, aliasOpts, packageAliasConfigs, workspacePackages };
}

// ---------------------------------------------------------------------------
// extractFacts() — the language-BACKEND boundary. Parse the repo and return
// per-file "facts": for each in-project source file, its exported symbols, the
// files it imports (+ the named symbols crossing each edge), pass-through
// re-exports, and which export is `default`. This is the ONLY function that
// knows about ts-morph and Vue SFCs; build() assembles the graph + rankings
// from these facts and is backend-agnostic. A second language = a second
// producer of this same shape (the Batch 2 seam). Operates on process.cwd().
//
// Returns { [relPath]: {
//   exports:         [{ name, kind, definedIn?, external? }], // definedIn = the real
//                      declaration site when this entry only re-exports the name
//                      (checker-resolved through any number of barrel hops);
//                      external = the origin is outside the repo. Both absent for
//                      a genuine local definition, so non-barrel repos are unchanged.
//   locals:          [{ name, kind }],                  // non-exported top-level decls — discovery-only (--find/--any), NOT ranked
//   imports:         [targetPath…],                    // = Object.keys(importedSymbols)
//   importedSymbols: { [targetPath]: [names…] },        // "default"/"*" still literal
//   defaultExportName: string | null,                   // resolved default-export name
//   reExports:       [names…],                          // pass-through re-exports (barrels)
//   typeOnlyImports: [targetPath…],                    // compile-time-only deps — disjoint
//                      from `imports`, never fed to PageRank/edgeCoverage/ranking
//   typeOnlyDependents: [sourcePath…],                 // the inverse; absent when empty
//   rsc:             'client' | 'server',                // React Server/Client boundary directive — absent if none
// } }
// A single pathological file is skipped + warned, never fatal (graceful degrade).
// ---------------------------------------------------------------------------
function extractFacts(inc = null) {
  // Resolve backend scoping fresh per build: read .agentmapignore from disk and
  // snapshot the --include-dts flag. Both default to "no change" (null matcher,
  // false flag) so a repo with neither is byte-identical to pre-feature behavior.
  const ignoreMatcher = loadIgnoreMatcher();
  const includeDts = INCLUDE_DTS;
  const { project, vueMap, vueReal, aliasOpts, packageAliasConfigs, workspacePackages } = makeProject(inc);
  const { SyntaxKind } = tsMorph();
  const CallExpression = SyntaxKind.CallExpression;
  const cwd = process.cwd().replace(/\\/g, "/");
  // rel() rewrites ts-morph file paths to repo-relative keys. For Vue virtual
  // sources (`App.vue.ts`), vueMap rewrites back to the real `.vue` path so
  // users never see virtual paths in the map, hubs, --relates, or --find.
  const rel = (p) => {
    const abs = p.replace(/\\/g, "/");
    const real = vueMap[abs];
    return (real || abs).replace(cwd + "/", "");
  };
  const files = {};
  // PATH-SEGMENT exclusion (not substring) so e.g. components/.next-demo or
  // src/node_modules_helper.ts are NOT wrongly excluded.
  const excluded = (p) => { const segs = p.split("/"); return segs.includes("node_modules") || segs.includes(".next") || (ignoreMatcher !== null && ignoreMatcher(p)); };

  // Map-health counters (fed into edgeCoverage / the degraded signal in
  // assemble). We only tally import sites that LOOK repo-local — relative
  // (`./`, `../`) or an alias sigil (`@/`, `~/`, `~`, `#`) that's never a valid
  // bare package name — so React/Next/etc. node_modules imports don't drag the
  // coverage down on a perfectly healthy repo. A local-looking site is "resolved"
  // when it lands a non-excluded in-project edge; when a whole repo's aliases live
  // only in vite.config/webpack (which we don't read) they all miss → coverage
  // collapses toward 0, which is the honest signal we surface.
  let localSites = 0, resolvedSites = 0;
  const ALIAS_SIGIL = /^(@[\\/]|~[\\/]|~$|#)/;
  const expectedLocal = (spec) => spec.startsWith(".") || ALIAS_SIGIL.test(spec);

  // Resolve a relative module specifier (from the importing file's dir) to an
  // in-project source file key. Tries the bare path, then each extension, then
  // /index.*. Returns the rel key or null. Powers side-effect (6b) + dynamic
  // import()/require() (6c) edges that ts-morph's specifier resolution skips.
  const RES_EXT = CODE_EXT;
  // posix-join that collapses "" / "." / ".." segments (no fs access).
  const joinPosix = (a, b) => {
    const parts = (a + "/" + b).split("/"); const st = [];
    for (const seg of parts) { if (seg === "" || seg === ".") continue; if (seg === "..") st.pop(); else st.push(seg); }
    return (a.startsWith("/") ? "/" : "") + st.join("/");
  };
  // resolve an absolute-ish path to an in-project source file, honoring
  // extensionless + /index.* + .vue resolution (shared by relative + alias paths).
  const tryResolveAt = (abs, allowEmittedExt = true) => {
    if (vueReal[abs]) return rel(abs);
    let sf = project.getSourceFile(abs);
    if (!sf) for (const e of RES_EXT) { sf = project.getSourceFile(`${abs}.${e}`); if (sf) break; }
    if (!sf) for (const e of RES_EXT) { sf = project.getSourceFile(`${abs}/index.${e}`); if (sf) break; }
    if (sf) return rel(sf.getFilePath());
    if (vueReal[`${abs}.vue`]) return rel(`${abs}.vue`);
    // Under `moduleResolution: nodenext`, a TS source imports its sibling by the
    // EMITTED specifier — `./consts.js` for `consts.ts`. This ladder is the ONLY
    // resolution path for per-package tsconfig aliases (resolveAlias below), so
    // without this rung every `~/x.js`-style alias edge in a monorepo is dropped
    // and the target reports zero dependents. Strip the emitted extension once
    // and re-run. Literal paths are tried FIRST above, so a real .js file still
    // wins over a .ts sibling of the same name in a mixed repo.
    if (allowEmittedExt) {
      const m = /\.(js|jsx|mjs|cjs)$/.exec(abs);
      if (m) return tryResolveAt(abs.slice(0, -m[0].length), false);
    }
    return null;
  };
  // #3 fix + monorepo: tsconfig/jsconfig baseUrl+paths alias resolution ("@/x",
  // "#/x", "~/x") for side-effect/dynamic/require edges AND static imports when
  // ts-morph can't resolve (cwd tsconfig lacks package paths). Per importing
  // file, use the nearest discovered config's paths. Node package.json "imports"
  // maps (`#internal/*`) are normalized into this SAME paths shape upstream
  // (discoverPackageAliasConfigs), so a `#`-prefixed specifier resolves here too.
  const ROOTABS = process.cwd().replace(/\\/g, "/");
  const resolveAlias = (spec, fromAbsDir) => {
    const cfg = nearestAliasConfig(fromAbsDir, packageAliasConfigs, ROOTABS, aliasOpts);
    const aliasBase = cfg.baseUrl || cfg.dir; // baseUrl is already absolute (anchored at read time)
    // TS `paths` precedence: an EXACT (no `*`) pattern wins over any wildcard, and
    // among wildcards the LONGEST fixed prefix wins — not source/JSON order. Sort
    // by descending specificity (stable, so equal-specificity aliases keep order,
    // keeping non-overlapping-alias repos byte-identical).
    const aliasEntries = Object.entries(cfg.paths || {}).sort((a, b) => {
      const sa = a[0].indexOf("*"), sb = b[0].indexOf("*");
      const exactA = sa === -1, exactB = sb === -1;
      if (exactA !== exactB) return exactA ? -1 : 1;              // exact beats wildcard
      return (exactB ? b[0].length : sb) - (exactA ? a[0].length : sa); // longer prefix wins
    });
    for (const [pat, targets] of aliasEntries) {
      const star = pat.indexOf("*");
      let sub = null;
      if (star === -1) { if (spec === pat) sub = ""; else continue; }
      else {
        const pre = pat.slice(0, star), suf = pat.slice(star + 1);
        if (spec.length < pre.length + suf.length || !spec.startsWith(pre) || !spec.endsWith(suf)) continue;
        sub = spec.slice(pre.length, spec.length - suf.length);
      }
      for (const tRaw of (Array.isArray(targets) ? targets : [targets])) {
        const tStar = tRaw.indexOf("*");
        const candidate = tStar === -1 ? tRaw : tRaw.slice(0, tStar) + sub + tRaw.slice(tStar + 1);
        const hit = tryResolveAt(joinPosix(aliasBase, candidate));
        if (hit) return hit;
      }
    }
    return null;
  };
  // Workspace cross-package resolution (pnpm/npm/yarn workspaces): a BARE
  // specifier that equals a workspace package NAME (`@org/pkg`) or is a subpath of
  // one (`@org/pkg/sub`) resolves to that package's SOURCE. Bare name → the entry
  // candidates (src/index.* preferred); subpath → a declared "exports" subpath
  // target, else the naive package dir + subpath, run through the same
  // tryResolveAt ladder (extensionless / .ext / /index.ext / .vue). Returns a rel
  // key or null (miss → fall through to alias resolution, so a workspace name that
  // also matches a tsconfig alias still resolves). No named workspace package.json
  // ⇒ workspacePackages is empty ⇒ this never fires.
  const resolveWorkspace = (spec) => {
    if (spec.startsWith(".")) return null;
    for (const name in workspacePackages) {
      const { dir, entries, subpaths } = workspacePackages[name];
      if (spec === name) {                                      // bare package import → "." entry
        for (const e of entries) { const hit = tryResolveAt(joinPosix(dir, e)); if (hit) return hit; }
      } else if (spec.startsWith(name + "/")) {                 // subpath import
        const sub = spec.slice(name.length + 1);
        // Prefer a declared "exports" subpath target ("./button" → src/…); else
        // fall back to the naive package-dir + subpath (source mirroring the
        // import path, the layout when there's no "exports" map).
        // Declared targets first, in precedence order, each tried until one exists
        // on disk; then the naive package-dir + subpath (the layout when a package
        // declares no "exports" map at all).
        for (const m of matchSubpath(subpaths, sub) || []) {
          const hit = tryResolveAt(joinPosix(dir, m));
          if (hit) return hit;
        }
        return tryResolveAt(joinPosix(dir, sub));
      }
    }
    return null;
  };
  // Resolve a module specifier to an in-project file key. A relative specifier is
  // joined against the importer's dir and handed to tryResolveAt — which already
  // encodes the full precedence ladder (exact `.vue` wins → extensionless →
  // `.ext` TS/JS shadow → `/index.ext` → `.vue` fallback). A bare specifier tries
  // workspace package resolution first (monorepo cross-package), then the
  // tsconfig/jsconfig alias resolver. (The relative branch used to re-implement
  // tryResolveAt's ladder behind a `join` local that shadowed joinPosix —
  // collapsed here to the one shared joinPosix + tryResolveAt.)
  const resolveSpec = (fromAbsDir, spec) =>
    spec.startsWith(".") ? tryResolveAt(joinPosix(fromAbsDir, spec)) : (resolveWorkspace(spec) || resolveAlias(spec, fromAbsDir));

  const sourceFiles = project.getSourceFiles();
  // In incremental mode only the changed files carry real content; the rest are
  // empty resolution stubs. Extract facts for the changed set only (stubs would
  // otherwise overwrite good cached facts with empty ones).
  const only = inc ? new Set(inc.changed) : null;
  // Every file that threw during parse and so never made it into `files`. Handed to
  // assemble() on a non-enumerable property (see the stash below) so a truncated map
  // can declare itself instead of reporting a truthful-looking count over survivors.
  const skipped = [];
  process.stderr.write(`# agentmap: parsing ${only ? only.size : sourceFiles.length} source files${inc ? " (incremental)" : ""}…\n`);
  for (const sf of sourceFiles) {
    const path = rel(sf.getFilePath());
    if (excluded(path)) continue;
    // `.d.ts` default-exclude: skip a declaration file as its OWN map node so its
    // (often generated, huge) symbols never pollute --find/--symbols/--hubs. It
    // stays a live import-RESOLUTION target — an importer that resolves to it
    // still records the edge in its own importedSymbols/imports (addEdge below
    // checks excluded(), not membership in `files`). --include-dts restores the
    // old behavior (the .d.ts becomes a full node again).
    if (!includeDts && path.endsWith(".d.ts")) continue;
    if (only && !only.has(path)) continue;
    try {
    const fromDir = sf.getDirectoryPath().replace(/\\/g, "/");
    const reExports = new Set(); // #2: names that are pass-through re-exports, not real uses
    // Files this file re-exports FROM (`export … from './x'`). Its `exports` list
    // transitively includes those targets' exports (getExportedDeclarations follows
    // the re-export), so re-parsing it in incremental mode against EMPTY stubs would
    // drop them. Tier 2 declines incremental when a re-export touches the changed
    // set. INTERNAL — stripped in assemble() so it never reaches map.json.
    const reExportsFrom = new Set();
    // exports, remembering which exported name was the file's DEFAULT export so
    // default-import edges can later resolve "default" → the real symbol name.
    let defaultExportName = null;
    // getExportedDeclarations() resolves through re-export barrels transitively via
    // the checker, so d[0] is ALREADY the origin declaration — `export *`, named,
    // renamed and multi-hop all land on the true site. Recording where it lives
    // costs one pointer read on a node we just materialised, and it is the only
    // signal that distinguishes a barrel's pass-through entry from a real
    // definition: `reExports` is built from named specifiers alone, so a star
    // barrel looks identical to a definer without this.
    const exports = [...sf.getExportedDeclarations()].map(([name, d]) => {
      const resolved = name === "default" ? (d[0]?.getName?.() ?? "default") : name;
      if (name === "default") defaultExportName = resolved;
      const originAbs = d[0]?.getSourceFile?.()?.getFilePath?.().replace(/\\/g, "/") ?? null;
      let via = {};
      if (originAbs) {
        // "Inside the repo" is decided by whether rel() actually stripped the cwd
        // prefix, not by re-deriving the test here — a second copy of that rule
        // could disagree with the one every other path in the map is built from
        // (Windows drive-letter casing being the obvious way).
        const op = rel(originAbs);
        const inRepo = op !== originAbs;
        // A dependency's declaration is not a place an agent may edit, and the
        // graph holds no node there — say "external", never a node_modules path.
        // `path` is rel(sf.getFilePath()) — for a Vue SFC both sides map back
        // through vueMap, so a file never reports itself as its own origin.
        if (op !== path) via = (!inRepo || excluded(op)) ? { external: true } : { definedIn: op };
      }
      return { name: resolved, kind: d[0]?.getKindName?.() ?? "?", ...via };
    });
    // Non-exported TOP-LEVEL declarations → `locals`, so --find/--any can surface a
    // private helper for reuse-before-rebuild. These NEVER enter rankSymbols/--map/
    // --hubs (assemble reads only `exports`), so the ranked digest is unaffected.
    // ts-morph's direct top-level getters (and getVariableStatements) return
    // module-scope decls only — they don't descend into function bodies — giving
    // the top-level-only guarantee for free; the exportedNames dedupe skips anything
    // getExportedDeclarations() already covers.
    const exportedNames = new Set(exports.map((e) => e.name));
    const locals = [];
    const seenLocal = new Set();
    const pushLocal = (decl) => {
      const nm = decl.getName?.();
      if (!nm || exportedNames.has(nm) || seenLocal.has(nm)) return;
      if (decl.isExported?.() || decl.hasExportKeyword?.() || decl.isDefaultExport?.()) return;
      seenLocal.add(nm);
      locals.push({ name: nm, kind: decl.getKindName?.() ?? "?" });
    };
    for (const d of sf.getFunctions()) pushLocal(d);
    for (const d of sf.getClasses()) pushLocal(d);
    for (const d of sf.getInterfaces()) pushLocal(d);
    for (const d of sf.getTypeAliases()) pushLocal(d);
    for (const d of sf.getEnums()) pushLocal(d);
    for (const vs of sf.getVariableStatements()) {
      if (vs.hasExportKeyword?.()) continue; // `export const …` already in getExportedDeclarations()
      for (const d of vs.getDeclarations()) pushLocal(d);
    }
    // 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 || excluded(tp)) return;
      (importedSymbols[tp] ??= []).push(...names);
    };
    // A fully `import type` / `export type` declaration is not a runtime edge and
    // must stay out of PageRank — but dropping it outright made the file it points
    // at look unused. Measured on vercel/chatbot@c2f8235: lib/types.ts has 23
    // importers, every one of them type-only, and --relates reported `dependents
    // (0)` — indistinguishable from an orphan. These land in a SEPARATE field so
    // the runtime graph, edgeCoverage and symbol ranking are all untouched.
    const typeOnly = new Set();
    const addTypeEdge = (tp) => { if (tp && !excluded(tp)) typeOnly.add(tp); };
    for (const imp of sf.getImportDeclarations()) {
      // Fully erased at compile time — either `import type {…}`, or a plain import
      // whose every named specifier is individually `type` with no default or
      // namespace binding. `import { type A } from "./x"` emits NOTHING, so it is
      // not a runtime dependency; the `["*"]` fallback further down cannot tell,
      // because once the type specifiers are filtered out it looks identical to a
      // side-effect `import "./x"` — which does run. The specifier COUNT separates
      // them. This shape is what @typescript-eslint's consistent-type-imports
      // writes under fixStyle:"inline-type-imports", so it is common, and it was
      // fabricating a runtime edge and inflating the target's PageRank.
      const named = imp.getNamedImports();
      const erased = imp.isTypeOnly()
        || (named.length > 0 && named.every((n) => n.isTypeOnly()) && !imp.getDefaultImport() && !imp.getNamespaceImport());
      if (erased) {
        const t0 = imp.getModuleSpecifierSourceFile();
        addTypeEdge(t0 ? rel(t0.getFilePath()) : resolveSpec(fromDir, imp.getModuleSpecifierValue()));
        continue; // type-only modules must not inflate runtime PageRank
      }
      // Map-health: a repo-local-looking specifier is one edgeCoverage counts.
      const local = expectedLocal(imp.getModuleSpecifierValue());
      if (local) localSites++;
      const t = imp.getModuleSpecifierSourceFile();
      if (t) {
        // skip individual type-only named specifiers (`import { type X }`)
        const names = imp.getNamedImports().filter((n) => !n.isTypeOnly()).map((n) => n.getName());
        if (imp.getDefaultImport()) names.push("default"); // resolved to the real name in a post-pass below
        if (imp.getNamespaceImport()) names.push("*");
        const tp = rel(t.getFilePath());
        if (local && !excluded(tp)) resolvedSites++; // landed a non-excluded in-project edge
        addEdge(tp, names.length ? names : ["*"]);
      } else {
        // 6b: side-effect or alias import — ts-morph may not resolve when cwd
        // tsconfig lacks package paths; resolveSpec uses nearest tsconfig paths.
        const spec = imp.getModuleSpecifierValue();
        const tp = resolveSpec(fromDir, spec);
        if (tp) {
          const names = imp.getNamedImports().filter((n) => !n.isTypeOnly()).map((n) => n.getName());
          if (imp.getDefaultImport()) names.push("default");
          if (imp.getNamespaceImport()) names.push("*");
          if (local && !excluded(tp)) resolvedSites++; // resolved via nearest tsconfig alias
          addEdge(tp, names.length ? names : ["*"]);
        }
      }
    }
    for (const exp of sf.getExportDeclarations()) {
      const t = exp.getModuleSpecifierSourceFile();
      // `export { X } from "<spec>"` forwards X; it never declares it. That is true
      // of the syntax alone, so ownership must not hinge on <spec> resolving —
      // a workspace package with no node_modules installed resolves to nothing,
      // and the file was then scored as a rival DEFINITION of every name it merely
      // forwards, which made --callers fail the whole query as "ambiguous".
      // A bare `export { local }` (no `from`) does declare, hence the specifier
      // check. `export * from "<unresolvable>"` stays uncovered — its names are
      // unknowable without resolving the target.
      if (!t && exp.getModuleSpecifierValue()) {
        for (const n of exp.getNamedExports()) reExports.add(n.getName());
      }
      // Same erasure rule as imports. `export { type X } from "./z"` re-exports
      // nothing at runtime, but note `export * from "./z"` DOES — and it also has
      // zero named specifiers, so the count is again what distinguishes them.
      const namedExp = exp.getNamedExports();
      if (exp.isTypeOnly() || (namedExp.length > 0 && namedExp.every((n) => n.isTypeOnly()))) {
        if (t) addTypeEdge(rel(t.getFilePath()));
        continue; // type-only re-exports excluded from RUNTIME edges
      }
      if (t) {
        const tp = rel(t.getFilePath());
        const names = exp.getNamedExports().filter((n) => !n.isTypeOnly()).map((n) => n.getName());
        addEdge(tp, names);                     // keep the FILE-level edge (barrel depends on origin)
        reExportsFrom.add(tp);                  // this file's exports transitively depend on tp's content
        for (const n of names) reExports.add(n); // #2: mark as re-export so rankSymbols won't count it as a reference
      }
    }
    // 6c: dynamic import("./x") and require("./x") with relative, in-project
    // string-literal specifiers → edge with names ["*"]. Prefilter on raw text
    // so we only AST-walk the few files that actually contain a dynamic call.
    const srcText = sf.getFullText();
    if (srcText.includes("import(") || srcText.includes("require(")) for (const call of sf.getDescendantsOfKind(CallExpression)) {
      const expr = call.getExpression();
      const kind = expr.getKind();
      const isImport = kind === SyntaxKind.ImportKeyword;
      const isRequire = expr.getText?.() === "require";
      if (!isImport && !isRequire) continue;
      const a0 = call.getArguments()[0];
      if (!a0 || a0.getKind() !== SyntaxKind.StringLiteral) continue;
      const tp = resolveSpec(fromDir, a0.getLiteralText());
      if (tp) addEdge(tp, ["*"]);
    }
    const imports = Object.keys(importedSymbols);
    const rsc = rscBoundary(sf, SyntaxKind);
    // Disjoint from `imports`: when a file also pulls something at runtime from the
    // same target, the runtime edge is the stronger claim and the weaker one would
    // just double-count the target in two arrays.
    const typeOnlyImports = [...typeOnly].filter((tp) => !importedSymbols[tp]).sort();
    files[path] = { exports, locals, imports, importedSymbols, defaultExportName, reExports: [...reExports], reExportsFrom: [...reExportsFrom], ...(rsc ? { rsc } : {}), ...(typeOnlyImports.length ? { typeOnlyImports } : {}) };
    } catch (e) {
      // #1 fix: a single pathological file (malformed import specifier, ts-morph
      // edge case) must NOT abort the whole map — skip it + warn, preserving the
      // graceful-degradation contract agentmap advertises.
      //
      // Warning alone was not enough, and that was the bug: the file never reached
      // `files[path]`, so map.json reported a fileCount over the SURVIVORS with
      // degraded:false and exit 0, while --relates/--find answered confidently about
      // a graph the file had never been in. The only trace was one stderr line that
      // scrolls away (run() in test/helpers.mjs discards stderr on a zero exit, so
      // even the suite could not see it). Record every skip so the map can say so.
      //
      // A RangeError is classified apart because it is not a malformed file:
      // getExportedDeclarations() (:1354) recurses through `export * from` barrel
      // chains and blows the JS stack at ~3500-4000 links. The user-facing fix is
      // different — flatten the barrel chain, not fix a typo.
      const msg = String(e?.message ?? e);
      skipped.push({ file: path, reason: (e instanceof RangeError || /call stack/i.test(msg)) ? "stack-overflow" : "parse-error" });
      process.stderr.write(`# agentmap: skipped ${path} (parse error: ${msg})\n`);
    }
  }
  // Stash map-health counters on a NON-ENUMERABLE property so assemble() can read
  // them without them ever reaching map.json (JSON.stringify / for-in / Object.*
  // and structuredClone all skip non-enumerable props — verified byte-safe). Only
  // on a full parse: an incremental run parses just the changed files, so its
  // counts would be partial and are recomputed as null downstream instead.
  if (!inc) Object.defineProperty(files, "__edgeStats", { value: { localSites, resolvedSites }, enumerable: false, configurable: true });
  // Same carrier, same byte-safety argument, for the skip ledger. Set unconditionally
  // (an incremental parse can throw too); assemble() decides what to EMIT, gated on
  // target the same way edgeCoverage is.
  Object.defineProperty(files, "__skipped", { value: skipped, enumerable: false, configurable: true });
  return files;
}

// ---------------------------------------------------------------------------
// build() — backend-agnostic assembly. Take per-file facts from extractFacts(),
// resolve default-import edges, invert dependents, group features, compute file
// PageRank + the Aider-style symbol ranking, pick hubs, and persist the cache.
// Knows nothing about ts-morph / Vue — swapping the backend never touches this.
// ---------------------------------------------------------------------------
function build({ target = MAP, extra = null } = {}) {
  const t0 = Date.now();
  return assemble(extractFacts(), { target, extra, t0 });
}

// assemble() — the backend-agnostic graph assembly + persistence shared by the
// full build() and the Tier 2 incremental rebuild. Takes raw per-file facts
// (exports/imports/importedSymbols/defaultExportName/reExports), resolves
// default-import edges, inverts dependents, groups features, computes file
// PageRank + the Aider-style symbol ranking, picks hubs, and persists the cache.
// MUTATES `files`, so incremental passes a disposable copy.
function assemble(files, { target = MAP, extra = null, t0 = Date.now() } = {}) {
  // Snapshot raw facts BEFORE the mutations below so a CLEAN build can persist
  // them (Tier 2) for a later incremental rebuild. Clean builds only — a dirty or
  // incremental build never re-bases off its own output.
  const rawFacts = target === MAP ? structuredClone(files) : null;
  // 7: resolve default-import edges. A default import was recorded literally as
  // "default"; rankSymbols skips "default", so default-exported symbols (the
  // dominant Next.js component) never ranked. Map each "default" entry to the
  // TARGET file's resolved default-export name so it forms reference edges.
  for (const f of Object.values(files)) {
    for (const tp of Object.keys(f.importedSymbols)) {
      const dn = files[tp]?.defaultExportName;
      if (!dn || dn === "default") continue;
      f.importedSymbols[tp] = f.importedSymbols[tp].map((n) => (n === "default" ? dn : n));
    }
  }
  // Invert imports → dependents (who imports each file). Derived purely from the
  // facts, in the same file/import iteration order the in-loop build used, so the
  // per-file dependents arrays stay byte-identical.
  const dependents = {};
  for (const [p, f] of Object.entries(files)) for (const tp of f.imports) (dependents[tp] ??= []).push(p);
  for (const p in files) files[p].dependents = dependents[p] ?? [];
  // Same inversion for the compile-time-only edges, kept in its own field so
  // `dependents` keeps meaning exactly "would break at runtime".
  const typeDependents = {};
  for (const [p, f] of Object.entries(files)) for (const tp of (f.typeOnlyImports || [])) (typeDependents[tp] ??= []).push(p);
  for (const p in files) if (typeDependents[p]?.length) files[p].typeOnlyDependents = typeDependents[p];

  // Group files into features (first real app/ route segment) from their paths.
  const features = {};
  for (const p of Object.keys(files)) { const feat = featureOf(p); if (feat) (features[feat] ??= []).push(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);

  // Lexical (BM25) index: one doc per symbol, token bag = split(name) + split(path
  // minus ext) + feature + kind. Pure term-frequency counting — no ts-morph, no
  // type-checker, O(tokens) — capped so a giant monorepo can't bloat map.json.
  // Powers --search + the --any lexical rung. Additive; rides build()/dirty/
  // incremental alike (shared assemble). SCHEMA_VERSION was bumped to 5 for it.
  const lexDocs = [];
  const df = Object.create(null);
  for (const [p, f] of Object.entries(files)) {
    if (lexDocs.length >= LEXICAL_DOC_LIMIT) break;
    const pathToks = splitIdent(p.replace(CODE_EXT_RE, "").replace(/\.vue$/, ""));
    const feat = featureOf(p);
    const featToks = feat ? splitIdent(feat) : [];
    for (const e of [...(f.exports || []), ...(f.locals || [])]) {
      if (lexDocs.length >= LEXICAL_DOC_LIMIT) break;
      const kind = (e.kind || "").replace(/Declaration$/, "").toLowerCase();
      const toks = [...splitIdent(e.name), ...pathToks, ...featToks, kind].filter(Boolean);
      const tf = Object.create(null);
      for (const t of toks) tf[t] = (tf[t] || 0) + 1;
      for (const t of Object.keys(tf)) df[t] = (df[t] || 0) + 1;
      lexDocs.push({ file: p, name: e.name, kind: e.kind, tf, len: toks.length });
    }
  }
  const avgdl = lexDocs.length ? lexDocs.reduce((s, d) => s + d.len, 0) / lexDocs.length : 0;
  const lexical = { N: lexDocs.length, avgdl: +avgdl.toFixed(4), df, docs: lexDocs };

  // 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, HUBS_LIMIT)
    .map(([p, pr, deg]) => `${p} (deg ${deg}, pr ${pr})`);

  // defaultExportName was only needed for the fix-#7 post-pass, and reExportsFrom
  // only for Tier 2's re-export gate — drop both before persisting so the on-disk
  // `files` shape (map.json) stays byte-identical.
  for (const p of nodes) { delete files[p].defaultExportName; delete files[p].reExportsFrom; }

  // Map health: fraction of repo-local-looking import sites that resolved to an
  // in-project edge. Reported for the CLEAN full build only (target === MAP): a
  // dirty rebuild (map.dirty.json, either tier) is modify-only on an already-mapped
  // repo, and — critically — the Tier-2 incremental path parses only the changed
  // files, so it carries no whole-repo __edgeStats. Gating on target keeps the full
  // and incremental dirty builds BYTE-IDENTICAL (both → null), the invariant the
  // incremental suite asserts. __edgeStats rides in on a full parse (non-enumerable,
  // so it never reached JSON). No local sites at all (0) → null, not 0/0.
  const es = target === MAP ? files.__edgeStats : null;
  const edgeCoverage = es && es.localSites > 0 ? +(es.resolvedSites / es.localSites).toFixed(4) : null;
  // Degraded = a non-trivial repo where almost no local imports resolved — the
  // "154 files, 3 edges" garbage-framed-as-success case. High bar (fileCount>10 &&
  // coverage<0.15) so a normal healthy repo (coverage near 1) never trips it.
  const degraded = edgeCoverage !== null && nodes.length > 10 && edgeCoverage < 0.15;

  // Truncation accounting. `degraded` says "the edges are bad"; `incomplete` says
  // "files are MISSING" — strictly worse, because --relates/--find then answer
  // confidently about a graph that never contained the file.
  // Same `target === MAP` gate as edgeCoverage, for the same reason: a Tier-2
  // incremental parse sees only the changed files, so its ledger would be a strict
  // subset of a full dirty build's. Gating keeps BOTH map.dirty.json producers
  // emitting nothing, preserving the byte-identity invariant test/incremental.test.mjs
  // asserts. Every field is spread CONDITIONALLY (same idiom as `rsc`), so a repo that
  // indexed every file serialises byte-identically to schema 6.
  const skips = (target === MAP && files.__skipped) || [];
  const skippedList = skips.slice(0, SKIPPED_LIST_LIMIT);
  const truncation = skips.length
    ? {
        incomplete: true,
        skippedCount: skips.length,          // always exact, even when the list is capped
        skipped: skippedList,
        ...(skips.length > skippedList.length ? { skippedTruncated: true } : {}),
      }
    : {};

  const sha = currentSha();
  const out = {
    schema: SCHEMA_VERSION, generatedSha: sha, dirty: dirtyCount(), fileCount: nodes.length,
    edgeCoverage, degraded, ...truncation,
    // fingerprint lets non-git repos (sha === "") trust the cache across runs.
    fingerprint: sha ? undefined : sourceFingerprint(),
    hubs, features, rankedSymbols: rankedSymbols.slice(0, RANKED_SYMBOLS_LIMIT), lexical, files,
  };
  // `extra` (dirty-map cache key etc.) is merged for non-default targets only;
  // a default clean build passes extra=null so map.json stays byte-identical.
  if (extra) Object.assign(out, extra);
  mkdirSync(".claude/agentmap", { recursive: true });
  // Atomic write: tmp + rename so a concurrent background rebuild can never
  // expose a torn/truncated map to a reader.
  //
  // The tmp name is PID-SUFFIXED, and that is load-bearing, not cosmetic. A fixed
  // `target + ".tmp"` is the SAME literal path in every process, and nothing on the
  // CLI/MCP query path holds a lock (only hooks/post-commit does, and only for its
  // own invocations) — so two agent sessions querying one repo at the same time
  // both land here. Measured on 150 files x 6 concurrent processes: the winner
  // renames the shared tmp away, and every loser's renameSync then throws an
  // uncaught `ENOENT: rename '.claude/agentmap/map.json.tmp'`, which propagates
  // out of assemble() -> build() -> ensureFresh() -> main() and hard-crashes an
  // ordinary query (there is no top-level catch). Per-writer tmp paths remove the
  // shared name entirely; renameSync stays atomic per writer and the last rename
  // to land wins, which is the same "last build wins" outcome as before — just
  // without the crash. (Torn output was the hypothesised failure and did NOT
  // reproduce: 0 tears in 8 synthetic rounds at 6MB and 96MB payloads. The crash
  // is the real one, and it is near-deterministic under a synchronized barrier.)
  const tmp = `${target}.${process.pid}.tmp`;
  writeFileSync(tmp, JSON.stringify(out));
  renameSync(tmp, target);
  // Tier 2: persist the raw facts snapshot for CLEAN git builds so a later dirty
  // query can reparse only the changed files instead of the whole repo. Never
  // fatal — the snapshot is a pure optimization.
  // NOT written from a TRUNCATED build: buildIncremental() merges cached facts for
  // every file it does not re-parse, so a partial snapshot would make later dirty
  // queries inherit the missing files as permanent absences. An older COMPLETE
  // snapshot at the same sha survives untouched and stays usable.
  if (rawFacts && sha && !skips.length) {
    try {
      // PID-suffixed for the same reason as the map write above. This one is
      // already inside a catch-all, so the shared path did not crash the query —
      // it silently lost the snapshot instead, making the next dirty query fall
      // back to a full reparse for no visible reason.
      const ftmp = `${FACTS}.${process.pid}.tmp`;
      writeFileSync(ftmp, JSON.stringify({ schema: SCHEMA_VERSION, generatedSha: sha, facts: rawFacts }));
      renameSync(ftmp, FACTS);
    } catch {}
  }
  process.stderr.write(`# agentmap: built ${nodes.length} files in ${Date.now() - t0}ms${skips.length ? ` (${skips.length} skipped — map is INCOMPLETE)` : ""}\n`);
  // Map-health signal — clean full build only (target === MAP), so a dirty query's
  // map.dirty.json rebuild never repeats it. One honest line when the map is empty
  // or almost nothing connected, so a stranger doesn't read "built 0 files" / a
  // flat map as success and uninstall.
  if (target === MAP) {
    // The census runs BEFORE the generic warnings, because "0 source files" is
    // the least useful thing to tell someone whose repo is 400 Python files —
    // that reads as a bug in agentmap rather than as "wrong tool, and here is
    // where to say so". Opt out with AGENTMAP_NO_CENSUS=1.
    const census = process.env.AGENTMAP_NO_CENSUS ? null : languageCensus(gitListFiles());
    if (census) {
      const pct = Math.round(census.share * 100);
      process.stderr.write(
        `⚠ ${census.count} ${census.lang} file${census.count === 1 ? "" : "s"} (${pct}% of this repo) vs ${census.supported} TS/JS/Vue. `
        + `agentmap is TS/JS-only today — ${census.lang} is not indexed.\n`
        + `  Want ${census.lang}? React to ${VOTE_URL} — reactions are how this gets prioritized.\n`
        + `  (silence: AGENTMAP_NO_CENSUS=1)\n`,
      );
    }
    // Truncation gets its OWN block, not a branch of the degraded chain: a build can
    // be both truncated and degraded, and truncation is the more actionable of the
    // two (files missing outright, not just edges unresolved).
    if (skips.length) {
      const nStack = skips.filter((s) => s.reason === "stack-overflow").length;
      process.stderr.write(
        `⚠ INCOMPLETE map: ${skips.length} of ${nodes.length + skips.length} files were not indexed`
        + `${nStack ? ` — ${nStack} blew the JS stack (usually a very deep \`export * from\` barrel chain)` : ""}`
        + `. --relates / --find / --hubs will under-report.\n`
        + `  \`agentmap --doctor\` lists the skipped files.\n`,
      );
    }
    if (nodes.length === 0) {
      process.stderr.write("⚠ 0 source files found (repo not git-tracked? non-standard dir layout?)\n");
    } else if (degraded) {
      // Do NOT reinstate the old "aliases from vite.config/webpack aren't read
      // yet" line: VITE_CONFIG_RE (:579) probes vite/vitest/webpack configs and
      // readBundlerAliasEntries() (:587) AST-parses their resolve.alias, covered
      // by test/vite-alias.test.mjs. That message sent users to mirror aliases
      // into tsconfig paths — work the tool had already done — and hid the real
      // causes below.
      // tsconfig `references` is NOT listed here. It was, briefly, and that was
      // wrong: project references govern build order and declaration output, not
      // module resolution, and file discovery already ignores tsconfig `include`
      // entirely (see the git ls-files pass in makeProject). Measured across
      // solution-style / narrow-include / partial-include / no-tsconfig layouts —
      // all index the full repo. See test/monorepo-shapes.test.mjs.
      process.stderr.write(`⚠ ${nodes.length} files, ${fileEdges.length} import edge${fileEdges.length === 1 ? "" : "s"} resolved — most imports unresolved. Known gaps: computed aliases (function/regex/URL idioms) in bundler configs, which are skipped, and package-name imports with no \`paths\` entry and no workspace \`package.json\` (TypeScript cannot resolve those either). Run \`agentmap --doctor\`, or file an issue with your config layout.\n`);
    }
  }
  return out;
}

// Resolve `--symbols n` / the `symbols` MCP tool against a cached map.
//
// `map.json` persists only the top RANKED_SYMBOLS_LIMIT (80) symbols, so asking
// for more used to print "top 200 ranked symbols" above at most 80 rows: the
// count described the REQUEST, not the output, with nothing saying so. When n
// exceeds what was persisted, re-rank from the cached file map rather than
// truncating — rankSymbols() reads `files` only, which is the same ts-morph-free
// recompute the `--map --focus` path already performs, so this costs a graph walk
// over data already in memory and no rebuild. Falls back to the stored slice if
// the recompute cannot run (a pre-schema-7 cache with no `files`), because a
// short answer beats a thrown one. Callers report `shown` so a repo that simply
// has fewer ranked symbols than requested is distinguishable from a cap.
function rankedSymbolsFor(data, n) {
  const stored = data.rankedSymbols || [];
  if (n <= stored.length) return stored.slice(0, n);
  try {
    const full = rankSymbols(data.files || {}, null);
    return full.length >= stored.length ? full.slice(0, n) : stored.slice(0, n);
  } catch { return stored.slice(0, n); }
}

// 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) {
      getOrSet(defines, e.name, () => new Set()).add(p);
      definition.set(`${p}|${e.name}`, { file: p, name: e.name, kind: e.kind });
    }
  }
  for (const [p, f] of Object.entries(files)) {
    const reExp = new Set(f.reExports || []); // #2: pass-through re-exports aren't real references
    for (const tp of f.imports)
      for (const name of f.importedSymbols[tp] || [])
        if (name !== "*" && name !== "default" && !reExp.has(name)) getOrSet(references, 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 *= FOCUS_BOOST;
        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);
  }
  const ranked = [...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)));

  // Aider parity (#8): keep exported symbols that NOTHING imports (Aider gives
  // them a 0.1 self-edge; pagerank() skips self-loops, so we append them here
  // with a tiny baseline rank below the lowest real rank). Lets public-API
  // entry points + default-export components surface in the digest tail.
  const present = new Set(ranked.map((d) => `${d.file}|${d.name}`));
  const lowest = ranked.length ? ranked[ranked.length - 1].rank : 0;
  const baseline = +(lowest - 1e-6 > 0 ? lowest - 1e-6 : 1e-6).toFixed(6);
  const tail = [];
  for (const def of definition.values()) {
    const k = `${def.file}|${def.name}`;
    if (present.has(k)) continue;
    if (focus && focus.has(def.file)) continue;
    tail.push({ ...def, rank: baseline });
  }
  tail.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
  return [...ranked, ...tail];
}

// 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() {
  // --include-dts is an opt-in restore of the old (.d.ts-included) behavior. It
  // reads/writes its OWN cache (MAP_DTS) so the default map.json — which the
  // post-commit hook writes and every normal query reads — is never touched or
  // read in this mode. Kept simple: trust the dts-cache only when clean + current;
  // any dirty/miss just rebuilds it fresh (this is a rarely-used diagnostic path).
  if (INCLUDE_DTS) {
    const sha = currentSha();
    const clean = sha ? (dirtyFiles().length === 0 && dirtyConfigFiles().length === 0) : false;
    if (existsSync(MAP_DTS)) {
      try {
        const c = JSON.parse(readFileSync(MAP_DTS, "utf8"));
        if (sha && clean && c.generatedSha === sha && c.schema === SCHEMA_VERSION && c.dirty === 0) return c;
      } catch {}
    }
    return build({ target: MAP_DTS });
  }
  const sha = currentSha();
  // One porcelain parse drives the whole freshness decision: dirty SOURCE files
  // (dl) AND dirty tsconfig/jsconfig (cfgDirty). A config edit changes alias
  // resolution without touching any source file, so it must bust the cache too.
  const porc = sha ? parsePorcelain() : [];
  const dl = porc.filter((e) => SOURCE_EXT_RE.test(e.path) || (e.oldPath && SOURCE_EXT_RE.test(e.oldPath)));
  const cfgDirty = porc.filter((e) => CONFIG_DIRTY_RE.test(e.path) || (e.oldPath && CONFIG_DIRTY_RE.test(e.oldPath)));
  // Read the namespaced path; fall back to the legacy '.claude/agentmap.json'
  // when the new path is missing (migration from a pre-namespacing install — the
  // legacy file is still trustworthy, the next build() rewrites to the new path).
  const mapPath = existsSync(MAP) ? MAP : (existsSync(MAP_LEGACY) ? MAP_LEGACY : MAP);
  if (existsSync(mapPath)) {
    try {
      const cached = JSON.parse(readFileSync(mapPath, "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 && dl.length === 0 && cfgDirty.length === 0) return cached;
      // NON-git repo (sha === ""): no HEAD to compare. Trust the cache when a
      // lightweight source fingerprint (path:mtime:size hash) is unchanged so
      // we don't full-reparse on every call. Best-effort — any mismatch/error
      // falls through to build(). Does NOT touch the git-repo path above.
      if (!sha && cached.schema === SCHEMA_VERSION && cached.fingerprint) {
        const fp = sourceFingerprint();
        if (fp && cached.fingerprint === fp) return cached;
      }
    } catch {}
  }
  // Dirty git tree (Tier 1): the clean fast-path above didn't return, so either
  // HEAD/schema drifted or the tree is dirty. Serve a cached dirty build keyed by
  // the dirty file set so back-to-back queries on an UNCHANGED dirty tree reuse
  // ONE rebuild instead of re-parsing the whole repo every call. Sits outside the
  // map.json block so it runs even before the first clean build exists.
  if (sha && (dl.length || cfgDirty.length)) {           // dirty source OR dirty config
    const dfp = dirtyFingerprint(sha, dl, cfgDirty);
    if (existsSync(MAP_DIRTY)) {
      try {
        const dc = JSON.parse(readFileSync(MAP_DIRTY, "utf8"));
        if (dc.schema === SCHEMA_VERSION && dc.dirtyFingerprint === dfp) return dc;
      } catch {}
    }
    return buildDirty(sha, dl, dfp);
  }
  return build();
}

// Produce the dirty-tree map and cache it to MAP_DIRTY, keyed by `dfp`. Tries the
// Tier 2 incremental path (reparse only changed files) first; on ANY miss or
// error it falls through to a full build() — incremental is a pure optimization
// and must never be the reason a query fails or returns a wrong map.
function buildDirty(sha, dirtyList, dfp) {
  // Tier 2 incremental is EXPERIMENTAL and OPT-IN (AGENTMAP_INCREMENTAL=1). For the
  // common modify cases it is byte-identical to a full rebuild AND much faster, but
  // adversarial verification found a tail of resolution edge cases where an
  // isolated-stub reparse diverges from a whole-repo build (re-export chains, .d.ts
  // edges, package.json "exports", …; see docs/batch3-dirty-tree-perf.md). Until
  // that tail is exhausted it stays OFF by default so the proven, byte-identical
  // Tier 1 dirty-map cache is what ships. When on, any miss/error falls back to a
  // full dirty build.
  if (/^(1|true)$/.test(process.env.AGENTMAP_INCREMENTAL || "")) {
    try {
      const inc = buildIncremental(sha, dirtyList, dfp);
      if (inc) return inc;
    } catch (e) {
      process.stderr.write(`# agentmap: incremental rebuild fell back to full build (${e?.message ?? e})\n`);
    }
  }
  return build({ target: MAP_DIRTY, extra: { dirtyFingerprint: dfp } });
}

// Tier 2 (true incremental) — reparse only the git-changed files against the
// cached clean-HEAD facts snapshot, merge, then re-run the (global but cheap)
// assembly. Returns the map object on success, or null to signal "fall back to a
// full dirty build" (no / mismatched facts snapshot). Correctness rests on: a
// file's own facts depend only on its own source (so unchanged cached facts stay
// valid); changed files' edges resolve against empty stubs of the unchanged files
// (same keys a full build produces); and every derived step (dependents, both
// PageRanks, features, hubs) is recomputed fully from the merged facts.
function buildIncremental(sha, dirtyList, dfp) {
  if (!sha || !existsSync(FACTS)) return null;
  let snap; try { snap = JSON.parse(readFileSync(FACTS, "utf8")); } catch { return null; }
  if (!snap || snap.schema !== SCHEMA_VERSION || snap.generatedSha !== sha || !snap.facts) return null;
  // Monorepo signals make the isolated-stub reparse diverge from ts-morph's
  // whole-repo resolution, so decline when present (the common single-package repo
  // is unaffected):
  //   • a NESTED tsconfig/jsconfig can redefine a ROOT alias to a different dir —
  //     the full build resolves via ts-morph's root-tsconfig-native resolution, the
  //     incremental resolver via the hand-rolled resolveAlias (nearest config);
  //   • a NESTED package.json makes a directory import (`import './mod'`) resolve
  //     via its "main" in a full build, but the incremental index-ladder ignores it.
  // Use the SAME listing discoverPackageAliasConfigs uses (--cached --others) so an
  // UNTRACKED config can't slip the guard. Cross-platform (no shell globbing).
  const listed = gitListFiles();
  if (listed.some((f) => /\/(tsconfig|jsconfig)(\.[\w.-]+)?\.json$/.test(f))) return null;
  if (listed.some((f) => /\/package\.json$/.test(f) && !f.split("/").includes("node_modules"))) return null;
  const cached = snap.facts;
  // Incremental is byte-identical to a full rebuild ONLY when the file SET is
  // unchanged — every dirty entry must be a MODIFICATION of a file already in the
  // snapshot. Adds/deletes/renames are declined (return null → full dirty build,
  // still cached by Tier 1), because they:
  //   • change the `files` key ordering (a new file lands at a different position
  //     than ts-morph's full-build order → shifts rank tie-breaks), and
  //   • flip edges in UNCHANGED importers we don't re-parse (a full build drops an
  //     importer's edge to a deleted file, or forms one to a newly-added file).
  // A modification never changes the file set, and an importer's edge NAMES come
  // from its own (unchanged) import statement, so a pure-modify merge is exact.
  for (const { code, path, oldPath } of dirtyList) {
    if (oldPath) return null;                              // rename / copy
    if (!Object.hasOwn(cached, path)) return null;         // added / new-untracked file
    if ((code || "").includes("D")) return null;           // deleted (staged or worktree)
  }
  const changed = dirtyList.map((d) => d.path);            // all modifications of existing files
  const changedSet = new Set(changed);
  // Re-export hazard, REVERSE: an UNCHANGED barrel that `export … from` a changed
  // file derives its OWN exports from that file (getExportedDeclarations follows
  // the re-export). We don't re-parse the barrel, so its cached exports would go
  // stale. cached[].reExportsFrom is reliable (recorded at the clean build, where
  // targets were real). Decline → full dirty build (Tier-1 cached).
  for (const k in cached) {
    const rf = cached[k].reExportsFrom;
    if (rf) for (const t of rf) if (changedSet.has(t)) return null;
  }
  // Re-export hazard, FORWARD: a changed file that itself `export … from` another
  // module has its `exports` list transitively resolved through that target — which
  // is an EMPTY stub in incremental mode, so its exports would be incomplete. We
  // can't rely on ts-morph resolving the stub, so detect it syntactically on the
  // changed file's own text (resolution-independent). Decline → full build.
  // \s* (not \s+) after `export` so whitespace-free minified forms like
  // `export*from"./a"` / `export{x}from"./a"` don't dodge the guard.
  const STAR_REEXPORT = /\bexport\s*(?:type\s+)?\*/;                       // export * / export * as / export type *
  const NAMED_REEXPORT = /\bexport\s*(?:type\s+)?\{[\s\S]*?\}\s*from\s*['"]/; // export { … } from '…' (multi-line)
  // CommonJS export forms: getExportedDeclarations() returns [] for `module.exports`
  // when the file is re-parsed in the isolated incremental project (it needs the
  // whole-repo module context), so the changed file's exports would collapse.
  const CJS_EXPORTS = /\bmodule\.exports\b|\bexports\.[A-Za-z_$]|\bexport\s*=/;
  for (const p of changed) {
    let txt; try { txt = readFileSync(p, "utf8"); } catch { return null; }
    if (STAR_REEXPORT.test(txt) || NAMED_REEXPORT.test(txt) || CJS_EXPORTS.test(txt)) return null;
  }
  const fresh = extractFacts({ changed, cachedKeys: Object.keys(cached) }); // reparse changed only
  const merged = structuredClone(cached);                  // disposable copy (assemble mutates it)
  for (const p of changed) {
    if (!fresh[p]) return null;   // file dropped from the map (parse-skip / vue <script> removed) ⇒ set change ⇒ full build
    // Backstop for the forward re-export gate: if the parsed file DID record a
    // module re-export (ts-morph resolved the specifier through a stub), decline —
    // its transitive exports were resolved against empty stubs.
    if (fresh[p].reExportsFrom && fresh[p].reExportsFrom.length) return null;
    // Re-export hazard, LAUNDERED (`export default Imported` / `export { Imported as default }`
    // with no `from` clause): the export's declaration lives in another file, which is an EMPTY
    // stub here, so getExportedDeclarations() can't name it → kind "?" and defaultExportName
    // stays "default". A full build resolves the real name. Kind "?" is the tell — decline.
    if (fresh[p].exports.some((e) => e.kind === "?")) return null;
    merged[p] = fresh[p];
  }
  return assemble(merged, { target: MAP_DIRTY, extra: { dirtyFingerprint: dfp } });
}

// Resolve a query to a file key, in PREFERENCE order so a loose substring path
// match never shadows a symbol the user actually wanted:
//   (a) exact path key
//   (b) unique basename match, CASE-INSENSITIVE
//   (c) unique case-insensitive SUBSTRING match (weakest — only when a/b miss)
//   (d) multiple substring matches → {key:null, candidates} for disambiguation
function resolveFile(keys, filesObj, q) {
  // Object.hasOwn (not `filesObj[q]`) so a query equal to an Object.prototype
  // property name (constructor / toString / __proto__ / hasOwnProperty / …) can't
  // hit an inherited property and fabricate a false file match (JSON/MCP) or crash
  // fileBlock() on the undefined value (prose).
  if (Object.hasOwn(filesObj, q)) return { key: q };                              // (a)
  const ql = q.toLowerCase();
  const base = keys.filter((k) => k.split("/").pop().toLowerCase() === ql);        // (b) case-insensitive basename
  if (base.length === 1) return { key: base[0] };
  const subs = keys.filter((k) => k.toLowerCase().includes(ql));                   // (c)/(d) substring
  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})${originNote(e)}`).join(", ") || "—"}`);
  console.log(`imports (${f.imports.length}): ${f.imports.join(", ") || "—"}`);
  console.log(`dependents (${f.dependents.length}): ${f.dependents.join(", ") || "—"}`);
  // Compile-time-only relationships, listed apart from the runtime ones: renaming
  // or deleting an export breaks these files, but nothing here fails at runtime.
  if (f.typeOnlyImports?.length) console.log(`type-only imports (${f.typeOnlyImports.length}): ${f.typeOnlyImports.join(", ")}`);
  if (f.typeOnlyDependents?.length) console.log(`type-only dependents (${f.typeOnlyDependents.length}): ${f.typeOnlyDependents.join(", ")}`);
  if (f.rsc) console.log(`boundary: ${f.rsc === "client" ? "'use client' (client component)" : "'use server' (server module/actions)"}`);
}

// --- Graph serializers for `--export` (pure, read the cached map only — no
// ts-morph Project, so the fast path is untouched). Emit the FILE import graph
// (nodes=files, edges=imports) as Graphviz DOT or Mermaid. Nodes bucket into 3
// PageRank tiers for light styling; Mermaid uses sanitized n0,n1,… ids (its ids
// can't hold slashes/dots) with the real path in the label, DOT quotes the path.
function _tier(pr, max) { if (max <= 0) return "leaf"; const r = pr / max; return r >= 0.5 ? "hub" : r >= 0.15 ? "mid" : "leaf"; }
function toDot(nodes, edges, meta) {
  const max = Math.max(0, ...nodes.map((n) => n.pagerank));
  const L = [
    `// agentmap import graph — ${meta.fileCount} files, sha ${meta.sha}${meta.focus ? `, focus ${meta.focus}` : ""}${meta.capped ? `, top ${meta.shown} by pagerank` : ""}`,
    "digraph agentmap {",
    "  rankdir=LR;",
    '  node [shape=box, style="rounded,filled", fillcolor="#f5f5f5", fontname="sans-serif"];',
  ];
  for (const n of nodes) {
    const t = _tier(n.pagerank, max);
    const st = t === "hub" ? ', fillcolor="#d9d9d9", penwidth=2' : t === "mid" ? ', fillcolor="#ececec"' : "";
    L.push(`  ${JSON.stringify(n.path)} [label=${JSON.stringify(n.path)}${st}];`);
  }
  for (const e of edges) L.push(`  ${JSON.stringify(e.from)} -> ${JSON.stringify(e.to)};`);
  L.push("}");
  return L.join("\n");
}
function toMermaid(nodes, edges, meta) {
  const max = Math.max(0, ...nodes.map((n) => n.pagerank));
  const id = new Map();
  nodes.forEach((n, i) => id.set(n.path, `n${i}`));
  const esc = (s) => s.replace(/"/g, "&quot;");
  const L = [
    `%% agentmap import graph — ${meta.fileCount} files, sha ${meta.sha}${meta.focus ? `, focus ${meta.focus}` : ""}${meta.capped ? `, top ${meta.shown} by pagerank` : ""}`,
    "flowchart TD",
    "  classDef hub fill:#d9d9d9,stroke:#333,stroke-width:2px;",
    "  classDef mid fill:#ececec;",
    "  classDef leaf fill:#f8f8f8;",
  ];
  for (const n of nodes) L.push(`  ${id.get(n.path)}["${esc(n.path)}"]:::${_tier(n.pagerank, max)}`);
  for (const e of edges) L.push(`  ${id.get(e.from)} --> ${id.get(e.to)}`);
  return L.join("\n");
}

// Strip // line comments and /* */ block comments from a JSONC string WITHOUT
// touching comment-like sequences inside double-quoted strings (so a value like
// "https://x" or "a /* b */ c" is preserved verbatim). Single-pass state machine:
// tracks whether we're inside a string (and an escape inside it) vs a line/block
// comment. Trailing commas are NOT handled — only comments, which is what real-
// world settings.json files carry.
function stripJsonComments(src) {
  let out = "";
  let inStr = false, esc = false, inLine = false, inBlock = false;
  for (let i = 0; i < src.length; i++) {
    const c = src[i], n = src[i + 1];
    if (inLine) { if (c === "\n") { inLine = false; out += c; } continue; }
    if (inBlock) { if (c === "*" && n === "/") { inBlock = false; i++; } continue; }
    if (inStr) {
      out += c;
      if (esc) esc = false;
      else if (c === "\\") esc = true;
      else if (c === '"') inStr = false;
      continue;
    }
    if (c === '"') { inStr = true; out += c; continue; }
    if (c === "/" && n === "/") { inLine = true; i++; continue; }
    if (c === "/" && n === "*") { inBlock = true; i++; continue; }
    out += c;
  }
  return out;
}

// Parse a settings.json that may be JSONC: try strict JSON first, then retry
// after stripping comments, and only then surface the caller's clear error.
function parseSettings(text, settingsPath) {
  try { return JSON.parse(text) || {}; }
  catch {
    try { return JSON.parse(stripJsonComments(text)) || {}; }
    catch { throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run`); }
  }
}

// ---------------------------------------------------------------------------
// Shared hook-wiring identifiers — the SINGLE source of truth consumed by both
// the writer (installHooks) and the checker (collectHookStatus). Previously
// each redeclared its own copies (nudgeDestRel/IGNORE_LINE vs NUDGE_REL/
// MAP_IGNORE_LINE) kept in sync only by comments; now there's one definition.
// ---------------------------------------------------------------------------
// Marker string baked into hooks/post-commit — used by --hook-status to detect our
// hook even when chained with other tools in the same file.
const POST_COMMIT_MARKER = "agentmap — git post-commit hook";
const NUDGE_REL = ".claude/hooks/agentmap-nudge.mjs";
const MAP_IGNORE_LINE = ".claude/agentmap/";
const NUDGE_SETTINGS_PATH = ".claude/settings.json";
const NUDGE_CMD = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/agentmap-nudge.mjs"`;
const NUDGE_MATCHERS = ["Grep", "Bash"];

// True when a PreToolUse entry list already wires our nudge to `matcher`.
// Shared predicate: installHooks uses it to decide whether to add an entry,
// collectHookStatus uses it to report wired/missing per matcher.
function nudgeMatcherWired(entries, matcher) {
  return entries.some(
    (e) => e?.matcher === matcher && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
  );
}

// ---------------------------------------------------------------------------
// --install-hooks: copy the package post-commit hook into .git/hooks, copy the
// PreToolUse nudge into .claude/hooks/agentmap-nudge.mjs, ensure .claude/agentmap/
// is gitignored, and auto-wire the Claude Code PreToolUse(Grep|Bash) nudge into
// the project's .claude/settings.json so map enforcement is ON by default (no
// manual copy-paste). Merge-safe + idempotent. With { dryRun:true } it prints the
// files it WOULD touch and writes nothing. Throws on any failure so the caller
// can stderr+exit 1.
// ---------------------------------------------------------------------------
// Does core.hooksPath send git somewhere other than `hooksDir`? Returns the
// configured path when it redirects, else null. Compared through realpath where
// possible so `.git/hooks` and an absolute spelling of the same dir agree.
// A dead hook that reports "installed" is the failure this whole area exists to
// prevent, so both the writer and --doctor consult this.
function hooksPathRedirect(hooksDir) {
  const configured = sh("git config --get core.hooksPath");
  if (!configured) return null;
  const abs = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
  return abs(configured) === abs(hooksDir) ? null : configured;
}

function warnIfHooksPathRedirects(hooksDir) {
  const redirect = hooksPathRedirect(hooksDir);
  if (!redirect) return;
  console.error(`# warning: core.hooksPath is set to ${redirect}, so git will NOT run the hook just written to ${hooksDir}.`);
  console.error(`# warning: the map will not auto-refresh. Either copy ${hooksDir}/post-commit into ${redirect}/, or unset core.hooksPath.`);
}

function installHooks({ dryRun = false } = {}) {
  const src = new URL("./hooks/post-commit", import.meta.url);
  // The package hooks/ dir must ship alongside agentmap.mjs.
  if (!existsSync(src)) throw new Error(`packaged hook not found at ${src.pathname} (is the hooks/ dir present?)`);
  // The PreToolUse nudge that gets COPIED into the project (see below). It must
  // ship alongside agentmap.mjs too.
  const nudgeSrc = new URL("./hooks/agentmap-nudge.mjs", import.meta.url);
  if (!existsSync(nudgeSrc)) throw new Error(`packaged nudge not found at ${nudgeSrc.pathname} (is the hooks/ dir present?)`);

  // Locate the hooks dir of the CURRENT repo (cwd), then copy in the hook.
  //
  // `--git-common-dir`, NOT `--git-dir`. Inside a linked worktree the two differ:
  // --git-dir is <main>/.git/worktrees/<name>, but git executes hooks from the
  // COMMON dir. Installing against --git-dir wrote a hook git never runs, while
  // --install-hooks printed "Done — the map auto-refreshes on commit" and --doctor
  // reported "installed". The map then silently froze at install time — in the
  // exact shape a parallel-agent workflow uses most.
  //
  // Deliberately NOT `--git-path hooks`, which additionally resolves core.hooksPath:
  // under husky that points at a tracked .husky/ directory, and dropping a generated
  // file into the user's committed hook directory is a different decision than
  // fixing worktrees. That case is warned about below instead.
  const commonDir = sh("git rev-parse --git-common-dir");
  if (!commonDir) throw new Error("not a git repository (cwd has no .git) — run inside the repo you want to wire up");
  const hooksDir = `${commonDir}/hooks`;
  const dest = `${hooksDir}/post-commit`;

  // The nudge is copied into the PROJECT (not referenced inside node_modules) so
  // the documented one-liner `npx @raymondchins/agentmap --install-hooks` works
  // even though npx never populates ./node_modules — the old path
  // node_modules/@raymondchins/agentmap/hooks/agentmap-nudge.mjs simply does not
  // exist after an npx install, so the hook silently never fired. The nudge is
  // self-contained (Node stdlib only, no relative package imports), so copying it
  // standalone is safe. CLAUDE_PROJECT_DIR is set by Claude Code at hook time, so
  // the wired command resolves the copied file regardless of cwd.
  const nudgeDestRel = NUDGE_REL;

  // .gitignore line: ignore the namespaced map DIR (not the legacy single file).
  const IGNORE_LINE = MAP_IGNORE_LINE;
  const settingsPath = NUDGE_SETTINGS_PATH;

  // --- Determine what WOULD change (so --dry-run and the pre-write notice both
  // describe the real plan). ---
  let ignoredAlready = false;
  if (existsSync(".gitignore")) {
    ignoredAlready = readFileSync(".gitignore", "utf8").split(/\r?\n/).some((l) => l.trim() === IGNORE_LINE);
  }
  let settings = {};
  if (existsSync(settingsPath)) {
    settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
  }
  settings.hooks ??= {};
  settings.hooks.PreToolUse ??= [];
  const hasGrep = nudgeMatcherWired(settings.hooks.PreToolUse, "Grep");
  const hasBash = nudgeMatcherWired(settings.hooks.PreToolUse, "Bash");
  const alreadyWired = hasGrep && hasBash;

  // The set of files this run touches — used by both the dry-run report and the
  // one-line pre-write notice in the normal path.
  const targets = [
    dest,                                              // .git/hooks/post-commit
    nudgeDestRel,                                      // .claude/hooks/agentmap-nudge.mjs
    ...(ignoredAlready ? [] : [".gitignore"]),         // only if the ignore line is missing
    ...(alreadyWired ? [] : [settingsPath]),           // only if not already wired
  ];

  if (dryRun) {
    console.log("--dry-run: would create/overwrite the following files (no changes written):");
    for (const t of targets) console.log(`  ${t}`);
    return;
  }

  // Normal path: announce the plan, then write.
  console.log(`agentmap --install-hooks: writing ${targets.length} file(s): ${targets.join(", ")}`);

  // 1) post-commit hook → .git/hooks. Don't silently clobber a user's OWN
  // (non-agentmap) post-commit hook — back it up first so their work is
  // recoverable (agentmap's hook replaces it and does not chain an existing one).
  mkdirSync(hooksDir, { recursive: true });
  if (existsSync(dest)) {
    const cur = readFileSync(dest, "utf8");
    if (!cur.includes(POST_COMMIT_MARKER)) {
      writeFileSync(`${dest}.pre-agentmap`, cur, { mode: 0o755 });
      console.error(`# warning: backed up your existing post-commit hook → ${dest}.pre-agentmap (agentmap's hook replaces it and does not chain it; re-add your logic if needed)`);
    }
  }
  writeFileSync(dest, readFileSync(src, "utf8"), { mode: 0o755 });
  chmodSync(dest, 0o755); // explicit: writeFileSync mode is masked by umask

  // core.hooksPath redirects git AWAY from the dir just written (husky sets it to
  // .husky). The hook is on disk and inert — the same silent-freshness-death the
  // worktree bug caused, so say it out loud rather than printing "Done".
  warnIfHooksPathRedirects(hooksDir);

  // 2) nudge → .claude/hooks/agentmap-nudge.mjs (idempotent overwrite-on-rerun)
  mkdirSync(".claude/hooks", { recursive: true });
  writeFileSync(nudgeDestRel, readFileSync(nudgeSrc, "utf8"));

  // 3) .gitignore: ignore the namespaced map dir (append/create).
  if (!ignoredAlready) {
    if (existsSync(".gitignore")) {
      const cur = readFileSync(".gitignore", "utf8");
      writeFileSync(".gitignore", cur + (cur.endsWith("\n") || cur === "" ? "" : "\n") + IGNORE_LINE + "\n");
    } else {
      writeFileSync(".gitignore", IGNORE_LINE + "\n");
    }
  }

  // 4) Auto-wire the PreToolUse(Grep|Bash) nudge into project settings. Merge-
  // safe + idempotent: preserves existing settings/hooks, never duplicates ours.
  if (!hasGrep) settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
  if (!hasBash) settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [{ type: "command", command: NUDGE_CMD }] });
  if (!alreadyWired) {
    mkdirSync(".claude", { recursive: true });
    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
  }

  // Success report.
  console.log(`installed post-commit hook → ${dest}`);
  console.log(`installed PreToolUse nudge → ${nudgeDestRel}`);
  console.log(ignoredAlready ? `.gitignore already has ${IGNORE_LINE}` : `added ${IGNORE_LINE} to .gitignore`);
  console.log(alreadyWired
    ? `${settingsPath} already wires the PreToolUse(Grep|Bash) → agentmap nudge — left as-is`
    : `wired PreToolUse(Grep|Bash) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
  console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
}

// Collect hook wiring as structured data. `degradedOutsideGit` switches the
// outside-git behavior: --hook-status (legacy) bails out and prints one line,
// --doctor wants the remaining repo-local checks (nudge, PreToolUse, .gitignore)
// to keep running with the git-only ones marked `skipped`.
function collectHookStatus({ degradedOutsideGit = false } = {}) {
  const gitDir = sh("git rev-parse --git-dir");
  const insideGit = Boolean(gitDir);
  const checks = [];

  checks.push({
    name: "git-repo",
    label: "Git repo",
    status: insideGit ? "ok" : "skipped",
    detail: insideGit ? "detected" : "not inside a git repository",
  });

  if (!insideGit && !degradedOutsideGit) return { insideGit: false, checks };

  if (insideGit) {
    // Must match installHooks' `--git-common-dir` exactly. Deriving it from
    // --git-dir instead is how --doctor came to greenlight a hook git never runs:
    // in a linked worktree it checked <main>/.git/worktrees/<name>/hooks, found the
    // file installHooks had just written there, and reported "installed" while the
    // hook git actually executes was absent.
    const hooksDir = `${sh("git rev-parse --git-common-dir")}/hooks`;
    const postCommitPath = `${hooksDir}/post-commit`;
    let detail = "not installed";
    let status = "missing";
    if (existsSync(postCommitPath)) {
      const body = readFileSync(postCommitPath, "utf8");
      const redirect = hooksPathRedirect(hooksDir);
      if (body.includes(POST_COMMIT_MARKER) && redirect) {
        // On disk, correct, and inert — git is looking somewhere else entirely.
        // Reporting "installed" here is the same lie the worktree bug told.
        detail = `installed but INERT — core.hooksPath=${redirect} redirects git away from ${hooksDir}`;
        status = "degraded";
      } else if (body.includes(POST_COMMIT_MARKER)) {
        detail = "installed";
        status = "installed";
      } else {
        detail = "not installed (hook exists but agentmap not found)";
      }
    }
    checks.push({
      name: "post-commit",
      label: "post-commit",
      status,
      detail,
      path: postCommitPath,
      // Re-running --install-hooks cannot fix a core.hooksPath redirect — it would
      // rewrite the same inert file. Name the fix that actually works.
      suggestion: status === "installed"
        ? null
        : status === "degraded"
          ? "git config --unset core.hooksPath  (or copy the hook into the configured hooksPath)"
          : "agentmap --install-hooks",
    });
  } else {
    checks.push({
      name: "post-commit",
      label: "post-commit",
      status: "skipped",
      detail: "not inside a git repository",
    });
  }

  const nudgeInstalled = existsSync(NUDGE_REL);
  checks.push({
    name: "nudge",
    label: `nudge (${NUDGE_REL})`,
    status: nudgeInstalled ? "installed" : "missing",
    detail: nudgeInstalled ? "installed" : "not installed",
    path: NUDGE_REL,
    suggestion: nudgeInstalled ? null : "agentmap --install-hooks",
  });

  const settingsPath = NUDGE_SETTINGS_PATH;
  let settings = null;
  let settingsInvalid = false;
  if (existsSync(settingsPath)) {
    try {
      settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
    } catch {
      settingsInvalid = true;
    }
  }
  const entries = settings?.hooks?.PreToolUse || [];
  for (const matcher of NUDGE_MATCHERS) {
    let status, detail;
    if (settingsInvalid) {
      status = "invalid";
      detail = "not wired (invalid settings.json)";
    } else if (!existsSync(settingsPath)) {
      status = "missing";
      detail = "not wired";
    } else if (nudgeMatcherWired(entries, matcher)) {
      status = "wired";
      detail = "wired";
    } else {
      status = "missing";
      detail = "not wired";
    }
    checks.push({
      name: `pretooluse-${matcher.toLowerCase()}`,
      label: `PreToolUse(${matcher})`,
      status,
      detail,
      path: settingsPath,
      suggestion: status === "wired" ? null : "agentmap --install-hooks",
    });
  }

  if (insideGit || existsSync(".gitignore")) {
    const gitignoreOk = existsSync(".gitignore") &&
      readFileSync(".gitignore", "utf8").split(/\r?\n/).some((l) => l.trim() === MAP_IGNORE_LINE);
    checks.push({
      name: "gitignore",
      label: `.gitignore (${MAP_IGNORE_LINE})`,
      status: gitignoreOk ? "ok" : "missing",
      detail: gitignoreOk ? "ok" : "missing entry",
      path: ".gitignore",
      suggestion: gitignoreOk ? null : "agentmap --install-hooks",
    });
  } else {
    checks.push({
      name: "gitignore",
      label: `.gitignore (${MAP_IGNORE_LINE})`,
      status: "skipped",
      detail: "no .gitignore outside a git repository",
    });
  }

  return { insideGit, checks };
}

function hookStatus() {
  const { insideGit, checks } = collectHookStatus({ degradedOutsideGit: false });
  if (!insideGit) {
    console.log("not a git repository — run inside the repo you want to check");
    return;
  }
  for (const c of checks) {
    if (c.name === "git-repo") continue;
    console.log(`${c.label}: ${c.detail}`);
  }
}

// ---------------------------------------------------------------------------
// --doctor: read-only harness health report. doctor reports; it never repairs.
// Reuses collectHookStatus() (with degradedOutsideGit), the skill install-target
// metadata from skills/install.mjs, the 3 MCP targets from setupMcp(), and the
// module-local dirtyCount() — no new sources of truth, no writes anywhere.
// ---------------------------------------------------------------------------

// Same 3 targets setupMcp() writes — keep labels/paths aligned so doctor's
// "missing entry" actually maps to "agentmap --setup-mcp will add it here".
// Each target: the ONE definition consumed by both collectMcpStatus (checker:
// path/has) and setupMcp (writer: path/graft). Antigravity is written to BOTH
// its entries on purpose — older builds read only the IDE-specific
// ~/.gemini/antigravity path, newer unified builds read the shared
// ~/.gemini/config path, so writing both is version-proof.
const MCP_TARGETS = [
  {
    name: "opencode",
    label: "OpenCode",
    path: () => join(homedir(), ".config", "opencode", "opencode.json"),
    displayPath: "~/.config/opencode/opencode.json",
    has: (cfg) => Boolean(cfg?.mcp?.agentmap),
    objectPath: "mcp.agentmap",
    graft: (cfg, { command, args }) => { (cfg.mcp ??= {}).agentmap = { type: "stdio", command, args, enabled: true }; },
  },
  {
    name: "antigravity",
    label: "Antigravity IDE",
    path: () => join(homedir(), ".gemini", "antigravity", "mcp_config.json"),
    displayPath: "~/.gemini/antigravity/mcp_config.json",
    has: (cfg) => Boolean(cfg?.mcpServers?.agentmap),
    objectPath: "mcpServers.agentmap",
    graft: (cfg, { command, args }) => { (cfg.mcpServers ??= {}).agentmap = { command, args }; },
  },
  {
    name: "antigravity-shared",
    label: "Antigravity (shared)",
    path: () => join(homedir(), ".gemini", "config", "mcp_config.json"),
    displayPath: "~/.gemini/config/mcp_config.json",
    has: (cfg) => Boolean(cfg?.mcpServers?.agentmap),
    objectPath: "mcpServers.agentmap",
    graft: (cfg, { command, args }) => { (cfg.mcpServers ??= {}).agentmap = { command, args }; },
  },
];

async function collectSkillStatus({ expectedVersion, root }) {
  const { getSkillInstallTargets } = await import("./skills/install.mjs");
  const targets = getSkillInstallTargets({ platforms: "all", project: true, global: false, root });
  return targets.map((t) => {
    const installed = existsSync(t.dest);
    if (!installed) {
      return {
        name: t.name,
        label: `${t.label}${t.legacy ? " (legacy)" : ""}`,
        status: "missing",
        path: t.dest,
        expectedVersion,
        suggestion: "agentmap --install-skill",
      };
    }
    let actualVersion = null;
    if (existsSync(t.versionPath)) {
      try { actualVersion = readFileSync(t.versionPath, "utf8").trim(); } catch { actualVersion = null; }
    }
    if (!actualVersion) {
      return {
        name: t.name,
        label: `${t.label}${t.legacy ? " (legacy)" : ""}`,
        status: "installed",
        detail: "version unknown",
        path: t.dest,
        expectedVersion,
        suggestion: "agentmap --install-skill",
      };
    }
    if (actualVersion !== expectedVersion) {
      return {
        name: t.name,
        label: `${t.label}${t.legacy ? " (legacy)" : ""}`,
        status: "stale",
        detail: `installed ${actualVersion}, current ${expectedVersion}`,
        path: t.dest,
        actualVersion,
        expectedVersion,
        suggestion: "agentmap --install-skill",
      };
    }
    return {
      name: t.name,
      label: `${t.label}${t.legacy ? " (legacy)" : ""}`,
      status: "ok",
      path: t.dest,
      actualVersion,
      expectedVersion,
    };
  });
}

function collectMcpStatus() {
  return MCP_TARGETS.map((t) => {
    const path = t.path();
    if (!existsSync(path)) {
      return {
        name: t.name,
        label: t.label,
        status: "missing",
        detail: "config missing",
        path: t.displayPath,
        objectPath: t.objectPath,
        suggestion: "agentmap --setup-mcp",
      };
    }
    let cfg;
    try { cfg = parseSettings(readFileSync(path, "utf8"), path); }
    catch {
      return {
        name: t.name,
        label: t.label,
        status: "invalid",
        detail: "invalid JSON",
        path: t.displayPath,
        objectPath: t.objectPath,
        suggestion: `fix ${t.displayPath} then re-run agentmap --setup-mcp`,
      };
    }
    const wired = t.has(cfg);
    return {
      name: t.name,
      label: t.label,
      status: wired ? "wired" : "missing",
      detail: wired ? "wired" : "agentmap entry missing",
      path: t.displayPath,
      objectPath: t.objectPath,
      suggestion: wired ? null : "agentmap --setup-mcp",
    };
  });
}

function collectMapStatus() {
  const currentExists = existsSync(MAP);
  const legacyExists = existsSync(MAP_LEGACY);
  if (!currentExists && !legacyExists) {
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "missing",
      detail: "no map cache found",
      path: MAP,
      suggestion: "agentmap",
    }];
  }
  const selectedPath = currentExists ? MAP : MAP_LEGACY;
  let cache;
  try { cache = JSON.parse(readFileSync(selectedPath, "utf8")); }
  catch {
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "unknown",
      detail: "cache exists but could not be parsed",
      path: selectedPath,
      suggestion: "agentmap",
    }];
  }
  // Health BEFORE staleness. build() already persists fileCount/edgeCoverage/
  // degraded (:1386-1387) and warns on stderr at :1417-:1421, but that warning
  // scrolls past once at build time and --doctor never read the fields — so a
  // map of ZERO files reported "Map cache: ok" with exit 0 forever after. A map
  // that is fresh and empty is worse than a stale one: staleness suggests
  // rebuilding, "ok" suggests nothing is wrong. Checked first so the empty case
  // can't be masked by a matching generatedSha.
  //
  // Guarded on typeof, not truthiness: caches written before schema 5 lack these
  // fields, and `undefined` must read as "unknown", never as 0/degraded.
  // Checked ahead of BOTH the 0-file and degraded branches: a map that dropped files
  // is the most severe of the three, and it also EXPLAINS a 0-file map (everything
  // threw) that would otherwise be reported as "repo not git-tracked?". Guarded on
  // `=== true` so pre-schema-7 caches (field absent) read as "not truncated".
  if (cache.incomplete === true) {
    const list = Array.isArray(cache.skipped) ? cache.skipped : [];
    const n = typeof cache.skippedCount === "number" ? cache.skippedCount : list.length;
    const why = [...new Set(list.map((s) => s?.reason).filter(Boolean))].join(", ") || "unknown";
    const sample = list.slice(0, 5).map((s) => s?.file).filter(Boolean).join(", ");
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "incomplete",
      detail: `map is missing ${n} source file${n === 1 ? "" : "s"} (${why})${sample ? ` — e.g. ${sample}` : ""}; --relates/--find/--hubs will under-report`,
      path: selectedPath,
      suggestion: "agentmap",
    }];
  }
  if (typeof cache.fileCount === "number" && cache.fileCount === 0) {
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "invalid",
      detail: "map contains 0 source files (repo not git-tracked? non-standard dir layout? everything excluded?)",
      path: selectedPath,
      suggestion: "agentmap",
    }];
  }
  if (cache.degraded === true) {
    const cov = typeof cache.edgeCoverage === "number"
      ? ` — only ${(cache.edgeCoverage * 100).toFixed(1)}% of local imports resolved`
      : "";
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "degraded",
      detail: `map built but most imports did not resolve${cov}; --relates and --hubs will be unreliable`,
      path: selectedPath,
      suggestion: "agentmap",
    }];
  }

  const sha = currentSha();
  const dirty = dirtyCount();
  const reasons = [];
  if (sha && cache.generatedSha && cache.generatedSha !== sha) {
    reasons.push(`generatedSha ${cache.generatedSha} differs from HEAD ${sha}`);
  }
  if (typeof cache.schema === "number" && cache.schema !== SCHEMA_VERSION) {
    reasons.push(`schema ${cache.schema} differs from current ${SCHEMA_VERSION}`);
  }
  if (dirty > 0) {
    reasons.push(`working tree has ${dirty} TS/JS/Vue source change(s)`);
  }
  if (reasons.length) {
    return [{
      name: "map-cache",
      label: "Map cache",
      status: "stale",
      detail: reasons.join("; "),
      path: selectedPath,
      suggestion: "agentmap",
    }];
  }
  return [{
    name: "map-cache",
    label: "Map cache",
    status: "ok",
    detail: currentExists ? "current cache path present" : "legacy cache path present",
    path: selectedPath,
  }];
}

function readPackageVersion() {
  try {
    const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
    return { name: pkg.name || "agentmap", version: pkg.version || "0.0.0" };
  } catch {
    return { name: "agentmap", version: "0.0.0" };
  }
}

async function collectDoctorReport() {
  const pkg = readPackageVersion();
  const cwd = process.cwd();
  const { insideGit, checks: hooks } = collectHookStatus({ degradedOutsideGit: true });
  const skills = await collectSkillStatus({ expectedVersion: pkg.version, root: cwd });
  const mcp = collectMcpStatus();
  const map = collectMapStatus();

  const all = [...hooks, ...skills, ...mcp, ...map];
  const suggestions = [...new Set(all.map((c) => c.suggestion).filter(Boolean))];
  // "degraded" belongs here: a map that built but resolved almost no imports is
  // exactly the state --doctor exists to surface. Omitting it would reproduce the
  // bug this list is meant to catch — a real problem reported with exit 0.
  const needsAttention = all.some((c) =>
    // "incomplete" belongs here for the same reason "degraded" does, one severity
    // higher: files are missing outright, and the whole point of --doctor is to stop
    // a real problem being reported with exit 0.
    ["missing", "stale", "invalid", "degraded", "incomplete"].includes(c.status)
  );
  const overall = !insideGit ? "degraded" : (needsAttention ? "needs attention" : "ok");

  return {
    command: "doctor",
    cwd,
    package: pkg,
    overall,
    checks: { hooks, skills, mcp, map },
    suggestions,
  };
}

function formatDoctorReport(report) {
  const lines = [];
  lines.push("agentmap doctor");
  lines.push(`cwd: ${report.cwd}`);
  lines.push(`package: ${report.package.name} ${report.package.version}`);
  lines.push(`overall: ${report.overall}`);
  lines.push("");

  // Repo-relative display for skill/rule paths (which arrive absolute from
  // getSkillInstallTargets). Hooks/MCP/map paths are already short. Keep the
  // absolute path in the JSON output for tests/tooling.
  const displayPath = (p) => {
    if (!p) return "";
    const cwd = report.cwd;
    if (p === cwd) return ".";
    if (p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
    return p;
  };

  const section = (title, checks) => {
    lines.push(title);
    for (const c of checks) {
      const detail = c.detail ? ` — ${c.detail}` : "";
      const path = c.path ? ` (${displayPath(c.path)})` : "";
      lines.push(`  ${c.label}: ${c.status}${path}${detail}`);
    }
    lines.push("");
  };

  section("Hooks", report.checks.hooks);
  section("Skills / Rules", report.checks.skills);
  section("MCP", report.checks.mcp);
  section("Map cache", report.checks.map);

  lines.push("Suggested next steps");
  if (!report.suggestions.length) {
    lines.push("  No action needed.");
  } else {
    for (const s of report.suggestions) lines.push(`  - ${s}`);
  }
  return lines.join("\n");
}

// ---------------------------------------------------------------------------
// --setup-mcp: register the agentmap MCP server in the global configs of
// MCP-capable IDEs that aren't Claude Code (which uses --install-hooks instead).
// Merge-safe + idempotent; with { dryRun:true } it prints the plan and writes
// nothing. Throws on the first malformed config so the caller can stderr+exit 1.
// ---------------------------------------------------------------------------
function setupMcp({ dryRun = false } = {}) {
  const mcpPath = fileURLToPath(new URL("./mcp.mjs", import.meta.url));

  // npx materializes the package under a `_npx` cache dir that gets garbage-
  // collected, so a config pointing at that path would rot. When invoked via npx,
  // pin to the published spec instead; otherwise reference the resolved file.
  const isNpx = mcpPath.includes("_npx");
  const command = isNpx ? "npx" : process.execPath;
  const args = isNpx ? ["-y", "@raymondchins/agentmap", "--mcp"] : [mcpPath];

  if (dryRun) console.log("--dry-run: would configure MCP server (no changes written):");

  // Same MCP_TARGETS table collectMcpStatus() reads — one source of truth for
  // labels/paths; each entry's `graft` builds the writer's config shape.
  for (const { label, path: pathFn, graft } of MCP_TARGETS) {
    const path = pathFn();
    // Reuse parseSettings so JSONC (comments) is tolerated and a malformed file
    // throws a clear error WITHOUT clobbering the original (we never write on the
    // failure path, so no .bak dance is needed).
    let cfg = {};
    if (existsSync(path)) cfg = parseSettings(readFileSync(path, "utf8"), path);
    graft(cfg, { command, args });

    if (dryRun) {
      console.log(`  ${label}: would write to ${path}`);
    } else {
      mkdirSync(dirname(path), { recursive: true });
      writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n");
      console.log(`configured ${label} MCP server → ${path}`);
    }
  }
}

// ---------------------------------------------------------------------------
// CLI — arg parsing + command dispatch. Lives inside main() so that IMPORTING
// this module (for the exported pure functions below) has zero side effects:
// no build, no cache write, no console output, no process.exit. main() runs
// only when the file is executed directly (see the import.meta.url guard at the
// very bottom — the same dual check mcp.mjs uses).
// ---------------------------------------------------------------------------
const USAGE = `agentmap — the queryable, ranked repo map your coding agent is forced to use.

Usage: agentmap [command] [--json]

Query commands:
  --any <q>            route a query: file → symbol → feature → live git-grep
  --find <sym> [--kind <k>]
                       find symbols by (sub)name (exports + non-exported top-level)
                       --kind filters by declaration kind, matched loosely:
                       function / interface / type / class / variable
  --search <q>         rank symbols by BM25 lexical relevance (vague NL queries)
  --relates <path>     a file's exports/imports/dependents + related files
  --callers <sym> [--in <path>] [--depth N]
                       compiler-accurate call sites that invoke a symbol
                       (experimental; --depth N = transitive N-hop closure, max 5)
  --calls <sym> [--in <path>] [--depth N]
                       compiler-accurate in-project symbols a symbol invokes
                       (outgoing; experimental; --depth for transitive; dynamic not resolved)
  --map [--focus <p>] [--tokens <n>]
                       token-budgeted ranked digest (--focus personalizes)
  --symbols [n]        top-n Aider-style ranked symbols (default 30)
  --feature <name>     files composing a feature + external dependents
  --features           list all features (route segments) by size
  --routes             Next.js App Router route table: real URLs (route groups
                       stripped, [id] -> :id), HTTP methods per API route, the
                       layout chain, and re-export shim aliases
  --route <url|file>   what serves this URL (or which URL a file serves):
                       matched file, methods, layout chain, RSC boundary
  --affected <path>    test files that transitively import this file — what to
                       re-run after changing it (and what has NO cover at all)
  --hubs               top files by PageRank importance
  --print              dump the full cached map as JSON
  --export <mermaid|dot> [--focus <p>]
                       print the file import graph as Mermaid / Graphviz DOT
                       (nodes=files, edges=imports, top-N by pagerank; --focus scopes)
  (no flags)           build the map + print a one-line summary

Global modifier:
  --json               emit exactly one JSON object (no prose) for the command
  --include-dts        include .d.ts declaration files in the symbol/ranking pass
                       (default: excluded so generated types don't flood results)
  --no-locals          hide non-exported top-level declarations from --find/--any
                       (default: shown; they never affect --map/--hubs ranking)

Maintenance:
  --install-hooks [--dry-run]
                       install git post-commit + copy the PreToolUse nudge +
                       wire .claude/settings.json (--dry-run = preview, no writes)
  --install-skill [--platform claude|cursor|codex|opencode|gemini|antigravity|copilot|agents|all] [--project|--global] [--dry-run]
                       install skills + always-on docs/hooks per platform
  --build-edges        precompute the call-edge index so --callers answers from
                       cache (~35ms) instead of a live type-checker walk (~1.5s).
                       Costs ~4x a normal build, so it is explicit: the
                       post-commit hook runs it in the background. Safe to skip —
                       --callers falls back to the live walk without it.
  --hook-status          report whether agentmap git/nudge wiring is installed
  --doctor             read-only health report: hooks, skills/rules, MCP wiring, map cache
                         (exits 0, suggests fix commands, never writes files)
  --setup-mcp [--dry-run]
                       configure MCP server for OpenCode & Antigravity IDE
                       (--dry-run = preview, no writes)
  --mcp                start a stdio MCP server (for MCP-capable agents)
  --help, -h           show this help
  --version, -v        print the version

Exit codes: 0 ok · 1 query had zero results (incl. --map --focus with no match) · 2 usage error · 3 maintenance command failed.`;

async function main() {
  const args = process.argv.slice(2);
  const has = (f) => args.includes(f);
  // Return the value after flag `f`, but treat a missing value OR one that looks
  // like another flag (starts with "--") as undefined so the missing-arg guards
  // fire — e.g. `--any --foo` must NOT search for the literal "--foo".
  const arg = (f) => { const i = args.indexOf(f); if (i < 0) return undefined; const v = args[i + 1]; return v === undefined || v.startsWith("--") ? undefined : v; };

  // --json is a GLOBAL modifier: when present, the chosen command emits exactly
  // ONE JSON object to stdout (no prose). Branches build a result, then either
  // console.log(JSON.stringify(obj)) or fall through to the prose printer. Exit
  // codes are identical in both modes.
  const wantJson = has("--json");
  const out = (obj, prose) => { if (wantJson) console.log(JSON.stringify(obj)); else prose(); };
  // --kind: filter symbol results by declaration kind. Matched LOOSELY and
  // case-insensitively against the ts-morph kind name, so `--kind function`
  // finds FunctionDeclaration and `--kind type` finds TypeAliasDeclaration —
  // nobody should have to know ts-morph's enum spelling to narrow a search.
  const kindFilter = arg("--kind");
  const kindOk = (k) => !kindFilter || String(k || "").toLowerCase().includes(kindFilter.toLowerCase());

  // --include-dts is a GLOBAL modifier (like --json), valid with any query
  // command or none: it flips the module-scoped INCLUDE_DTS so extractFacts keeps
  // `.d.ts` files as full map nodes (the pre-0.11 behavior). Off by default so a
  // generated declaration file's symbols don't flood --find/--symbols/--hubs.
  if (has("--include-dts")) INCLUDE_DTS = true;
  // --no-locals: query-time filter that hides non-exported top-level declarations
  // (each file's `locals`) from --find/--any. `locals` are still BUILT (the cache
  // always carries them), so this only suppresses them at read time — never a
  // separate build, and it can never affect --map/--symbols/--hubs (they ignore locals).
  if (has("--no-locals")) INCLUDE_LOCALS = false;

  // Every recognized flag (the global modifiers + maintenance flags + each
  // command + sub-flags that take a value). Anything starting with "-" that is
  // NOT in this set is an unknown flag → usage error (exit 2), not a silent build.
  const KNOWN = new Set([
    "--json", "--include-dts", "--no-locals", "--print",
    "--help", "-h", "--version", "-v", "--install-hooks", "--hook-status", "--doctor", "--install-skill", "--platform", "--project", "--global",
    "--dry-run", "--setup-mcp", "--mcp", "--build-edges",
    "--any", "--find", "--search", "--relates", "--callers", "--calls", "--in", "--depth", "--map", "--export", "--focus", "--tokens",
    "--symbols", "--feature", "--features", "--hubs", "--routes", "--route", "--affected", "--kind",
  ]);

  // A token consumed as the VALUE of a value-taking flag is never itself a flag —
  // so a dash-leading query like `--any "-O/bin/sh"` is bound as the query, not
  // mistaken for an unknown flag. (arg() already rejects a "--"-leading value, so
  // `--any --foo` still falls through to the missing-arg guard instead.)
  const VALUE_FLAGS = new Set(["--any", "--find", "--search", "--relates", "--callers", "--calls", "--in", "--depth", "--export", "--feature", "--focus", "--tokens", "--symbols", "--platform", "--route", "--affected", "--kind"]);
  const valueIdx = new Set();
  for (let i = 0; i < args.length - 1; i++) if (VALUE_FLAGS.has(args[i])) valueIdx.add(i + 1);

  // --help / --version short-circuit BEFORE any build or dispatch.
  if (has("--help") || has("-h")) {
    console.log(USAGE);
    process.exit(0);
  }
  if (has("--version") || has("-v")) {
    console.log(readPackageVersion().version);
    process.exit(0);
  }

  // Unknown-flag guard: any "-"-prefixed token not in KNOWN → usage error (exit
  // 2). Runs BEFORE any command dispatch (incl. the maintenance flags below, each
  // of which process.exit()s in its own branch) so a typo never silently triggers
  // the wrong command or a bare build. A token bound as a value-flag's value
  // (valueIdx) is never treated as a flag.
  if (args.some((a, i) => a.startsWith("-") && !KNOWN.has(a) && !valueIdx.has(i))) {
    const bad = args.find((a, i) => a.startsWith("-") && !KNOWN.has(a) && !valueIdx.has(i));
    console.error(`unknown flag: ${bad}\ntry \`agentmap --help\` for the list of commands.`);
    process.exit(2);
  }

  // Declarative command table. The dispatch below is order-insensitive set
  // membership, so without this pass two commands at once (`--map --doctor`) or an
  // orphan sub-flag (`--focus` with no `--map`) is silently accepted — whichever
  // branch matches first wins, no warning. Each key is a command; its value lists
  // the sub-flags that only make sense with it. `--json` is a global modifier (not
  // a command) and is deliberately absent — valid with any command or with none.
  const COMMANDS = {
    "--mcp": [], "--install-hooks": ["--dry-run"],
    "--install-skill": ["--platform", "--project", "--global", "--dry-run"],
    "--hook-status": [], "--doctor": [], "--setup-mcp": ["--dry-run"], "--build-edges": [],
    "--any": [], "--relates": [], "--callers": ["--in", "--depth"], "--calls": ["--in", "--depth"], "--map": ["--focus", "--tokens"], "--export": ["--focus"],
    "--symbols": [], "--feature": [], "--features": [], "--hubs": [], "--print": [],
    "--find": ["--kind"], "--search": ["--kind"],
    "--routes": [], "--route": [], "--affected": [],
  };
  const presentCommands = Object.keys(COMMANDS).filter(has);
  if (presentCommands.length > 1) {
    console.error(`conflicting commands: ${presentCommands.join(", ")} — pass exactly one.\ntry \`agentmap --help\` for the list of commands.`);
    process.exit(2);
  }
  // --export owns stdout (it prints graph text); --json is a competing output contract.
  if (has("--export") && has("--json")) {
    console.error("--export writes graph text to stdout; it is not compatible with --json.\ntry `agentmap --help`.");
    process.exit(2);
  }
  // sub-flag → its declared parent command(s). A sub-flag shared by two commands
  // (--dry-run: --install-hooks or --setup-mcp) is valid if ANY parent is present.
  const subFlagParents = new Map();
  for (const [cmd, subs] of Object.entries(COMMANDS))
    for (const sub of subs) getOrSet(subFlagParents, sub, () => []).push(cmd);
  for (const [sub, parents] of subFlagParents)
    if (has(sub) && !parents.some(has)) {
      console.error(`${sub} requires ${parents.join(" or ")} — got: ${args.join(" ") || "(none)"}\ntry \`agentmap --help\` for usage.`);
      process.exit(2);
    }

  // --mcp: hand off to the stdio MCP server (authored separately). Dynamic import
  // so a missing mcp.mjs only fails when --mcp is actually requested. Pass mcpQuery
  // in explicitly — this branch runs inside main()'s top-level await, so agentmap.mjs
  // is still "evaluating" and mcp.mjs can NOT import it back without deadlocking;
  // injection sidesteps the cycle (mcp.mjs imports it itself only on a direct
  // `node mcp.mjs` run, which is not cyclic).
  if (has("--mcp")) {
    try {
      // .href, not the URL object: both resolve identically at runtime, but the
      // dynamic-import signature is typed as string, so the object form is the
      // one thing in this file the typecheck gate cannot see past.
      const m = await import(new URL("./mcp.mjs", import.meta.url).href);
      await m.serve(mcpQuery);
    } catch (e) {
      console.error(`agentmap --mcp failed: ${e?.message || e}`);
      process.exit(3);
    }
  }
  // --install-hooks: wire the git post-commit refresh + emit the PreToolUse
  // snippet. Self-contained (resolves the package hooks/ dir relative to here).
  else if (has("--install-hooks")) {
    try { installHooks({ dryRun: has("--dry-run") }); process.exit(0); }
    catch (e) { console.error(`agentmap --install-hooks failed: ${e?.message || e}`); process.exit(3); }
  }
  // --install-skill: copy packaged SKILL.md / Cursor rule (see skills/install.mjs).
  else if (has("--install-skill")) {
    try {
      // lazy import keeps skills/install.mjs (and its package.json read) OFF the
      // hot path — warm --any/--find queries must not load it.
      const { installSkill } = await import("./skills/install.mjs");
      installSkill({
        platforms: arg("--platform") || "all",
        project: !has("--global"),
        global: has("--global"),
        dryRun: has("--dry-run"),
      });
      process.exit(0);
    } catch (e) {
      console.error(`agentmap --install-skill failed: ${e?.message || e}`);
      process.exit(3);
    }
  }
  // --hook-status: report post-commit / nudge / settings wiring (no writes).
  else if (has("--hook-status")) {
    try { hookStatus(); process.exit(0); }
    catch (e) { console.error(`agentmap --hook-status failed: ${e?.message || e}`); process.exit(3); }
  }
  // --build-edges: precompute the call-edge sidecar that --callers reads. Explicit
  // (never implicit) because it costs ~4x a normal build — the post-commit hook
  // runs it in the background so no interactive query ever waits on it.
  else if (has("--build-edges")) {
    try {
      const r = buildCallEdges();
      if (wantJson) console.log(JSON.stringify({ command: "build-edges", ...r }));
      else console.log(`agentmap: ${r.edges} call edges from ${r.sites} sites across ${r.files} files → ${EDGES}`);
      process.exit(0);
    } catch (e) {
      console.error(`agentmap --build-edges failed: ${e?.message || e}`);
      process.exit(3);
    }
  }
  // --doctor: read-only harness health report (hooks + skills + MCP + map cache).
  // Always exits 0; never writes. --json emits the structured report.
  else if (has("--doctor")) {
    try {
      const report = await collectDoctorReport();
      if (wantJson) console.log(JSON.stringify(report, null, 2));
      else console.log(formatDoctorReport(report));
      process.exit(0);
    } catch (e) {
      console.error(`agentmap --doctor failed: ${e?.message || e}`);
      process.exit(3);
    }
  }
  // --setup-mcp: configure MCP server for OpenCode & Antigravity IDE.
  else if (has("--setup-mcp")) {
    try { setupMcp({ dryRun: has("--dry-run") }); process.exit(0); }
    catch (e) { console.error(`agentmap --setup-mcp failed: ${e?.message || e}`); process.exit(3); }
  }
  else 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.error('--any needs a query, e.g. `--any PremiumCard` or `--any "multi-modal"`'); process.exitCode = 2; }
    else {
      const q = raw.toLowerCase();
      const data = ensureFresh();
      const keys = Object.keys(data.files);
      const { key: fileKey, candidates } = resolveFile(keys, data.files, raw);
      // structured symbol/feature hits (reused by both prose + JSON shapes),
      // ranked by PageRank and capped so a broad query can't dump thousands.
      const symAll = [];
      for (const [path, f] of Object.entries(data.files)) {
        for (const e of f.exports)
          if (e.name.toLowerCase().includes(q)) symAll.push(symMatch(path, e));
        if (INCLUDE_LOCALS) for (const e of (f.locals || []))
          if (e.name.toLowerCase().includes(q)) symAll.push({ file: path, name: e.name, kind: e.kind, local: true });
      }
      const symTotal = symAll.length;
      const symObjs = rankMatches(data.files, symAll).slice(0, SYMBOL_MATCH_LIMIT);
      const symTrunc = symTotal > symObjs.length;
      const symFoot = symTrunc ? ` (showing top ${symObjs.length} of ${symTotal} by pagerank — narrow your query)` : "";
      const symHits = symObjs.map((s) => `  ${s.file} → ${s.name} (${s.kind})${originNote(s)}`);
      const featNames = Object.keys(data.features || {}).filter((k) => k.toLowerCase().includes(q));
      if (fileKey) {
        // A file resolved — but ALSO surface symbol/feature hits (fix #3) so a
        // loose path match (e.g. "auth") can't shadow a symbol the user wanted.
        const f = data.files[fileKey];
        out({ command: "any", query: raw, kind: "file", file: fileKey, pagerank: f.pagerank ?? null, exports: f.exports, imports: f.imports, dependents: f.dependents, ...typeOnlyOut(f), symbols: symObjs, symbolsTotal: symTotal, symbolsTruncated: symTrunc, features: featNames.map((n) => ({ name: n, count: data.features[n].length })) }, () => {
          console.log(`[structure:file] ${fileKey}  (pr ${f.pagerank ?? "—"})`);
          fileBlock(fileKey, f);
          if (symHits.length) { console.log(`[structure] ${symTotal} symbol match for "${raw}"${symFoot}:`); console.log(symHits.join("\n")); }
          if (featNames.length) console.log("features: " + featNames.map((n) => `${n} (${data.features[n].length})`).join(", "));
        });
      } else if (symHits.length || featNames.length) {
        out({ command: "any", query: raw, kind: "structure", symbols: symObjs, symbolsTotal: symTotal, symbolsTruncated: symTrunc, features: featNames.map((n) => ({ name: n, count: data.features[n].length })) }, () => {
          console.log(`[structure] ${symTotal} symbol, ${featNames.length} feature match for "${raw}"${symFoot}`);
          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) {
        out({ command: "any", query: raw, kind: "candidates", candidates }, () => {
          console.log(`[structure] "${raw}" matched ${candidates.length} files — narrow it:`);
          for (const k of candidates) console.log(`  ${k}`);
        });
      } else {
        // Lexical (BM25) rung — fires ONLY when exact file/symbol/feature matching
        // found nothing, so every existing --any assertion stays byte-identical. If
        // BM25 is also empty, fall through to the git-grep content search as before.
        const lex = bm25Search(data.lexical, data.files, raw);
        if (lex.matches.length) {
          const trunc = lex.total > lex.matches.length;
          out({ command: "any", query: raw, kind: "lexical", matches: lex.matches, total: lex.total, shown: lex.matches.length, truncated: trunc }, () => {
            console.log(`[lexical] ${lex.total} match for "${raw}"${trunc ? ` (showing top ${lex.matches.length} by relevance)` : ""}:`);
            console.log(lex.matches.map((m) => `  ${m.file} → ${m.name} (${m.kind})  [${m.score}]`).join("\n"));
          });
        } else {
          const res = contentSearch(raw);
          if (!res) {
            process.exitCode = 1;
            out({ command: "any", query: raw, kind: "empty" }, () => console.log(`[content] 0 match for "${raw}" (git grep, tracked + untracked)`));
          } else {
            const lines = res.split("\n");
            const shown = lines.slice(0, CONTENT_LINES_LIMIT);
            out({ command: "any", query: raw, kind: "content", total: lines.length, lines: shown }, () => {
              console.log(`[content] ${lines.length} line${lines.length > 1 ? "s" : ""}${lines.length > CONTENT_LINES_LIMIT ? ` (showing ${CONTENT_LINES_LIMIT})` : ""}:`);
              console.log(shown.join("\n"));
            });
          }
        }
      }
    }
  } else if (has("--search")) {
    const raw = arg("--search");
    if (!raw) { console.error('--search needs a query, e.g. `--search "auth retry logic"`'); process.exitCode = 2; }
    else {
      const data = ensureFresh();
      const lex = bm25Search(data.lexical, data.files, raw);
      if (kindFilter) { lex.matches = lex.matches.filter((m) => kindOk(m.kind)); lex.total = lex.matches.length; }
      if (!lex.matches.length) process.exitCode = 1;
      const trunc = lex.total > lex.matches.length;
      out({ command: "search", query: raw, ...(kindFilter ? { kind: kindFilter } : {}), total: lex.total, shown: lex.matches.length, truncated: trunc, matches: lex.matches }, () => {
        console.log(`search "${raw}"${kindFilter ? ` kind~${kindFilter}` : ""}: ${lex.total} match${trunc ? ` (showing top ${lex.matches.length} by relevance)` : ""}`);
        if (lex.matches.length) console.log(lex.matches.map((m) => `  ${m.file} → ${m.name} (${m.kind})  [${m.score}]`).join("\n"));
      });
    }
  } else if (has("--find")) {
    const raw = arg("--find");
    if (!raw) { console.error("--find needs a symbol query, e.g. `--find PremiumCard`"); process.exitCode = 2; }
    else {
      const q = raw.toLowerCase();
      const data = ensureFresh();
      const all = [];
      for (const [path, f] of Object.entries(data.files)) {
        for (const e of f.exports)
          if (e.name.toLowerCase().includes(q) && kindOk(e.kind)) all.push(symMatch(path, e));
        if (INCLUDE_LOCALS) for (const e of (f.locals || []))
          if (e.name.toLowerCase().includes(q) && kindOk(e.kind)) all.push({ file: path, name: e.name, kind: e.kind, local: true });
      }
      if (!all.length) process.exitCode = 1;
      const ranked = rankMatches(data.files, all);
      const matches = ranked.slice(0, SYMBOL_MATCH_LIMIT);
      const truncated = ranked.length > matches.length;
      out({ command: "find", query: raw, ...(kindFilter ? { kind: kindFilter } : {}), total: ranked.length, shown: matches.length, truncated, matches }, () => {
        console.log(`find "${raw}"${kindFilter ? ` kind~${kindFilter}` : ""}: ${ranked.length} match${truncated ? ` (showing top ${matches.length} by pagerank — narrow your query)` : ""}`);
        if (matches.length) console.log(matches.map((m) => `  ${m.file} → ${m.name} (${m.kind})${originNote(m)}`).join("\n"));
      });
    }
  } else if (has("--relates")) {
    const q = arg("--relates");
    if (!q) { console.error("--relates needs a file path/name, e.g. `--relates agentmap.mjs`"); process.exitCode = 2; }
    else {
      const data = ensureFresh();
      const keys = Object.keys(data.files);
      const { key, candidates } = resolveFile(keys, data.files, q);
      if (!key) {
        process.exitCode = 1;
        out({ command: "relates", error: "no match", query: q, candidates: candidates || [] }, () => {
          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];
        // 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, RELATED_LIMIT);
        out({ command: "relates", file: key, ...(f.rsc ? { rsc: f.rsc } : {}), pagerank: f.pagerank ?? null, exports: f.exports, imports: f.imports, dependents: f.dependents, ...typeOnlyOut(f), related: top.map(([file, score]) => ({ file, score: +score.toFixed(6) })) }, () => {
          console.log(`relates: ${key}  (pr ${f.pagerank ?? "—"})`);
          fileBlock(key, f);
          console.log(`related (random-walk relevance):`);
          for (const [k, r] of top) console.log(`  ${k} (${r.toFixed(4)})`);
        });
      }
    }
  } else if (has("--callers")) {
    const raw = arg("--callers");
    if (!raw) { console.error("--callers needs a symbol, e.g. `--callers extractFacts`"); process.exitCode = 2; }
    else {
      const r = callGraph(raw, { inFilter: arg("--in") || "", depth: parseInt(arg("--depth") || "1", 10) });
      const { _code, ...obj } = r;
      if (_code) process.exitCode = _code;
      out(obj, () => {
        if (obj.error === "ambiguous") {
          console.log(`callers: "${raw}" is defined in ${obj.candidates.length} files — disambiguate with --in <path>:`);
          for (const k of obj.candidates) console.log(`  ${k}`);
        } else if (obj.error === "no match") {
          console.log(`callers: no symbol named "${raw}" in the map (exact match; try --find "${raw}")`);
        } else if (obj.error === "degraded") {
          console.log(`callers: ${raw} (${obj.file}) — ${obj.reason}`);
        } else {
          const foot = obj.truncated
            ? (obj.depth > 1 ? ` (truncated at the ${obj.total}-node cap — narrow with --in or lower --depth)` : ` (showing top ${obj.shown} of ${obj.total} by pagerank — narrow with --in)`)
            : "";
          const unit = obj.depth > 1 ? `caller${obj.total === 1 ? "" : "s"} within depth ${obj.depth}` : `call site${obj.total === 1 ? "" : "s"}`;
          console.log(`callers of ${raw}  [${obj.file}]: ${obj.total} ${unit}${foot}`);
          for (const c of obj.callers) console.log(`  ${c.file}:${c.line} → ${c.caller}${c.depth > 1 ? ` [depth ${c.depth}]` : ""}`);
        }
      });
    }
  } else if (has("--calls")) {
    const raw = arg("--calls");
    if (!raw) { console.error("--calls needs a symbol, e.g. `--calls extractFacts`"); process.exitCode = 2; }
    else {
      const r = callGraph(raw, { inFilter: arg("--in") || "", direction: "calls", depth: parseInt(arg("--depth") || "1", 10) });
      const { _code, ...obj } = r;
      if (_code) process.exitCode = _code;
      out(obj, () => {
        if (obj.error === "ambiguous") {
          console.log(`calls: "${raw}" is defined in ${obj.candidates.length} files — disambiguate with --in <path>:`);
          for (const k of obj.candidates) console.log(`  ${k}`);
        } else if (obj.error === "no match") {
          console.log(`calls: no symbol named "${raw}" in the map (exact match; try --find "${raw}")`);
        } else if (obj.error === "degraded") {
          console.log(`calls: ${raw} (${obj.file}) — ${obj.reason}`);
        } else {
          const foot = obj.truncated
            ? (obj.depth > 1 ? ` (truncated at the ${obj.total}-node cap — narrow with --in or lower --depth)` : ` (showing top ${obj.shown} of ${obj.total} by pagerank — narrow with --in)`)
            : "";
          console.log(`${raw} calls  [${obj.file}]: ${obj.total} in-project target${obj.total === 1 ? "" : "s"}${obj.depth > 1 ? ` within depth ${obj.depth}` : ""}${foot}`);
          for (const c of obj.calls) console.log(`  ${c.file}:${c.line} → ${c.name} (${c.kind})${c.depth > 1 ? ` [depth ${c.depth}]` : ""}`);
        }
      });
    }
  } else if (has("--map")) {
    // Token-budgeted ranked digest (Aider's killer feature). --focus <path>
    // personalizes toward a file; default budget FOCUS_BUDGET, ×8 with no focus.
    const focusArg = arg("--focus");
    // #14: `--focus` present but with NO value (it's the last arg, or another
    // flag follows) — warn + exit 2 instead of silently using the global budget.
    if (has("--focus") && focusArg === undefined) {
      console.error("--focus needs a file path/name, e.g. `--map --focus agentmap.mjs`");
      process.exitCode = 2;
    } else {
      const data = ensureFresh();
      const tk = parseInt(arg("--tokens") ?? "", 10);
      const budget = Number.isFinite(tk) && tk > 0 ? tk : (focusArg ? FOCUS_BUDGET : DEFAULT_BUDGET);
      let ranked = data.rankedSymbols || [];
      let focusLabel = "global";
      // focusResolved reports the outcome of a REQUESTED --focus only: true when it
      // resolved to a file, false when it matched 0 or 2+ candidates (the silent-
      // degrade case). Left undefined when no --focus was passed, so the JSON key is
      // omitted below — nothing was requested, so there's nothing to report.
      let focusResolved;
      if (focusArg) {
        const { key, candidates } = resolveFile(Object.keys(data.files), data.files, focusArg);
        if (key) { ranked = rankSymbols(data.files, new Set([key])); focusLabel = key; focusResolved = true; }
        else {
          console.error(`# warning: --focus "${focusArg}" matched ${(candidates && candidates.length) || 0} files — using global ranking`);
          focusResolved = false;
          // Reserve exit 1 for "query had zero results": an unresolved --focus is an
          // unresolved query even though the global digest below still prints a
          // useful (degraded) answer — same shape as --find/--feature no-match.
          process.exitCode = 1;
        }
      }
      // 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 })));
      // Budget the digest into per-file blocks; collect the SHOWN files (with the
      // exact symbols that fit) so prose + JSON render from one source of truth.
      let used = 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); }
      const shownFiles = []; // [{ file, symbols:[{name,kind}] }]
      let first = true;
      for (const [file, syms] of byFile) {
        const capped = syms.slice(0, SYMS_PER_FILE);
        const lineOf = (arr) => `\n${file}:\n` + arr.map((s) => `  ${s.name} (${s.kind})`).join("\n");
        const t = tokEst(lineOf(capped));
        if (used + t > budget) {
          // #13: if the FIRST (highest-ranked) block alone overruns the budget,
          // emit a PARTIAL block (fewer symbols) so the top file is never wholly
          // omitted. Otherwise `continue` so smaller lower-ranked files can still
          // fill the remaining budget (don't `break` on the first overflow).
          if (first && budget > 0) {
            // #6 fix: try progressively fewer symbols DOWN TO ONE. The old
            // `while (partial.length > 1)` sliced before testing and never tried
            // the single-symbol block, so a tiny --tokens could emit NOTHING for
            // the top file despite the "never wholly omitted" intent. If even one
            // symbol overflows the budget, nothing fits (correct) — but we now try.
            for (let k = capped.length - 1; k >= 1; k--) {
              const partial = capped.slice(0, k);
              const pt = tokEst(lineOf(partial));
              if (used + pt <= budget) {
                used += pt;
                shownFiles.push({ file, symbols: partial.map((s) => ({ name: s.name, kind: s.kind })) });
                break;
              }
            }
            first = false;
          }
          continue;
        }
        used += t; first = false;
        shownFiles.push({ file, symbols: capped.map((s) => ({ name: s.name, kind: s.kind })) });
      }
      out({ command: "map", focus: focusLabel, ...(focusResolved !== undefined ? { focusResolved } : {}), budget, tokens: used, files: shownFiles }, () => {
        console.log(`# agentmap (${data.fileCount} files, sha ${data.generatedSha}) — focus: ${focusLabel}, budget ~${budget} tok`);
        for (const { file, symbols } of shownFiles)
          console.log(`\n${file}:\n` + symbols.map((s) => `  ${s.name} (${s.kind})`).join("\n"));
        console.log(`\n# ~${used} tokens (${shownFiles.length} files shown)`);
      });
    }
  } else if (has("--export")) {
    const fmt = arg("--export");
    if (fmt !== "mermaid" && fmt !== "dot") { console.error("--export needs a format: `--export mermaid` or `--export dot`"); process.exitCode = 2; }
    else {
      const data = ensureFresh();
      const focusArg = arg("--focus");
      if (has("--focus") && !focusArg) { console.error("--focus needs a file path/name, e.g. `--export dot --focus agentmap.mjs`"); process.exitCode = 2; }
      else {
        let keep = Object.keys(data.files);
        let focusLabel = null;
        if (focusArg) {
          const { key } = resolveFile(keep, data.files, focusArg);
          if (!key) { console.error(`# warning: --focus "${focusArg}" matched no file — exporting the full graph`); process.exitCode = 1; }
          else {
            focusLabel = key;
            const f = data.files[key];
            const nb = new Set([key, ...f.imports.filter((p) => data.files[p]), ...f.dependents]);
            keep = keep.filter((k) => nb.has(k));
          }
        }
        // rank-cap: top-N files by PageRank, then keep only edges whose endpoints both survived.
        keep.sort((a, b) => (data.files[b].pagerank || 0) - (data.files[a].pagerank || 0));
        const kept = keep.slice(0, EXPORT_NODE_CAP);
        const keptSet = new Set(kept);
        const nodes = kept.map((p) => ({ path: p, pagerank: data.files[p].pagerank || 0 }));
        const edges = [];
        for (const p of kept) for (const t of data.files[p].imports) if (keptSet.has(t)) edges.push({ from: p, to: t });
        const meta = { fileCount: data.fileCount, sha: data.generatedSha, shown: kept.length, focus: focusLabel, capped: keep.length > kept.length };
        console.log(fmt === "dot" ? toDot(nodes, edges, meta) : toMermaid(nodes, edges, meta));
      }
    }
  } else if (has("--symbols")) {
    const data = ensureFresh();
    const sn = parseInt(arg("--symbols") ?? "", 10); const n = Number.isFinite(sn) && sn > 0 ? sn : DEFAULT_SYMBOLS;
    const syms = rankedSymbolsFor(data, n);
    out({ command: "symbols", requested: n, shown: syms.length, truncated: syms.length < n, symbols: syms.map((s) => ({ rank: s.rank, file: s.file, name: s.name, kind: s.kind })) }, () => {
      console.log(`top ${syms.length} ranked symbols (Aider-style)${syms.length < n ? ` — asked for ${n}, this repo only ranks ${syms.length}` : ""}:`);
      for (const s of syms) console.log(`  ${s.rank}  ${s.file} → ${s.name} (${s.kind})`);
    });
  } else if (has("--feature")) {
    const raw = arg("--feature");
    if (!raw) { console.error("--feature needs a name, e.g. `--feature dashboard` (run --features to list)"); process.exitCode = 2; }
    else {
    const 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 (!Object.keys(data.features).length) {
      // "no match" would be a lie here: there is nothing to match against, because
      // the repo has no App Router at all. Distinguish the two.
      process.exitCode = 1;
      out({ command: "feature", query: raw, error: "not applicable", reason: NOT_APP_ROUTER, _code: 1 },
        () => console.log(`feature "${raw}": no app/ or src/app/ directory — --feature is Next.js App Router only`));
    } else if (!name) {
      process.exitCode = 1;
      out({ command: "feature", error: "no match", query: raw }, () => 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);
      out({ command: "feature", name, files: fl, externalDependents: [...exts] }, () => {
        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]);
    if (!list.length) {
      // A feature is the first route segment under app/ or src/app/ — this command
      // is Next.js App Router only. Returning `{}` with exit 0 told every Vue, Nuxt,
      // Remix, Astro and plain-Node repo "you have no features", which reads as a
      // finding rather than as "not applicable". The consumer here is an LLM that
      // reads payloads, not READMEs, so the payload has to say why. Same shape as
      // --routes below.
      out({ command: "features", features: {}, reason: NOT_APP_ROUTER, _code: 1 },
        () => console.log("features: no app/ or src/app/ directory — --features is Next.js App Router only"));
      process.exitCode = 1;
    } else out({ command: "features", features: Object.fromEntries(list) }, () => {
      console.log(`features (${list.length}):`);
      for (const [k, n] of list) console.log(`  ${k} (${n} files)`);
    });
  } else if (has("--affected")) {
    const raw = arg("--affected");
    if (!raw) { console.error("--affected needs a file path, e.g. `--affected lib/auth.ts`"); process.exitCode = 2; }
    else {
      const data = ensureFresh();
      // Accept a suffix so `--affected auth.ts` works without the full path, but
      // refuse to guess when it is ambiguous — silently picking one of two files
      // would answer a question the user did not ask.
      const exact = data.files[raw] ? [raw] : Object.keys(data.files).filter((p) => p === raw || p.endsWith(`/${raw}`));
      if (!exact.length) {
        out({ command: "affected", query: raw, error: "no match", candidates: [], _code: 1 },
          () => console.log(`affected "${raw}": no such file in the map`));
        process.exitCode = 1;
      } else if (exact.length > 1) {
        out({ command: "affected", query: raw, error: "ambiguous", candidates: exact, _code: 1 }, () => {
          console.log(`affected: "${raw}" matches ${exact.length} files — name one:`);
          for (const c of exact) console.log(`  ${c}`);
        });
        process.exitCode = 1;
      } else {
        const file = exact[0];
        const reach = transitiveDependents(data, file);
        const tests = [...reach].filter(([p]) => TEST_FILE_RE.test(p))
          .sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1))
          .map(([p, hop]) => ({ file: p, hop }));
        const selfIsTest = TEST_FILE_RE.test(file);
        out({
          command: "affected", query: raw, file,
          dependents: reach.size, tests: tests.length, covered: tests.length > 0 || selfIsTest,
          affected: tests,
        }, () => {
          console.log(`affected by ${file}: ${tests.length} test file${tests.length === 1 ? "" : "s"} (of ${reach.size} transitive dependents)`);
          for (const t of tests) console.log(`  ${t.file}  [${t.hop} hop${t.hop === 1 ? "" : "s"}]`);
          // An empty list is the ANSWER, not a failure — and it is the answer that
          // matters most before a risky edit, so say it in words.
          if (!tests.length && !selfIsTest) console.log("  (none — this file has no test coverage reachable through imports)");
        });
      }
    }
  } else if (has("--routes")) {
    const data = ensureFresh();
    const routes = buildRouteTable(data);
    if (!routes) {
      out({ command: "routes", routes: [], reason: "no Next.js App Router directory (app/ or src/app/)", _code: 1 },
        () => console.log("routes: no app/ or src/app/ directory — not a Next.js App Router project"));
      process.exitCode = 1;
    } else {
      out({ command: "routes", total: routes.length, routes }, () => {
        const pages = routes.filter((r) => r.kind === "page").length;
        console.log(`routes (${routes.length}): ${pages} pages, ${routes.length - pages} api`);
        for (const r of routes) {
          const m = r.methods?.length ? ` [${r.methods.join(",")}]` : "";
          const a = r.alias ? `  -> ${r.alias}` : "";
          const b = r.boundary ? ` (${r.boundary})` : "";
          console.log(`  ${r.url}${m}${b}  ${r.file}${a}`);
        }
      });
    }
  } else if (has("--route")) {
    const raw = arg("--route");
    if (!raw) { console.error("--route needs a URL or file, e.g. `--route /brands/123` (run --routes to list)"); process.exitCode = 2; }
    else {
      const data = ensureFresh();
      const routes = buildRouteTable(data);
      const hits = routes ? matchRoute(routes, raw) : [];
      if (!hits.length) {
        out({ command: "route", query: raw, matches: [], _code: 1 },
          () => console.log(`route "${raw}": no match (run --routes to list)`));
        process.exitCode = 1;
      } else {
        // Enrich each hit with what the map already knows: the modules the
        // handler imports, flagged by RSC boundary — i.e. the server actions a
        // page can actually reach.
        const enriched = hits.map((r) => {
          const f = data.files[r.file] || {};
          const serverDeps = (f.imports || []).filter((i) => data.files[i]?.rsc === "server");
          return { ...r, imports: f.imports || [], serverModules: serverDeps };
        });
        out({ command: "route", query: raw, total: enriched.length, matches: enriched }, () => {
          for (const r of enriched) {
            console.log(`${r.url}${r.methods?.length ? ` [${r.methods.join(",")}]` : ""}  (${r.kind})`);
            console.log(`  serves: ${r.file}${r.boundary ? `  boundary: '${r.boundary}'` : ""}`);
            if (r.alias) console.log(`  alias of: ${r.alias}`);
            if (r.layoutChain.length) console.log(`  layouts (outer->inner): ${r.layoutChain.join(" -> ")}`);
            if (r.serverModules.length) console.log(`  server modules: ${r.serverModules.join(", ")}`);
          }
        });
      }
    }
  } else if (has("--hubs")) {
    const data = ensureFresh();
    out({ command: "hubs", fileCount: data.fileCount, sha: data.generatedSha, hubs: data.hubs }, () => {
      console.log(`agentmap: ${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();
    // --print is already JSON-only; add top-level fileCount (was omitted before).
    console.log(JSON.stringify({ fileCount: data.fileCount, hubs: data.hubs, features: data.features, rankedSymbols: data.rankedSymbols, files: data.files }));
  } else {
    // Bare invocation (possibly `--json` alone): build + one-line summary, or the
    // {command:"build", ...} JSON object.
    const built = build();
    const topHub = built.hubs[0] || null;
    out({ command: "build", fileCount: built.fileCount, features: Object.fromEntries(Object.entries(built.features).map(([k, v]) => [k, v.length])), topHub, edgeCoverage: built.edgeCoverage, degraded: built.degraded }, () => {
      console.log(`agentmap: ${built.fileCount} files | ${Object.keys(built.features).length} features | top hub: ${topHub || "—"}`);
    });
  }
}

// ---------------------------------------------------------------------------
// In-process query API for the MCP server. Each of the 8 query tools
// (any/find/relates/map/hubs/features/feature/symbols) is answered here against
// a map parsed ONCE and cached, instead of spawning `node agentmap.mjs --json …`
// per call. The object each branch returns is BYTE-IDENTICAL to what the matching
// main() branch feeds out() — the same construction reusing the same module-scoped
// helpers + limit constants, so the MCP JSON never drifts from the CLI --json.
// Returns { code, obj, stderr }: obj = the object the CLI JSON.stringifies to
// stdout (or null for a usage error → stderr + exit 2); code = 0 ok / 1 zero-result
// / 2 usage error; stderr = the exact usage message (code 2), else "". A build/parse
// failure THROWS (as on the CLI) so mcp.mjs surfaces isError (crash-masking).
// mcpEnsureFresh() memoizes ensureFresh()'s result across calls, keyed by the SAME
// freshness signal ensureFresh uses (schema|generatedSha|dirty|dirtyFingerprint|
// fingerprint); a key match returns the cached map, any mismatch re-runs ensureFresh.
// ---------------------------------------------------------------------------
let _mcpMapCache = null; // { key, data }
function mcpFreshKey(d) {
  return [d.schema, d.generatedSha, d.dirty, d.dirtyFingerprint ?? "", d.fingerprint ?? ""].join("|");
}
function mcpEnsureFresh() {
  const data = ensureFresh();
  const key = mcpFreshKey(data);
  if (_mcpMapCache && _mcpMapCache.key === key) return _mcpMapCache.data;
  _mcpMapCache = { key, data };
  return data;
}
// Test/rebuild seam: drop the in-memory map cache (force a re-derive without a
// fresh process). Optional — exported only for convenience.
function mcpResetCache() { _mcpMapCache = null; }

// --- Compiler-accurate call graph (--callers) -------------------------------
// LAZY, out-of-band, symbol-level blast radius: "who CALLS this symbol?",
// resolved by the TS language service (ts-morph findReferencesAsNodes), NOT by
// tree-sitter name-matching. This is the ONLY query that builds a ts-morph
// Project outside build()/extractFacts(): Phase A resolves the symbol NAME → its
// defining file from the CACHED map (cheap — no Project, no type-checker); only a
// clean single-owner resolution proceeds to Phase B, which spins up the full
// Project + type-checker (seconds on a big repo) and walks references. Nothing is
// persisted — references go stale on any edit, so we recompute per call. The fast
// path (build/--map/--find/--relates/--hubs) never constructs a Project, so it is
// provably untouched. Returns a plain object; `_code` is the exit code (stripped
// by both callers before it reaches the user).
// Given a reference identifier, return the node that INVOKES it, or null.
//
// Two shapes count as an invocation:
//   1. `foo()` / `ns.foo()` — a CallExpression whose CALLEE (not an argument) is
//      this identifier. The two-hop PropertyAccessExpression check is what makes
//      `ns.foo()` resolve while `foo(ns.bar)` correctly does not.
//   2. `<Foo />` / `<Foo>…</Foo>` — a JSX element whose TAG NAME is this
//      identifier. JSX is an invocation in every runtime (classic compiles to
//      `React.createElement(Foo, …)`, automatic to `jsx(Foo, …)`), and a user
//      asking "who calls Container" means the components rendering it.
//
// Shape 2 was missing, so `--callers` under-reported every React component while
// still exiting 0 under a "compiler-accurate" label — the exact silent-degradation
// class this tool exists to avoid. Verified before the fix: a 4-file TSX fixture
// with one direct call and two JSX usages returned 1 of 3.
//
// JsxClosingElement is deliberately NOT matched: `<Foo>…</Foo>` is ONE call site,
// and matching the closing tag too would double-count it on multi-line elements.
//
// `SyntaxKind` is passed in rather than closed over, so this stays a pure
// module-scope helper against the lazily-loaded ts-morph (same shape as
// rscBoundary at :450).
function invocationOf(id, SyntaxKind) {
  // `new Foo()` is an invocation exactly as much as `foo()` is. Only CallExpression
  // was matched here, so a class reachable ONLY via `new` reported ZERO callers —
  // silently, with exit 1, indistinguishable from genuinely-unused. It bit the
  // transitive --depth path too, since that shares this predicate.
  let call = id.getParentIfKind(SyntaxKind.CallExpression) ?? id.getParentIfKind(SyntaxKind.NewExpression);
  const pa = id.getParentIfKind(SyntaxKind.PropertyAccessExpression);
  if (!call && pa) call = pa.getParentIfKind(SyntaxKind.CallExpression) ?? pa.getParentIfKind(SyntaxKind.NewExpression);
  // When the reference sits under a member expression, it must be the NAME half.
  // Without this guard `db.query()` was reported as a call site of `db`: the
  // reference to `db` is the OBJECT, `pa` is `db.query`, and `call.getExpression()
  // === pa` holds — so every exported object/array/singleton const collected every
  // method call made on it, silently, with exit 0, under a "compiler-accurate"
  // label. The sidecar edge builder already applies exactly this check
  // (`callee.getNameNode()`), so the two walks disagreed and the answer depended
  // on whether the background --build-edges had finished.
  if (call && call.getExpression() === (pa ?? id) && (!pa || pa.getNameNode() === id)) return call;

  // `<Foo.Bar />` puts the identifier under a member expression; the element's
  // tag-name node is that member expression, not the bare identifier. TypeScript
  // models a dotted JSX tag as a plain PropertyAccessExpression — there is NO
  // `SyntaxKind.JsxMemberExpression` (that is a Babel/ESTree node type, and
  // reading it off SyntaxKind yields `undefined`, so getParentIfKind never
  // matched and this whole branch was dead from 0.17.0). `pa` above already
  // holds that node.
  //
  // Same name-half guard as the call branch above: for `<Dialog.Root />` the tag
  // resolves to `Root`, and a reference to `Dialog` (the namespace object) is NOT
  // a use of `Root`. Without it, every compound component credited its container.
  const tagHolder = pa && pa.getNameNode() === id ? pa : (pa ? null : id);
  for (const kind of tagHolder ? [SyntaxKind.JsxSelfClosingElement, SyntaxKind.JsxOpeningElement] : []) {
    const el = tagHolder.getParentIfKind(kind);
    if (el && el.getTagNameNode() === tagHolder) return el;
  }
  return null;
}

// A test file, by the conventions every JS test runner actually uses. Kept
// deliberately narrow: `/test/` as a bare path segment (not a substring, or
// `src/latest/x.ts` matches), and a `.test.`/`.spec.` infix before the extension.
const TEST_FILE_RE = /(^|\/)(__tests__|__mocks__|tests?)\/|\.(test|spec)\.[cm]?[jt]sx?$/;

// Transitive reverse dependency closure — every file that reaches `start` through
// import edges, at any depth. BFS with a visited set: an import cycle is normal in
// real code (barrels, type-only round-trips) and must terminate, not recurse.
// Returns a Map of file -> hop distance so a caller can report how far away a
// dependent is, which is what makes a long list triageable.
//
// Walks `dependents` UNION `typeOnlyDependents`. Type-only edges are excluded from
// PageRank on purpose (a type import is not a runtime dependency), but "what breaks
// if I change this" is exactly the question where they count: changing an exported
// type breaks every `import type` consumer at compile time. Reading only the runtime
// half made `--affected` report `covered:false` for files whose importers are all
// type-only — directly contradicting `--relates` on the same cached map.
function transitiveDependents(data, start) {
  const seen = new Map();
  let frontier = [start];
  let hop = 0;
  while (frontier.length) {
    hop++;
    const next = [];
    for (const f of frontier) {
      const e = data.files[f];
      if (!e) continue;
      for (const d of [...(e.dependents || []), ...(e.typeOnlyDependents || [])]) {
        if (seen.has(d) || d === start) continue;
        seen.set(d, hop);
        next.push(d);
      }
    }
    frontier = next;
  }
  return seen;
}

// ---------------------------------------------------------------------------
// Next.js App Router route table.
//
// Computed on demand from the filesystem rather than persisted: it is pure
// readdir + string work (single-digit ms even on 400 files), so caching it would
// buy nothing and add a staleness class. Nothing here touches map.json.
//
// The bar is a URL you can paste into a browser. That is precisely where a
// convention-only extractor goes wrong: a `(group)` folder organises the tree
// and contributes NOTHING to the URL, but it DOES contribute a layout. Emitting
// `/(app)/brands/:id` — a path that 404s — is worse than emitting nothing,
// because it looks authoritative.
// ---------------------------------------------------------------------------
const ROUTE_FILE_RE = /(^|\/)(page|route|layout)\.(t|j)sx?$/;

// Why --routes/--features return nothing on most repos. Stated once and reused by
// every surface (CLI + MCP) so the four commands cannot drift into disagreeing
// about what "empty" means — an empty payload with no reason reads as a finding.
const NOT_APP_ROUTER = "no Next.js App Router directory (app/ or src/app/) — this command is Next.js-only";
const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];

// One path segment -> its URL contribution, or null when it contributes none.
function routeSegment(seg) {
  if (/^\(.+\)$/.test(seg)) return null;               // (group) — organisational only
  if (/^@/.test(seg)) return null;                     // @slot — parallel route
  if (/^\[\[\.\.\..+\]\]$/.test(seg)) return `*${seg.slice(5, -2)}?`; // [[...rest]]
  if (/^\[\.\.\..+\]$/.test(seg)) return `*${seg.slice(4, -1)}`;      // [...rest]
  if (/^\[.+\]$/.test(seg)) return `:${seg.slice(1, -1)}`;            // [id]
  return seg;
}

function buildRouteTable(data) {
  // Derive the app dir from the MAP's own file list rather than the filesystem:
  // the map already honours .gitignore and the ignore rules, so a build artefact
  // or an untracked scratch file under app/ can never become a phantom route.
  const keys = Object.keys(data.files);
  const appDir = ["app", "src/app"].find((d) => keys.some((p) => p.startsWith(`${d}/`) && ROUTE_FILE_RE.test(p)));
  if (!appDir) return null;                            // not an App Router project
  const files = keys.filter((p) => p.startsWith(`${appDir}/`) && ROUTE_FILE_RE.test(p));
  const layouts = new Map();
  for (const f of files) if (/(^|\/)layout\.(t|j)sx?$/.test(f)) layouts.set(f.replace(/(^|\/)layout\.(t|j)sx?$/, ""), f);
  const routes = [];
  for (const f of files) {
    const kind = /(^|\/)page\./.test(f) ? "page" : /(^|\/)route\./.test(f) ? "route" : null;
    if (!kind) continue;                               // layout.tsx is chain-only, never its own URL
    const relDir = f.slice(appDir.length + 1).replace(/(^|\/)(page|route)\.(t|j)sx?$/, "");
    const segs = relDir === "" ? [] : relDir.split("/");
    const url = "/" + segs.map(routeSegment).filter((s) => s !== null).join("/");
    let src = ""; try { src = readFileSync(f, "utf8"); } catch {}
    const methods = kind === "route"
      ? HTTP_METHODS.filter((m) => new RegExp(`export\\s+(async\\s+)?(function|const)\\s+${m}\\b`).test(src))
      : null;
    // `export { default } from "X"` — a shim route that renders another route's
    // component. A convention-only extractor misses these entirely because there
    // is no `export default function` to match.
    const alias = src.match(/export\s*\{\s*default(?:\s+as\s+default)?\s*\}\s*from\s*["']([^"']+)["']/)?.[1] ?? null;
    // Layout chain: every ancestor dir INCLUDING (group) dirs — the groups that
    // vanish from the URL are exactly the ones that add a layout.
    //
    // PAGES ONLY. A route.ts handler is not wrapped by layout.tsx — layouts are
    // React components composing a rendered tree, and an API handler returns a
    // Response, never JSX. Reporting a layout chain for /api/* would be a
    // confident falsehood about what runs on that request.
    const chain = [];
    if (kind === "page") {
      let cur = f.replace(/(^|\/)(page)\.(t|j)sx?$/, "");
      for (;;) {
        if (layouts.has(cur)) chain.unshift(layouts.get(cur));
        if (!cur || cur === appDir) break;
        const up = cur.slice(0, cur.lastIndexOf("/"));
        if (up.length < appDir.length) break;
        cur = up === cur ? "" : up;
      }
    }
    routes.push({
      url: url.length > 1 ? url.replace(/\/+$/, "") : "/",
      kind, file: f,
      ...(methods ? { methods } : {}),
      ...(alias ? { alias } : {}),
      layoutChain: chain,
      boundary: data.files[f]?.rsc ?? null,
    });
  }
  routes.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : (a.kind < b.kind ? -1 : 1)));
  return routes;
}

// Match a concrete URL against the table, honouring dynamic segments.
function matchRoute(routes, q) {
  const norm = (u) => ("/" + u.replace(/^\/+|\/+$/g, "")).replace(/\/+/g, "/");
  const direct = routes.filter((r) => r.url === norm(q) || r.file === q || r.file.endsWith(`/${q}`));
  if (direct.length) return direct;
  const parts = norm(q).split("/").filter(Boolean);
  return routes.filter((r) => {
    const rp = r.url.split("/").filter(Boolean);
    if (rp.some((s) => s.startsWith("*"))) {
      const fixed = rp.filter((s) => !s.startsWith("*"));
      return fixed.every((s, i) => s.startsWith(":") || s === parts[i]);
    }
    if (rp.length !== parts.length) return false;
    return rp.every((s, i) => s.startsWith(":") || s === parts[i]);
  });
}

// Resolve the named function/class that lexically encloses a reference node.
// Module scope because BOTH the live callGraph() walk and the sidecar sweep must
// name callers identically — a second copy would drift and make the two paths
// disagree. An anonymous callback (`.map(x => <Foo/>)`, an IIFE,
// `startTransition(async () => …)`) is NOT an answer — it has no name worth
// printing and no findReferences-able node to recurse on — so keep walking OUTWARD
// until a named owner appears rather than giving up at the first anonymous
// ancestor. Returns `{name, node}`: `node` is what the transitive BFS recurses on
// (null when the owner cannot be recursed on); "<module>" means genuinely
// top-level, not merely "wrapped in a callback".
function enclosingOwner(id, SyntaxKind) {
  let cur = id;
  for (;;) {
    const enc = cur.getFirstAncestor((an) => /Function|Method|Constructor|ClassDeclaration/.test(an.getKindName()));
    if (!enc) return { name: "<module>", node: null };
    const k = enc.getKindName();
    if (k === "Constructor") {
      const cls = enc.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
      if (cls?.getName?.()) return { name: cls.getName(), node: cls };
    } else if (/ArrowFunction|FunctionExpression/.test(k)) {
      const p = enc.getParent();
      const pk = p?.getKind?.();
      // `const Foo = () => …` / `const Foo = function () {…}`
      if (pk === SyntaxKind.VariableDeclaration && p.getInitializer?.() === enc
        && p.getNameNode?.().getKind?.() === SyntaxKind.Identifier) return { name: p.getName(), node: p.getNameNode() };
      // `{ foo: () => … }`
      if (pk === SyntaxKind.PropertyAssignment && p.getName?.()) return { name: p.getName(), node: null };
      // named function expression: `foo(function bar() {…})`
      if (enc.getName?.()) return { name: enc.getName(), node: null };
    } else if (enc.getName?.()) {
      return { name: enc.getName(), node: enc };
    }
    cur = enc; // anonymous / unnamed — keep walking outward
  }
}
const enclosingName = (id, SyntaxKind) => enclosingOwner(id, SyntaxKind).name;

// Identity of the map a sidecar was derived from. ensureFresh() can return a map
// keyed three different ways (clean HEAD / dirty fingerprint / non-git source
// fingerprint); fold all of them plus the schema into one string so ANY drift
// yields a different key and a stale sidecar is simply ignored. Cheap and
// conservative on purpose: a false "stale" costs one live query, a false "fresh"
// would serve wrong answers.
function edgeKey(data) {
  return [
    SCHEMA_VERSION,
    `e${EDGES_FORMAT}`,
    data.generatedSha || "",
    data.dirtyFingerprint || "",
    data.fingerprint || "",
    data.dirty ?? "",
  ].join(":");
}

// Read the sidecar, or null when it is absent / unreadable / keyed to a different
// map. Never throws: every failure means "fall back to the live walk".
function readCallEdges(data) {
  if (!existsSync(EDGES)) return null;          // never built — the normal state
  let c;
  try { c = JSON.parse(readFileSync(EDGES, "utf8")); }
  catch {
    // Present but unreadable. Staleness is routine and stays quiet; a CORRUPT
    // cache is not, and answering correctly-but-20x-slower with no explanation is
    // the kind of silent degradation that never gets diagnosed. One line, stderr,
    // never fatal — the answer below is still the authoritative live walk.
    console.error(`# agentmap: ${EDGES} unreadable — using the live walk (rebuild with \`agentmap --build-edges\`)`);
    return null;
  }
  if (c.schema !== SCHEMA_VERSION || c.key !== edgeKey(data)) return null; // stale: expected, silent
  if (!Array.isArray(c.edges)) {
    console.error(`# agentmap: ${EDGES} malformed — using the live walk (rebuild with \`agentmap --build-edges\`)`);
    return null;
  }
  return c.edges;
}

// Sweep every in-project file once and record every resolvable call/JSX site.
//
// This is the SAME resolution primitive the live --callers query uses, run from
// the call-site side instead of per-symbol: "this site resolves to that
// declaration" and "that declaration's references include this site" describe the
// same edge, so one whole-repo pass yields what N per-symbol findReferences()
// walks would, minus the per-query cost. Expensive (getDefinitionNodes() per
// site) — which is exactly why it is a background/explicit step, never implicit.
function buildCallEdges() {
  const data = ensureFresh();
  const { SyntaxKind } = tsMorph();
  const { project, vueMap } = makeProject();
  const cwd = process.cwd().replace(/\\/g, "/");
  const rel = (p) => { const abs = p.replace(/\\/g, "/"); return (vueMap[abs] || abs).replace(cwd + "/", ""); };
  const inProject = (k) => Object.prototype.hasOwnProperty.call(data.files, k);
  // A declaration's own name is NOT always the name callers query by:
  // `export { impl as Widget }` binds the export to `Widget` while the node is
  // still named `impl`, and Phase A resolves the query through
  // getExportedDeclarations() — i.e. by the EXPORTED name. Keying edges on
  // d.getName() alone therefore made such a symbol look uncalled. Build the
  // inverse (declaration -> every name its own file exports it as) from the same
  // API Phase A trusts, memoised per file since the sweep revisits callee files
  // constantly.
  const aliasCache = new Map();
  const exportedNamesOf = (d, tsf) => {
    const key = tsf.getFilePath();
    let byNode = aliasCache.get(key);
    if (!byNode) {
      byNode = new Map();
      try {
        for (const [name, decls] of tsf.getExportedDeclarations()) {
          for (const dd of decls) {
            const at = `${dd.getStartLineNumber?.() ?? 0}:${dd.getKindName?.() ?? ""}`;
            if (!byNode.has(at)) byNode.set(at, new Set());
            byNode.get(at).add(name);
          }
        }
      } catch { /* unreadable exports — fall back to the declaration's own name */ }
      aliasCache.set(key, byNode);
    }
    const names = new Set();
    const own = d.getName?.();
    if (own) names.add(own);
    for (const n of byNode.get(`${d.getStartLineNumber?.() ?? 0}:${d.getKindName?.() ?? ""}`) ?? []) names.add(n);
    return names;
  };
  const edges = [];
  let sites = 0;
  for (const sf of project.getSourceFiles()) {
    const fp = sf.getFilePath().replace(/\\/g, "/");
    if (fp.includes("/node_modules/") || fp.includes("/.next/")) continue;
    const callerFile = rel(fp);
    if (!inProject(callerFile)) continue;
    for (const site of [
      ...sf.getDescendantsOfKind(SyntaxKind.CallExpression),
      ...sf.getDescendantsOfKind(SyntaxKind.NewExpression),
      ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
      ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
    ]) {
      sites++;
      const k = site.getKind();
      const isJsx = k === SyntaxKind.JsxSelfClosingElement || k === SyntaxKind.JsxOpeningElement;
      const callee = isJsx ? site.getTagNameNode() : site.getExpression();
      // Same shapes invocationOf() accepts: a bare identifier, or the name half of
      // a dotted access (`ns.foo()` and `<UI.Widget />` alike — TypeScript models
      // both as PropertyAccessExpression).
      let idNode = null;
      if (callee.getKind() === SyntaxKind.Identifier) idNode = callee;
      else if (callee.getKind() === SyntaxKind.PropertyAccessExpression) idNode = callee.getNameNode();
      if (!idNode) continue; // computed / parenthesized / dynamic — the same honest limit --calls has
      let targets;
      try { targets = idNode.getDefinitionNodes?.() || []; } catch { continue; }
      // `const wrapped = helper; wrapped()` — go-to-definition helpfully walks
      // THROUGH the trivial reassignment and returns BOTH the local `wrapped`
      // binding and `helper` itself. Emitting every target made `helper` look
      // called from a site that never names it, which the live reference walk
      // rightly does not report (the reference there is `wrapped`, not `helper`).
      // A local value binding is where resolution stops: keep only it.
      const rebind = targets.find((d) => {
        const k = d.getKindName?.();
        return (k === "VariableDeclaration" || k === "BindingElement" || k === "Parameter")
          && d.getSourceFile().getFilePath() === sf.getFilePath();
      });
      const resolved = rebind ? [rebind] : targets;
      const callerLine = idNode.getStartLineNumber();
      // Keep the owner NODE too, not just its name: the transitive walk's `via`
      // key is `file:caller:declLine`, and declLine is the enclosing symbol's own
      // declaration line — not the call-site line.
      const owner = enclosingOwner(idNode, SyntaxKind);
      const callerName = owner.name;
      const callerDeclLine = owner.node?.getStartLineNumber?.() ?? callerLine;
      for (const d of resolved) {
        const tsf = d.getSourceFile();
        if (tsf.isInNodeModules() || tsf.isDeclarationFile()) continue;
        const calleeFile = rel(tsf.getFilePath().replace(/\\/g, "/"));
        if (!inProject(calleeFile)) continue;
        // The callee's OWN declaration line/kind — what --calls prints for each
        // outgoing row, and what lets the transitive walk rejoin an edge's head
        // to the next hop's tail.
        const calleeLine = d.getStartLineNumber?.() ?? 0;
        const calleeKind = d.getKindName?.() ?? "";
        for (const calleeName of exportedNamesOf(d, tsf)) {
          edges.push({ callerFile, callerLine, callerName, callerDeclLine, calleeFile, calleeName, calleeLine, calleeKind, kind: isJsx ? "jsx" : "call" });
        }
      }
    }
  }
  mkdirSync(".claude/agentmap", { recursive: true });
  const tmp = `${EDGES}.${process.pid}.tmp`; // PID-suffixed for the same reason assemble() is
  writeFileSync(tmp, JSON.stringify({ schema: SCHEMA_VERSION, key: edgeKey(data), edges }));
  renameSync(tmp, EDGES);
  return { files: Object.keys(data.files).length, sites, edges: edges.length };
}

function callGraph(symbolName, { inFilter = "", direction = "callers", depth = 1 } = {}) {
  // --depth N (default 1) makes the query TRANSITIVE. depth 1 is byte-identical to
  // the single-hop path below (guarded `if (maxDepth > 1)`); depth ≥2 runs a capped
  // BFS over the SAME warm Project (no extra build, still lazy).
  const maxDepth = Math.min(Math.max(1, Math.trunc(Number(depth)) || 1), DEPTH_CAP);
  const data = ensureFresh();
  // Phase A — NAME → defining file(s), from the cached map. EXACT name (not the
  // substring match --find uses): a call graph must bind to one symbol precisely.
  // A file that only RE-EXPORTS the name (barrel) is not a definer — exclude it
  // via f.reExports so a re-exported symbol doesn't read as "ambiguous".
  // Separate EXPORTED definitions from same-named private locals. A file that only
  // RE-EXPORTS the name (barrel) is not a definer (f.reExports). Exported/shared
  // definitions take PRECEDENCE: a same-named private local in ANOTHER file is a
  // DIFFERENT symbol and must NOT make an exported symbol read as "ambiguous"
  // (private names like parse/format/handler collide constantly). --in narrows
  // across BOTH pools so a private local stays reachable when you name its file.
  const exportOwners = [];
  const localOwners = [];
  for (const [path, f] of Object.entries(data.files)) {
    // `definedIn`/`external` is the precise per-symbol answer to "does this file
    // actually declare the name": the checker resolved it. `reExports` is the
    // older, name-list approximation built from NAMED specifiers only, so it
    // cannot see `export * from` — one star barrel used to be scored as a rival
    // definition and made this whole query fail with error:"ambiguous". Keep it as
    // the fallback so nothing regresses where the newer field is absent, but do
    // NOT widen `reExports` itself: rankSymbols reads it to discount pass-through
    // names, and broadening it there would quietly move symbol ranking.
    const own = f.exports.find((e) => e.name === symbolName);
    const reExported = own
      ? (!!own.definedIn || !!own.external || (f.reExports || []).includes(symbolName))
      : false;
    if (own && !reExported) exportOwners.push(path);
    else if ((f.locals || []).some((e) => e.name === symbolName)) localOwners.push(path);
  }
  const owners = inFilter
    ? [...exportOwners, ...localOwners].filter((p) => p.includes(inFilter))
    : (exportOwners.length ? exportOwners : localOwners);
  if (!owners.length) return { command: direction, query: symbolName, error: "no match", candidates: [], _code: 1 };
  if (owners.length > 1) return { command: direction, query: symbolName, error: "ambiguous", candidates: owners, _code: 1 };
  const fileKey = owners[0];
  // Phase B FAST PATH — answer from the prebuilt call-edge sidecar when one exists
  // for exactly this map. Skips tsMorph() + makeProject() + the checker's
  // full-program bind entirely (~1.5s -> ~35ms measured on a 250-400 file repo).
  // Deliberately narrow: single-hop --callers only. --calls has a different output
  // shape and --depth >= 2 needs findReferences-able NODES to recurse on, which a
  // JSON row cannot carry; both keep the live walk. A missing/stale sidecar just
  // falls through, so this can only ever be faster, never wrong.
  {
    const cached = readCallEdges(data);
    if (cached && direction === "callers" && maxDepth === 1) {
      const seen = new Set();
      const sites = [];
      for (const e of cached) {
        if (e.calleeFile !== fileKey || e.calleeName !== symbolName) continue;
        const dedupe = `${e.callerFile}:${e.callerLine}`; // same key the live walk dedupes on
        if (seen.has(dedupe)) continue;
        seen.add(dedupe);
        sites.push({ file: e.callerFile, line: e.callerLine, caller: e.callerName });
      }
      sites.sort((x, y) =>
        ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
        || (x.file < y.file ? -1 : x.file > y.file ? 1 : x.line - y.line));
      const shown = sites.slice(0, SYMBOL_MATCH_LIMIT);
      return {
        command: "callers", query: symbolName, symbol: symbolName, file: fileKey,
        total: sites.length, shown: shown.length, truncated: sites.length > shown.length,
        callers: shown, _code: sites.length ? 0 : 1,
      };
    }
    // OUTGOING from cache: the same table read from the other end. An edge's tail
    // is (callerFile, callerName) — the enclosing named owner of the call site —
    // so "what does X call" is just the rows whose tail is X.
    if (cached && direction === "calls" && maxDepth === 1) {
      const seen = new Set();
      const targets = [];
      for (const e of cached) {
        if (e.callerFile !== fileKey || e.callerName !== symbolName) continue;
        if (e.calleeFile === fileKey && e.calleeName === symbolName) continue; // self-recursion isn't an outgoing edge
        const dedupe = `${e.calleeFile}:${e.calleeLine}:${e.calleeName}`;
        if (seen.has(dedupe)) continue;
        seen.add(dedupe);
        targets.push({ file: e.calleeFile, line: e.calleeLine, name: e.calleeName, kind: e.calleeKind });
      }
      // Outgoing rows tie-break by callee NAME, not line — matching the live walk.
      // (Incoming rows tie-break by line, because there the line IS the call site;
      // here it is the callee's declaration line, which carries no ordering
      // meaning to a reader scanning "what does this call".)
      targets.sort((x, y) =>
        ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
        || (x.file < y.file ? -1 : x.file > y.file ? 1 : (x.name < y.name ? -1 : x.name > y.name ? 1 : 0)));
      const shown = targets.slice(0, SYMBOL_MATCH_LIMIT);
      return {
        command: "calls", query: symbolName, symbol: symbolName, file: fileKey,
        total: targets.length, shown: shown.length, truncated: targets.length > shown.length,
        calls: shown, _code: targets.length ? 0 : 1,
      };
    }
    // TRANSITIVE from cache. The live walk recurses on findReferences-able NODES;
    // here the equivalent is rejoining an edge's tail (callerFile, callerName) to
    // the next hop's head (calleeFile, calleeName). Rows dedup by call SITE,
    // expansion dedups by enclosing SYMBOL — the same two-concern split, and the
    // same frontier/total caps, so a hub cannot blow the result open.
    if (cached && direction === "callers" && maxDepth > 1) {
      const byCallee = new Map();
      for (const e of cached) {
        const k = `${e.calleeFile}\x00${e.calleeName}`;
        (byCallee.get(k) ?? byCallee.set(k, []).get(k)).push(e);
      }
      const seenSite = new Set();
      const visitedSym = new Set([`${fileKey}\x00${symbolName}`]);
      const out = [];
      let frontier = [{ file: fileKey, name: symbolName, key: null }];
      let hop = 0, capped = false;
      while (frontier.length && hop < maxDepth && !capped) {
        hop++;
        const next = [];
        for (const fr of frontier) {
          for (const e of byCallee.get(`${fr.file}\x00${fr.name}`) ?? []) {
            const siteKey = `${e.callerFile}:${e.callerLine}`;
            if (seenSite.has(siteKey)) continue;
            seenSite.add(siteKey);
            out.push({ file: e.callerFile, line: e.callerLine, caller: e.callerName, depth: hop, via: fr.key });
            if (out.length >= CLOSURE_TOTAL_CAP) { capped = true; break; }
            if (e.callerName === "<module>") continue;   // module scope has no symbol to recurse on
            // TWO different keys, deliberately. The dedup key is internal cycle-
            // guard identity — (file, name), NUL-separated so a path can never
            // forge a collision. `via` is user-visible and must reproduce the live
            // walk byte-for-byte, which spells it file:caller:DECLARATION-line —
            // the enclosing symbol's own line, not the call-site line.
            const dedupK = `${e.callerFile}\x00${e.callerName}`;
            if (!visitedSym.has(dedupK)) {
              visitedSym.add(dedupK);
              next.push({
                file: e.callerFile, name: e.callerName,
                key: `${e.callerFile}:${e.callerName}:${e.callerDeclLine ?? e.callerLine}`,
                pr: data.files[e.callerFile]?.pagerank ?? 0,
              });
            }
          }
          if (capped) break;
        }
        next.sort((a, b) => b.pr - a.pr);
        frontier = next.slice(0, CLOSURE_FRONTIER_CAP);
      }
      out.sort((x, y) => (x.depth - y.depth)
        || ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
        || (x.file < y.file ? -1 : x.file > y.file ? 1 : x.line - y.line));
      return {
        command: "callers", query: symbolName, symbol: symbolName, file: fileKey, depth: maxDepth,
        total: out.length, shown: out.length, truncated: capped, callers: out, _code: out.length ? 0 : 1,
      };
    }
  }
  // Phase B — LAZY full Project (inc=null ⇒ language service live; NEVER the
  // incremental branch, which loads other files as empty stubs and would hide
  // cross-file callers). tsMorph() is the ~105ms init, fired only here.
  const { SyntaxKind } = tsMorph();
  const { project, vueMap } = makeProject();
  const cwd = process.cwd().replace(/\\/g, "/");
  const rel = (p) => { const abs = p.replace(/\\/g, "/"); return (vueMap[abs] || abs).replace(cwd + "/", ""); };
  const sf = project.getSourceFile(`${cwd}/${fileKey}`);
  if (!sf) return { command: direction, query: symbolName, symbol: symbolName, file: fileKey, error: "degraded", reason: "source not in project", total: 0, shown: 0, truncated: false, callers: [], calls: [], _code: 1 };
  // Relocate the declaration node(s). Exported: getExportedDeclarations() (the
  // same API that built f.exports) — get() returns an ARRAY (overloads/merged), so
  // union references across all. Non-exported: mirror the f.locals top-level getters.
  let decls = sf.getExportedDeclarations().get(symbolName) || [];
  if (!decls.length) {
    const top = [
      ...sf.getFunctions(), ...sf.getClasses(), ...sf.getInterfaces(),
      ...sf.getTypeAliases(), ...sf.getEnums(),
      ...sf.getVariableStatements().flatMap((v) => v.getDeclarations()),
    ];
    decls = top.filter((d) => d.getName?.() === symbolName);
  }
  if (!decls.length) return { command: direction, query: symbolName, symbol: symbolName, file: fileKey, error: "degraded", reason: "declaration not locatable", total: 0, shown: 0, truncated: false, callers: [], calls: [], _code: 1 };
  // OUTGOING (--calls): walk the resolved declaration's OWN body for call/construct
  // sites, then resolve each callee to its target declaration via the TS language
  // service. getDefinitionNodes() is "go to definition" — it follows an imported
  // binding THROUGH to the real in-project declaration (getSymbol() would stop at
  // the ImportSpecifier in the caller file). Keep only in-project targets; a
  // computed member (`map[k]()`), higher-order param (`cb()`), or otherwise
  // statically-unresolvable callee is skipped — the honest dynamic-dispatch limit.
  if (direction === "calls") {
    if (maxDepth > 1) {
      // Transitive OUTGOING BFS: each resolved target is itself a declaration node
      // (getDefinitionNodes) whose body we re-walk one hop deeper. `visited` (target
      // identity) is both the row-dedup and the cycle guard — a symbol reached once
      // is never re-expanded, so mutual/self recursion terminates; shallowest depth
      // wins (BFS). Frontier + total caps bound a hub's combinatorial blowup.
      const idOf = (d) => `${rel(d.getSourceFile().getFilePath().replace(/\\/g, "/"))}:${d.getName?.() ?? symbolName}:${d.getStartLineNumber?.() ?? 0}`;
      const visited = new Set(decls.map(idOf));
      const out = [];
      let frontier = decls.map((d) => ({ node: d, key: null }));
      let hop = 0, capped = false;
      while (frontier.length && hop < maxDepth && !capped) {
        hop++;
        const next = [];
        for (const fr of frontier) {
          const callSites = [
            ...fr.node.getDescendantsOfKind(SyntaxKind.CallExpression),
            ...fr.node.getDescendantsOfKind(SyntaxKind.NewExpression),
          ];
          for (const site of callSites) {
            const callee = site.getExpression();
            let idNode = null;
            if (callee.getKind() === SyntaxKind.Identifier) idNode = callee;
            else if (callee.getKind() === SyntaxKind.PropertyAccessExpression) idNode = callee.getNameNode();
            if (!idNode) continue;
            let targets;
            try { targets = idNode.getDefinitionNodes?.() || []; } catch { continue; }
            for (const d of targets) {
              const tsf = d.getSourceFile();
              if (tsf.isInNodeModules() || tsf.isDeclarationFile()) continue;
              const relKey = rel(tsf.getFilePath().replace(/\\/g, "/"));
              if (!data.files[relKey]) continue;
              const kind = d.getKindName();
              if (/^(Parameter|BindingElement)$/.test(kind)) continue;
              const name = d.getName?.() ?? d.getSymbol()?.getName?.() ?? "?";
              const line = d.getStartLineNumber?.() ?? 0;
              const idKey = `${relKey}:${name}:${line}`;
              if (visited.has(idKey)) continue;
              visited.add(idKey);
              out.push({ file: relKey, line, name, kind, depth: hop, via: fr.key });
              if (out.length >= CLOSURE_TOTAL_CAP) { capped = true; break; }
              next.push({ node: d, key: idKey, pr: data.files[relKey]?.pagerank ?? 0 });
            }
            if (capped) break;
          }
          if (capped) break;
        }
        next.sort((a, b) => b.pr - a.pr);
        frontier = next.slice(0, CLOSURE_FRONTIER_CAP);
      }
      out.sort((x, y) => (x.depth - y.depth)
        || ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
        || (x.file < y.file ? -1 : x.file > y.file ? 1 : (x.name < y.name ? -1 : x.name > y.name ? 1 : 0)));
      return {
        command: "calls", query: symbolName, symbol: symbolName, file: fileKey, depth: maxDepth,
        total: out.length, shown: out.length, truncated: capped, calls: out, _code: out.length ? 0 : 1,
      };
    }
    const seenCall = new Set();
    const out = [];
    for (const decl of decls) {
      const callSites = [
        ...decl.getDescendantsOfKind(SyntaxKind.CallExpression),
        ...decl.getDescendantsOfKind(SyntaxKind.NewExpression),
        // JSX elements are invocations too (see invocationOf). Without these, a
        // component that only renders children reported ZERO outgoing calls —
        // the mirror of the --callers JSX gap, in a separate code path.
        // JsxOpeningElement only: the closing tag of `<Foo>…</Foo>` is the same
        // call site, and collecting both would double-count it.
        ...decl.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
        ...decl.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
      ];
      for (const site of callSites) {
        const siteKind = site.getKind();
        const isJsx = siteKind === SyntaxKind.JsxSelfClosingElement || siteKind === SyntaxKind.JsxOpeningElement;
        const callee = isJsx ? site.getTagNameNode() : site.getExpression();
        let idNode = null;
        if (callee.getKind() === SyntaxKind.Identifier) idNode = callee;
        else if (callee.getKind() === SyntaxKind.PropertyAccessExpression) idNode = callee.getNameNode();
        // `<Foo.Bar />` — the component is Bar, not the Foo namespace.
        else if (callee.getKind() === SyntaxKind.JsxMemberExpression) idNode = callee.getNameNode();
        if (!idNode) continue; // computed / parenthesized / dynamic — unresolvable
        // Intrinsic tags (`<div>`) need no special case: they resolve into lib
        // .d.ts and are dropped by the isDeclarationFile() gate below.
        let targets;
        try { targets = idNode.getDefinitionNodes?.() || []; } catch { continue; }
        for (const d of targets) {
          const tsf = d.getSourceFile();
          if (tsf.isInNodeModules() || tsf.isDeclarationFile()) continue; // dep pkgs + TS builtins
          const relKey = rel(tsf.getFilePath().replace(/\\/g, "/"));
          if (!data.files[relKey]) continue; // authoritative in-project gate (same set --map/--relates trust)
          const kind = d.getKindName();
          if (/^(Parameter|BindingElement)$/.test(kind)) continue; // higher-order binding — statically unknowable
          const name = d.getName?.() ?? d.getSymbol()?.getName?.() ?? "?";
          const line = d.getStartLineNumber?.() ?? 0;
          const key = `${relKey}:${name}:${line}`;
          if (seenCall.has(key)) continue;
          seenCall.add(key);
          out.push({ file: relKey, line, name, kind });
        }
      }
    }
    out.sort((x, y) =>
      ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
      || (x.file < y.file ? -1 : x.file > y.file ? 1 : (x.name < y.name ? -1 : x.name > y.name ? 1 : 0)));
    const shownCalls = out.slice(0, SYMBOL_MATCH_LIMIT);
    return {
      command: "calls", query: symbolName, symbol: symbolName, file: fileKey,
      total: out.length, shown: shownCalls.length, truncated: out.length > shownCalls.length,
      calls: shownCalls, _code: out.length ? 0 : 1,
    };
  }
  // Keep ONLY true call sites — see invocationOf(): a CallExpression whose callee
  // is this identifier (two-hop for `ns.foo()`), or a JSX element whose tag name it
  // is. This is the compiler-accuracy line — a type-position mention, a re-export, a
  // bare value reference, or a same-named local in another file binds to a DIFFERENT
  // symbol and never reaches here.
  // Shared with the sidecar sweep — see enclosingOwner() at module scope.
  const enclosing = (id) => enclosingOwner(id, SyntaxKind);
  if (maxDepth > 1) {
    // Transitive INCOMING BFS: to recurse UP one hop we need a findReferences-able
    // node for the ENCLOSING symbol of each call site — that is `enclosing().node`
    // above. Rows dedup by call SITE; expansion dedups by enclosing SYMBOL (the
    // cycle guard) — two separate concerns. Frontier + total caps bound hubs.
    const seedKey = (d) => `${rel(d.getSourceFile().getFilePath().replace(/\\/g, "/"))}:${d.getName?.() ?? symbolName}:${d.getStartLineNumber?.() ?? 0}`;
    const visitedSym = new Set(decls.map(seedKey)); // enclosing-symbol expansion dedup (cycle guard)
    const seenSite = new Set();                     // global row dedup by call site
    const out = [];
    let frontier = decls.map((d) => ({ node: d, key: null }));
    let hop = 0, capped = false;
    while (frontier.length && hop < maxDepth && !capped) {
      hop++;
      const next = [];
      for (const fr of frontier) {
        let refs;
        try { refs = fr.node.findReferencesAsNodes(); } catch { continue; }
        for (const id of refs) {
          if (!invocationOf(id, SyntaxKind)) continue;
          const file = rel(id.getSourceFile().getFilePath());
          const line = id.getStartLineNumber();
          const siteKey = `${file}:${line}`;
          if (seenSite.has(siteKey)) continue;
          seenSite.add(siteKey);
          const { name: caller, node: recurseNode } = enclosing(id);
          out.push({ file, line, caller, depth: hop, via: fr.key });
          if (out.length >= CLOSURE_TOTAL_CAP) { capped = true; break; }
          if (recurseNode) {
            const symKey = `${file}:${caller}:${recurseNode.getStartLineNumber?.() ?? line}`;
            if (!visitedSym.has(symKey)) { visitedSym.add(symKey); next.push({ node: recurseNode, key: symKey, pr: data.files[file]?.pagerank ?? 0 }); }
          }
        }
        if (capped) break;
      }
      next.sort((a, b) => b.pr - a.pr);
      frontier = next.slice(0, CLOSURE_FRONTIER_CAP);
    }
    out.sort((x, y) => (x.depth - y.depth)
      || ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
      || (x.file < y.file ? -1 : x.file > y.file ? 1 : x.line - y.line));
    return {
      command: "callers", query: symbolName, symbol: symbolName, file: fileKey, depth: maxDepth,
      total: out.length, shown: out.length, truncated: capped, callers: out, _code: out.length ? 0 : 1,
    };
  }
  const seen = new Set();
  const sites = [];
  for (const decl of decls) {
    let refs;
    try { refs = decl.findReferencesAsNodes(); } catch { continue; }
    for (const id of refs) {
      if (!invocationOf(id, SyntaxKind)) continue;
      const file = rel(id.getSourceFile().getFilePath());
      const line = id.getStartLineNumber();
      const dedupe = `${file}:${line}`;
      if (seen.has(dedupe)) continue;
      seen.add(dedupe);
      sites.push({ file, line, caller: enclosing(id).name });
    }
  }
  // Rank by the CALLING file's PageRank so important callers survive the cap (same
  // instinct as --find), tie-broken by file then line for stable output.
  sites.sort((x, y) =>
    ((data.files[y.file]?.pagerank ?? 0) - (data.files[x.file]?.pagerank ?? 0))
    || (x.file < y.file ? -1 : x.file > y.file ? 1 : x.line - y.line));
  const shown = sites.slice(0, SYMBOL_MATCH_LIMIT);
  return {
    command: "callers", query: symbolName, symbol: symbolName, file: fileKey,
    total: sites.length, shown: shown.length, truncated: sites.length > shown.length,
    callers: shown, _code: sites.length ? 0 : 1,
  };
}

function mcpQuery(name, args) {
  const a = args && typeof args === "object" ? args : {};
  const err = (code, stderr) => ({ code, obj: null, stderr });
  const ok = (obj, code = 0) => ({ code, obj, stderr: "" });
  switch (name) {
    case "any": {
      const raw = String(a.query ?? "");
      if (!raw) return err(2, '--any needs a query, e.g. `--any PremiumCard` or `--any "multi-modal"`');
      const q = raw.toLowerCase();
      const data = mcpEnsureFresh();
      const keys = Object.keys(data.files);
      const { key: fileKey, candidates } = resolveFile(keys, data.files, raw);
      const symAll = [];
      for (const [path, f] of Object.entries(data.files)) {
        for (const e of f.exports)
          if (e.name.toLowerCase().includes(q)) symAll.push(symMatch(path, e));
        if (INCLUDE_LOCALS) for (const e of (f.locals || []))
          if (e.name.toLowerCase().includes(q)) symAll.push({ file: path, name: e.name, kind: e.kind, local: true });
      }
      const symTotal = symAll.length;
      const symObjs = rankMatches(data.files, symAll).slice(0, SYMBOL_MATCH_LIMIT);
      const symTrunc = symTotal > symObjs.length;
      const featNames = Object.keys(data.features || {}).filter((k) => k.toLowerCase().includes(q));
      if (fileKey) {
        const f = data.files[fileKey];
        return ok({ command: "any", query: raw, kind: "file", file: fileKey, pagerank: f.pagerank ?? null, exports: f.exports, imports: f.imports, dependents: f.dependents, ...typeOnlyOut(f), symbols: symObjs, symbolsTotal: symTotal, symbolsTruncated: symTrunc, features: featNames.map((n) => ({ name: n, count: data.features[n].length })) });
      } else if (symObjs.length || featNames.length) {
        return ok({ command: "any", query: raw, kind: "structure", symbols: symObjs, symbolsTotal: symTotal, symbolsTruncated: symTrunc, features: featNames.map((n) => ({ name: n, count: data.features[n].length })) });
      } else if (candidates && candidates.length > 1) {
        return ok({ command: "any", query: raw, kind: "candidates", candidates });
      } else {
        const lex = bm25Search(data.lexical, data.files, raw);
        if (lex.matches.length) return ok({ command: "any", query: raw, kind: "lexical", matches: lex.matches, total: lex.total, shown: lex.matches.length, truncated: lex.total > lex.matches.length });
        const res = contentSearch(raw);
        if (!res) return ok({ command: "any", query: raw, kind: "empty" }, 1);
        const lines = res.split("\n");
        const shown = lines.slice(0, CONTENT_LINES_LIMIT);
        return ok({ command: "any", query: raw, kind: "content", total: lines.length, lines: shown });
      }
    }
    case "search": {
      const raw = String(a.query ?? "");
      if (!raw) return err(2, 'search needs a query, e.g. `{ query: "auth retry logic" }`');
      const data = mcpEnsureFresh();
      // Same loose, case-insensitive kind match the CLI's --kind applies, so the
      // two surfaces cannot answer the same narrowed query differently.
      const mk = String(a.kind ?? "").toLowerCase();
      const keep = (k) => !mk || String(k || "").toLowerCase().includes(mk);
      const lex = bm25Search(data.lexical, data.files, raw);
      const matches = mk ? lex.matches.filter((m) => keep(m.kind)) : lex.matches;
      return ok({ command: "search", query: raw, ...(mk ? { kind: a.kind } : {}), total: mk ? matches.length : lex.total, shown: matches.length, truncated: !mk && lex.total > matches.length, matches }, matches.length ? 0 : 1);
    }
    case "find": {
      const raw = String(a.symbol ?? "");
      if (!raw) return err(2, "--find needs a symbol query, e.g. `--find PremiumCard`");
      const q = raw.toLowerCase();
      const mk = String(a.kind ?? "").toLowerCase();
      const keep = (k) => !mk || String(k || "").toLowerCase().includes(mk);
      const data = mcpEnsureFresh();
      const all = [];
      for (const [path, f] of Object.entries(data.files)) {
        for (const e of f.exports)
          if (e.name.toLowerCase().includes(q) && keep(e.kind)) all.push(symMatch(path, e));
        if (INCLUDE_LOCALS) for (const e of (f.locals || []))
          if (e.name.toLowerCase().includes(q) && keep(e.kind)) all.push({ file: path, name: e.name, kind: e.kind, local: true });
      }
      const code = all.length ? 0 : 1;
      const ranked = rankMatches(data.files, all);
      const matches = ranked.slice(0, SYMBOL_MATCH_LIMIT);
      const truncated = ranked.length > matches.length;
      return ok({ command: "find", query: raw, total: ranked.length, shown: matches.length, truncated, matches }, code);
    }
    case "relates": {
      const q = String(a.path ?? "");
      if (!q) return err(2, "--relates needs a file path/name, e.g. `--relates agentmap.mjs`");
      const data = mcpEnsureFresh();
      const keys = Object.keys(data.files);
      const { key, candidates } = resolveFile(keys, data.files, q);
      if (!key) return ok({ command: "relates", error: "no match", query: q, candidates: candidates || [] }, 1);
      const f = data.files[key];
      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((x, y) => y[1] - x[1]).slice(0, RELATED_LIMIT);
      return ok({ command: "relates", file: key, ...(f.rsc ? { rsc: f.rsc } : {}), pagerank: f.pagerank ?? null, exports: f.exports, imports: f.imports, dependents: f.dependents, ...typeOnlyOut(f), related: top.map(([file, score]) => ({ file, score: +score.toFixed(6) })) });
    }
    case "callers": {
      const raw = String(a.symbol ?? "");
      if (!raw) return err(2, "callers needs a symbol, e.g. `{ symbol: \"extractFacts\" }`");
      const r = callGraph(raw, { inFilter: String(a.in ?? ""), depth: Number(a.depth ?? 1) });
      const { _code = 0, ...obj } = r;
      return ok(obj, _code);
    }
    case "calls": {
      const raw = String(a.symbol ?? "");
      if (!raw) return err(2, "calls needs a symbol, e.g. `{ symbol: \"extractFacts\" }`");
      const r = callGraph(raw, { inFilter: String(a.in ?? ""), direction: "calls", depth: Number(a.depth ?? 1) });
      const { _code = 0, ...obj } = r;
      return ok(obj, _code);
    }
    case "map": {
      const focusArg = (a.focus != null && String(a.focus) !== "") ? String(a.focus) : undefined;
      const data = mcpEnsureFresh();
      const tkRaw = (a.tokens != null && Number.isFinite(Number(a.tokens))) ? String(Math.trunc(Number(a.tokens))) : "";
      const tk = parseInt(tkRaw, 10);
      const budget = Number.isFinite(tk) && tk > 0 ? tk : (focusArg ? FOCUS_BUDGET : DEFAULT_BUDGET);
      let ranked = data.rankedSymbols || [];
      let focusLabel = "global";
      let focusResolved;
      let code = 0;
      if (focusArg) {
        const { key } = resolveFile(Object.keys(data.files), data.files, focusArg);
        if (key) { ranked = rankSymbols(data.files, new Set([key])); focusLabel = key; focusResolved = true; }
        else { focusResolved = false; code = 1; }
      }
      if (!ranked.length)
        ranked = Object.entries(data.files)
          .sort((x, y) => (y[1].pagerank || 0) - (x[1].pagerank || 0))
          .flatMap(([file, f]) => (f.exports || []).map((e) => ({ file, name: e.name, kind: e.kind, rank: f.pagerank || 0 })));
      let used = 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); }
      const shownFiles = [];
      let first = true;
      for (const [file, syms] of byFile) {
        const capped = syms.slice(0, SYMS_PER_FILE);
        const lineOf = (arr) => `\n${file}:\n` + arr.map((s) => `  ${s.name} (${s.kind})`).join("\n");
        const t = tokEst(lineOf(capped));
        if (used + t > budget) {
          if (first && budget > 0) {
            for (let k = capped.length - 1; k >= 1; k--) {
              const partial = capped.slice(0, k);
              const pt = tokEst(lineOf(partial));
              if (used + pt <= budget) { used += pt; shownFiles.push({ file, symbols: partial.map((s) => ({ name: s.name, kind: s.kind })) }); break; }
            }
            first = false;
          }
          continue;
        }
        used += t; first = false;
        shownFiles.push({ file, symbols: capped.map((s) => ({ name: s.name, kind: s.kind })) });
      }
      return ok({ command: "map", focus: focusLabel, ...(focusResolved !== undefined ? { focusResolved } : {}), budget, tokens: used, files: shownFiles }, code);
    }
    case "hubs": {
      const data = mcpEnsureFresh();
      return ok({ command: "hubs", fileCount: data.fileCount, sha: data.generatedSha, hubs: data.hubs });
    }
    case "features": {
      const data = mcpEnsureFresh();
      const list = Object.entries(data.features).map(([k, v]) => [k, v.length]).sort((x, y) => y[1] - x[1]);
      // Mirrors the CLI: say "not applicable", never an empty result that reads
      // as a finding. This surface matters more than the CLI's — the caller is
      // always a model.
      if (!list.length) return ok({ command: "features", features: {}, reason: NOT_APP_ROUTER }, 1);
      return ok({ command: "features", features: Object.fromEntries(list) });
    }
    case "feature": {
      const raw = String(a.name ?? "");
      if (!raw) return err(2, "--feature needs a name, e.g. `--feature dashboard` (run --features to list)");
      const q = raw.toLowerCase();
      const data = mcpEnsureFresh();
      if (!Object.keys(data.features).length) return ok({ command: "feature", query: raw, error: "not applicable", reason: NOT_APP_ROUTER }, 1);
      const nm = Object.keys(data.features).find((k) => k.toLowerCase() === q) || Object.keys(data.features).find((k) => k.toLowerCase().includes(q));
      if (!nm) return ok({ command: "feature", error: "no match", query: raw }, 1);
      const fl = data.features[nm], 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);
      return ok({ command: "feature", name: nm, files: fl, externalDependents: [...exts] });
    }
    case "symbols": {
      const data = mcpEnsureFresh();
      const snRaw = (a.n != null && Number.isFinite(Number(a.n))) ? String(Math.trunc(Number(a.n))) : "";
      const sn = parseInt(snRaw, 10); const n = Number.isFinite(sn) && sn > 0 ? sn : DEFAULT_SYMBOLS;
      const syms = rankedSymbolsFor(data, n);
      return ok({ command: "symbols", requested: n, shown: syms.length, truncated: syms.length < n, symbols: syms.map((s) => ({ rank: s.rank, file: s.file, name: s.name, kind: s.kind })) });
    }
    // --affected / --routes / --route shipped in 0.19.0-0.20.0 as CLI-only, which
    // meant the three most agent-shaped queries this tool has ("what tests cover
    // this", "what serves this URL") were unreachable from the surface every agent
    // integration actually routes through. Payloads are byte-identical to the CLI.
    case "affected": {
      const raw = String(a.path ?? "");
      if (!raw) return err(2, "the 'affected' tool needs a path, e.g. { path: 'lib/auth.ts' }");
      const data = mcpEnsureFresh();
      const exact = data.files[raw] ? [raw] : Object.keys(data.files).filter((p) => p === raw || p.endsWith(`/${raw}`));
      if (!exact.length) return ok({ command: "affected", query: raw, error: "no match", candidates: [] }, 1);
      if (exact.length > 1) return ok({ command: "affected", query: raw, error: "ambiguous", candidates: exact }, 1);
      const file = exact[0];
      const reach = transitiveDependents(data, file);
      const tests = [...reach].filter(([p]) => TEST_FILE_RE.test(p))
        .sort((x, y) => x[1] - y[1] || (x[0] < y[0] ? -1 : 1))
        .map(([p, hop]) => ({ file: p, hop }));
      return ok({
        command: "affected", query: raw, file,
        dependents: reach.size, tests: tests.length,
        covered: tests.length > 0 || TEST_FILE_RE.test(file),
        affected: tests,
      });
    }
    case "routes": {
      const data = mcpEnsureFresh();
      const routes = buildRouteTable(data);
      if (!routes) return ok({ command: "routes", routes: [], reason: NOT_APP_ROUTER }, 1);
      return ok({ command: "routes", total: routes.length, routes });
    }
    case "route": {
      const raw = String(a.path ?? "");
      if (!raw) return err(2, "the 'route' tool needs a URL path, e.g. { path: '/dashboard' }");
      const data = mcpEnsureFresh();
      const routes = buildRouteTable(data);
      if (!routes) return ok({ command: "route", query: raw, matches: [], reason: NOT_APP_ROUTER }, 1);
      const hits = matchRoute(routes, raw);
      if (!hits.length) return ok({ command: "route", query: raw, matches: [] }, 1);
      const enriched = hits.map((r) => {
        const f = data.files[r.file] || {};
        return { ...r, imports: f.imports || [], serverModules: (f.imports || []).filter((i) => data.files[i]?.rsc === "server") };
      });
      return ok({ command: "route", query: raw, total: enriched.length, matches: enriched });
    }
    default:
      return err(2, `unknown tool: ${name}`);
  }
}

// ---------------------------------------------------------------------------
// Programmatic API. Importing agentmap.mjs executes NOTHING (see the guard
// below), so these pure building blocks can be used in-process by the MCP
// server, tests, and any future library caller without spawning a subprocess.
// ---------------------------------------------------------------------------
// SCHEMA_VERSION and CODE_EXT are exported for the test suite: a test that
// hardcodes either one is just another copy that can drift out of sync — which is
// exactly the failure both constants exist to prevent.
export { pagerank, rankSymbols, identMul, resolveFile, extractVueScripts, stripJsonComments, extractFacts, build, ensureFresh, readPackageVersion, dirtyFiles, dirtyFingerprint, buildDirty, buildIncremental, mcpQuery, mcpResetCache, bm25Search, splitIdent, isDirectRun, SCHEMA_VERSION, CODE_EXT };

// True when this module IS the process entry point, false when imported.
//
// The naive `fileURLToPath(import.meta.url) === process.argv[1]` comparison is
// WRONG for every install that goes through the package's own bin: npm links
// `node_modules/.bin/agentmap -> ../@raymondchins/agentmap/agentmap.mjs`, so
// argv[1] is the SYMLINK path while import.meta.url is the REAL path. They never
// match, the guard reads "imported", main() never runs — and the CLI exits 0
// having printed nothing. That silently killed `npx @raymondchins/agentmap`,
// `npm run agentmap`, `--install-hooks`, and the MCP Registry's `--mcp` launch
// across 12 published versions, 0.10.0 through 0.16.0. Compare realpaths so the
// symlink and its target resolve to the same file.
//
// The range is measured against published tarballs, not inferred from tags:
// `git tag --contains a217331` starts at v0.12.1, but 0.10.0 and 0.11.0 were
// published manually off the same day's work (ROADMAP.md:262), so the tag
// ancestry understates it. Verified via the bin symlink: 0.9.0 prints "0.9.0",
// 0.10.0 prints nothing.
function isDirectRun(metaUrl) {
  const argv1 = process.argv[1];
  if (!argv1) return false;
  const self = fileURLToPath(metaUrl);
  // Fast path first: identical strings need no syscall, and this is the only
  // branch available if realpath throws (deleted file, permission, exotic FS).
  if (self === argv1) return true;
  try {
    return realpathSync(self) === realpathSync(argv1);
  } catch {
    return false;
  }
}

// Run the CLI only when executed directly (`node agentmap.mjs …`, `npx
// @raymondchins/agentmap …`, `node_modules/.bin/agentmap …`), never on import.
if (isDirectRun(import.meta.url)) {
  await main();
}