@raymondchins/agentmap 0.3.0 → 0.5.0

package/README.md

@@ -4,14 +4,14 @@
 
 # agentmap
 
-**The repo map your coding agent is _forced_ to use — ~98% fewer tokens to understand your TS/JS codebase.**
+**The repo map your coding agent is _forced_ to use — ~98% fewer context tokens to understand your TS/JS codebase.**
 
 Your AI coding agent re-learns your codebase every session — opening files and grepping to find
 what connects to what, burning tokens before it writes a line. agentmap gives it a **queryable,
 ranked code-relationship map for TypeScript/JavaScript repos** instead — a `ts-morph` import/symbol
 graph ranked by personalized PageRank. Ask it to *"add a field"* or *"fix the login bug"* and it
 finds the right files, their imports, and what already exists in
-**~98% fewer tokens on average** (up to **99.9% per task**) — kept current by a post-commit
+**~98% fewer context tokens on average** (up to **~99.9% per task**; figures are chars/4 estimates applied equally to both sides) — kept current by a post-commit
 auto-refresh and actually used via a `PreToolUse(Grep)` hook.
 
 [![npm](https://img.shields.io/npm/v/@raymondchins/agentmap)](https://www.npmjs.com/package/@raymondchins/agentmap)
@@ -60,6 +60,19 @@ across [zod](https://github.com/colinhacks/zod) (367 files, **99.2%**) and
 on a single whole-repo map. Reproducible at pinned shas; full per-scenario tables in
 **[`./benchmark/RESULTS.md`](./benchmark/RESULTS.md)**.
 
+> **Methodology note:** the 58× overall figure is dominated by the whole-repo-load scenario
+> (Scenario F — 150 K vs 1 K tokens), which skews the combined ratio sharply upward. Excluding it,
+> the per-task overall ratio on the same sample repo is approximately 32×. Both numbers are real;
+> the headline captures the most common agent worst-case (repo-dump on session start), while the
+> per-task average better represents typical individual queries. RESULTS.md has the full breakdown.
+
+**Fewer tokens, but are they the _right_ tokens?** Token efficiency is only half the story — a
+separate [`EVAL.md`](./EVAL.md) (`npm run eval`) scores **retrieval accuracy** against ground
+truth derived live from real repos (zod, zustand, hono). Headline: agentmap returns the symbol
+definition in the **top 3 ~95%** of the time (naive grep ~79%) at **~2.6× fewer tokens**, and
+identifies a module's dependents at **~100% precision** (grep ~58%). Honest tradeoffs and method
+in EVAL.md.
+
 **Speed:** a cold build (parse + PageRank + symbol graph) takes **~1.2s**; a warm cached query
 returns in **~0.1s** (the lazy-loaded path added in 0.2.2) — the agent has a ranked answer back
 before it would have finished opening the first handful of files.
@@ -504,7 +517,9 @@ Honesty first — this is deliberately a small, sharp tool, not a universal code
 
 Issues and PRs welcome. High-value directions:
 
-- An end-to-end retrieval/accuracy eval (the benchmark is context-efficiency only today).
+- Retrieval-accuracy eval — **done** ([`EVAL.md`](./EVAL.md), `npm run eval`). Next: a
+  type-aware dependents mode (the eval excludes type-only edges to match the value-import
+  graph) and an `app/`-router fixture so `--feature` retrieval can be scored too.
 - A real tokenizer behind the `--map` budget.
 - Hardening feature detection for non-`app/`-router layouts.
 

package/agentmap.mjs

@@ -13,7 +13,7 @@
 //  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, statSync, chmodSync } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, readdirSync, statSync, lstatSync, chmodSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
@@ -26,8 +26,12 @@ const _require = createRequire(import.meta.url);
 let _tsm = null;
 const tsMorph = () => (_tsm ??= _require("ts-morph"));
 
-const MAP = ".claude/agentmap.json";
-const SCHEMA_VERSION = 2;
+const MAP = ".claude/agentmap/map.json";
+const MAP_LEGACY = ".claude/agentmap.json"; // pre-namespacing path; read for migration
+// 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.
+// Old caches (schema 2) are ignored so the first run after upgrade rebuilds.
+const SCHEMA_VERSION = 3;
 
 // ---------------------------------------------------------------------------
 // Tuning constants — KEEP THESE VALUES IDENTICAL (output + marketing must not
@@ -58,9 +62,21 @@ const sh = (c) => { try { return execSync(c, { stdio: ["ignore", "pipe", "ignore
 // untracked files (skips gitignored paths like node_modules). Reads DISK, so
 // never stale. -F = fixed-string so literals like "bg-[#faf8f2]" aren't regex.
 // 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*",
+  ":(exclude,icase)*secret*", ":(exclude,icase)*credential*", ":(exclude,icase)*.password*",
+];
 const contentSearch = (q) => {
   try {
-    return execFileSync("git", ["grep", "-F", "--untracked", "-n", "-i", "-I", "-e", q, "--", ".", ":!.claude/agentmap.json"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: MAXBUF }).trim();
+    return execFileSync("git", ["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");
@@ -72,7 +88,7 @@ const dirtyCount = () =>
     let p = l.slice(3);                                  // strip "XY " status prefix
     if (p.includes(" -> ")) p = p.split(" -> ").pop();   // rename: keep the new path
     p = p.replace(/^"|"$/g, "");                         // unquote space/special paths
-    return /\.(ts|tsx|mjs|cjs|jsx|js)$/.test(p);
+    return /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|vue)$/.test(p);
   }).length;
 const tokEst = (s) => Math.ceil((s || "").length / 4); // rough chars/4 estimate
 
@@ -83,7 +99,8 @@ const getOrSet = (m, k, make) => { let v = m.get(k); if (v === undefined) { v =
 // "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.
-const SRC_EXT = /\.(ts|tsx|mts|cts|jsx|js|mjs|cjs)$/;
+// Includes `.vue` so editing a Vue SFC invalidates the non-git cache too.
+const SRC_EXT = /\.(ts|tsx|mts|cts|jsx|js|mjs|cjs|vue)$/;
 function sourceFingerprint() {
   try {
     const entries = [];
@@ -92,7 +109,12 @@ function sourceFingerprint() {
         if (name === "node_modules" || name === ".git" || name === ".next") continue;
         const full = dir + "/" + name;
         let st;
-        try { st = statSync(full); } catch { continue; }
+        // lstatSync (NOT statSync) so a symlink reports as a symlink instead of
+        // its target. Symlinked entries are SKIPPED entirely — never recursed
+        // into, never stat'd through — so a circular symlink can't cause infinite
+        // recursion / stack overflow.
+        try { st = lstatSync(full); } catch { continue; }
+        if (st.isSymbolicLink()) continue;
         if (st.isDirectory()) walk(full);
         else if (SRC_EXT.test(name)) entries.push(`${full}:${st.mtimeMs}:${st.size}`);
       }
@@ -103,6 +125,70 @@ function sourceFingerprint() {
   } catch { return ""; }
 }
 
+// =============================================================================
+// 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) {
@@ -228,13 +314,25 @@ function makeProject() {
   const loaded = new Set(project.getSourceFiles().map((s) => s.getFilePath()));
   const cwdp = process.cwd().replace(/\\/g, "/");
   const listed = sh("git ls-files --cached --others --exclude-standard").split("\n").filter(Boolean);
+  // `.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 (!/\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(f)) continue;
-      const segs = f.split("/");
-      if (segs.includes("node_modules") || segs.includes(".next")) continue;
-      if (!loaded.has(`${cwdp}/${f}`)) missing.push(f);
+      if (/\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.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 {
@@ -244,8 +342,38 @@ function makeProject() {
       "components/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}", "lib/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
       "pages/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}", "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
     ]);
+    // Non-git `.vue` fallback: walk the tree like sourceFingerprint() does.
+    try {
+      const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+          if (name === "node_modules" || name === ".git" || name === ".next") continue;
+          const full = dir + "/" + name;
+          // lstatSync (NOT statSync) + skip symlinks, matching sourceFingerprint():
+          // a circular symlink would otherwise recurse until the stack overflows.
+          let st; try { st = lstatSync(full); } catch { continue; }
+          if (st.isSymbolicLink()) continue;
+          if (st.isDirectory()) walk(full);
+          else if (name.endsWith(".vue")) vueFiles.push(full.replace(/^\.\//, ""));
+        }
+      };
+      walk(".");
+    } catch { /* ignore — proceed without Vue */ }
   }
-  return project;
+  // 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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -255,11 +383,18 @@ function makeProject() {
 // ---------------------------------------------------------------------------
 function build() {
   const t0 = Date.now();
-  const project = makeProject();
+  const { project, vueMap, vueReal } = makeProject();
   const { SyntaxKind } = tsMorph();
   const CallExpression = SyntaxKind.CallExpression;
   const cwd = process.cwd().replace(/\\/g, "/");
-  const rel = (p) => p.replace(cwd + "/", "");
+  // 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 = {}, dependents = {}, features = {};
   // PATH-SEGMENT exclusion (not substring) so e.g. components/.next-demo or
   // src/node_modules_helper.ts are NOT wrongly excluded.
@@ -280,10 +415,19 @@ function build() {
     };
     const baseAbs = join(fromAbsDir, spec);
     const tryGet = (abs) => { const sf = project.getSourceFile(abs); return sf ? sf : null; };
+    // Vue SFC: `import X from "./C.vue"` (exact) ALWAYS wins — the user wrote
+    // `.vue` explicitly, so we honor that. This check must stay BEFORE the
+    // TS/JS loop.
+    if (vueReal[baseAbs]) return rel(baseAbs);
     let sf = tryGet(baseAbs);
     if (!sf) for (const e of RES_EXT) { sf = tryGet(`${baseAbs}.${e}`); if (sf) break; }
     if (!sf) for (const e of RES_EXT) { sf = tryGet(`${baseAbs}/index.${e}`); if (sf) break; }
-    return sf ? rel(sf.getFilePath()) : null;
+    // TS/JS SHADOW WINS: when a same-name .ts/.js exists, the extensionless
+    // `import "./C"` resolves to it (TS/JS-first priority is preserved). Only
+    // fall through to `.vue` as a last resort, when no TS/JS shadow exists.
+    if (sf) return rel(sf.getFilePath());
+    if (vueReal[`${baseAbs}.vue`]) return rel(`${baseAbs}.vue`);
+    return null;
   };
 
   const sourceFiles = project.getSourceFiles();
@@ -394,9 +538,9 @@ function build() {
     fingerprint: sha ? undefined : sourceFingerprint(),
     hubs, features, rankedSymbols: rankedSymbols.slice(0, RANKED_SYMBOLS_LIMIT), files,
   };
-  mkdirSync(".claude", { recursive: true });
+  mkdirSync(".claude/agentmap", { recursive: true });
   // Atomic write: tmp + rename so a concurrent background rebuild can never
-  // expose a torn/truncated agentmap.json to a reader.
+  // expose a torn/truncated map.json to a reader.
   const tmp = MAP + ".tmp";
   writeFileSync(tmp, JSON.stringify(out));
   renameSync(tmp, MAP);
@@ -500,9 +644,13 @@ function rankSymbols(files, focus) {
 // clean tree. A dirty tree REBUILDS from disk so queries reflect in-flight edits.
 function ensureFresh() {
   const sha = currentSha();
-  if (existsSync(MAP)) {
+  // 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(MAP, "utf8"));
+      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.
@@ -542,55 +690,95 @@ function fileBlock(key, f) {
   console.log(`dependents (${f.dependents.length}): ${f.dependents.join(", ") || "—"}`);
 }
 
+// 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 --install-hooks`); }
+  }
+}
+
 // ---------------------------------------------------------------------------
-// --install-hooks: copy the package post-commit hook into .git/hooks, ensure
-// .claude/agentmap.json 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.
-// Throws on any failure so the caller can stderr+exit 1.
+// --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.
 // ---------------------------------------------------------------------------
-function installHooks() {
+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 git dir of the CURRENT repo (cwd), then copy in the hook.
   const gitDir = sh("git rev-parse --git-dir");
   if (!gitDir) throw new Error("not a git repository (cwd has no .git) — run inside the repo you want to wire up");
   const hooksDir = `${gitDir}/hooks`;
-  mkdirSync(hooksDir, { recursive: true });
   const dest = `${hooksDir}/post-commit`;
-  writeFileSync(dest, readFileSync(src, "utf8"), { mode: 0o755 });
-  chmodSync(dest, 0o755); // explicit: writeFileSync mode is masked by umask
 
-  // Ensure .gitignore (in cwd) contains the derived-map line (append/create).
-  const IGNORE_LINE = ".claude/agentmap.json";
+  // 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 = ".claude/hooks/agentmap-nudge.mjs";
+  const NUDGE_CMD = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/agentmap-nudge.mjs"`;
+
+  // .gitignore line: ignore the namespaced map DIR (not the legacy single file).
+  const IGNORE_LINE = ".claude/agentmap/";
+  const settingsPath = ".claude/settings.json";
+
+  // --- Determine what WOULD change (so --dry-run and the pre-write notice both
+  // describe the real plan). ---
   let ignoredAlready = false;
   if (existsSync(".gitignore")) {
-    const cur = readFileSync(".gitignore", "utf8");
-    if (cur.split(/\r?\n/).some((l) => l.trim() === IGNORE_LINE)) ignoredAlready = true;
-    else writeFileSync(".gitignore", cur + (cur.endsWith("\n") || cur === "" ? "" : "\n") + IGNORE_LINE + "\n");
-  } else {
-    writeFileSync(".gitignore", IGNORE_LINE + "\n");
+    ignoredAlready = readFileSync(".gitignore", "utf8").split(/\r?\n/).some((l) => l.trim() === IGNORE_LINE);
   }
-
-  // Auto-wire the PreToolUse(Grep|Bash) enforcement nudge into the PROJECT
-  // settings (.claude/settings.json) so "the agent is forced to use the map"
-  // is ON by default — not a manual paste. Merge-safe + idempotent: preserves
-  // any existing settings/hooks, never duplicates our entry. Uses a project-
-  // relative command so a committed settings.json stays portable across machines.
-  // Both the Grep tool AND raw Bash searchers (grep/rg/ag/ack) are covered by
-  // a single hook file — the nudge routes internally based on tool_name.
-  const NUDGE_CMD = "node node_modules/@raymondchins/agentmap/hooks/agentmap-nudge.mjs";
-  const settingsPath = ".claude/settings.json";
   let settings = {};
   if (existsSync(settingsPath)) {
-    try { settings = JSON.parse(readFileSync(settingsPath, "utf8")) || {}; }
-    catch { throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run --install-hooks`); }
+    settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
   }
   settings.hooks ??= {};
   settings.hooks.PreToolUse ??= [];
-  // Check whether BOTH matchers are already present.
   const hasGrep = settings.hooks.PreToolUse.some(
     (e) => e?.matcher === "Grep" && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
   );
@@ -598,12 +786,48 @@ function installHooks() {
     (e) => e?.matcher === "Bash" && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
   );
   const alreadyWired = hasGrep && hasBash;
-  if (!hasGrep) {
-    settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
+
+  // 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;
   }
-  if (!hasBash) {
-    settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [{ type: "command", command: NUDGE_CMD }] });
+
+  // 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
+  mkdirSync(hooksDir, { recursive: true });
+  writeFileSync(dest, readFileSync(src, "utf8"), { mode: 0o755 });
+  chmodSync(dest, 0o755); // explicit: writeFileSync mode is masked by umask
+
+  // 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");
@@ -611,6 +835,7 @@ function installHooks() {
 
   // 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`
@@ -640,7 +865,7 @@ const out = (obj, prose) => { if (wantJson) console.log(JSON.stringify(obj)); el
 // NOT in this set is an unknown flag → usage error (exit 2), not a silent build.
 const KNOWN = new Set([
   "--json", "--print",
-  "--help", "-h", "--version", "-v", "--install-hooks", "--mcp",
+  "--help", "-h", "--version", "-v", "--install-hooks", "--dry-run", "--mcp",
   "--any", "--find", "--relates", "--map", "--focus", "--tokens",
   "--symbols", "--feature", "--features", "--hubs",
 ]);
@@ -674,7 +899,9 @@ Global modifier:
   --json               emit exactly one JSON object (no prose) for the command
 
 Maintenance:
-  --install-hooks      install git post-commit + print the PreToolUse snippet
+  --install-hooks [--dry-run]
+                       install git post-commit + copy the PreToolUse nudge +
+                       wire .claude/settings.json (--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
@@ -707,7 +934,7 @@ if (has("--mcp")) {
 // --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(); process.exit(0); }
+  try { installHooks({ dryRun: has("--dry-run") }); process.exit(0); }
   catch (e) { console.error(`agentmap --install-hooks failed: ${e?.message || e}`); process.exit(1); }
 }
 // Unknown-flag guard: any "-"-prefixed token not in KNOWN → usage error (exit

package/hooks/agentmap-nudge.mjs

@@ -96,11 +96,19 @@ process.stdin.on("end", () => {
       // hunts.
       const SEARCHER_RE = /(^|[;&]\s*)(rg|ripgrep|grep|egrep|fgrep|ag|ack)\b/;
       if (SEARCHER_RE.test(cmd)) {
-        fire =
-          DEP_RE.test(cmd) ||
-          (COMPONENT_TAG_RE.test(cmd) && !GENERIC_DENYLIST.test(cmd)) ||
-          INTENT_RE.test(cmd) ||
-          SYMBOL_RE.test(cmd);
+        // Guard: if any operand token references a non-source data file, stay
+        // silent — e.g. `rg TypeError app.log` is log-filtering, not a
+        // symbol/component hunt. Match on extension only (not inside quoted
+        // patterns) by scanning whitespace-separated tokens for a data-file ext.
+        const DATA_FILE_RE = /\.(log|txt|out|csv|tsv|jsonl|ndjson|json|md|ya?ml|xml)(\b|$)/i;
+        const hasDataFileTarget = cmd.split(/\s+/).some((tok) => DATA_FILE_RE.test(tok));
+        if (!hasDataFileTarget) {
+          fire =
+            DEP_RE.test(cmd) ||
+            (COMPONENT_TAG_RE.test(cmd) && !GENERIC_DENYLIST.test(cmd)) ||
+            INTENT_RE.test(cmd) ||
+            SYMBOL_RE.test(cmd);
+        }
       }
     }
 

package/hooks/post-commit

@@ -28,15 +28,26 @@ for state in rebase-merge rebase-apply MERGE_HEAD CHERRY_PICK_HEAD BISECT_LOG RE
   fi
 done
 
-# Locate the builder: prefer a local agentmap.mjs, else the installed `agentmap`.
+# ---------------------------------------------------------------------------
+# Runner resolution — security rationale:
+#
+#   Only TWO repo-local paths are trusted: ./agentmap.mjs (this repo's own
+#   dogfooding entry-point, reviewed and version-controlled at the root) and
+#   nothing else.  ./scripts/agentmap.mjs was removed because it is an unusual
+#   path that a malicious PR could introduce to gain arbitrary code execution
+#   on a victim's next commit without touching any obviously sensitive file.
+#
+#   Set AGENTMAP_HOOK_NO_LOCAL=1 to skip even ./agentmap.mjs and rely solely
+#   on the installed binary / npx — useful in CI or when reviewing untrusted
+#   branches.
+#
 # We cd "$ROOT" before running, so use RELATIVE paths — avoids word-splitting on
 # spaces in the repo path (POSIX sh has no arrays; quoting $RUNNER at invocation
 # would bundle cmd+args into one token and break argument passing).
+# ---------------------------------------------------------------------------
 RUNNER=""
-if [ -f "$ROOT/agentmap.mjs" ]; then
+if [ -z "$AGENTMAP_HOOK_NO_LOCAL" ] && [ -f "$ROOT/agentmap.mjs" ]; then
   RUNNER="node ./agentmap.mjs"
-elif [ -f "$ROOT/scripts/agentmap.mjs" ]; then
-  RUNNER="node ./scripts/agentmap.mjs"
 elif command -v agentmap >/dev/null 2>&1; then
   # Bare binary name — the installed binary is named `agentmap` (no scope).
   RUNNER="agentmap"

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "The repo map your coding agent is forced to use — ~98% fewer tokens (up to 99.9% per task) to understand a TS/JS codebase. A queryable, ranked ts-morph code-relationship map: PageRank hubs, Aider-style symbol ranking, a token-budgeted digest, and a single --any router (file → symbol → feature → live git-grep), wired into the agent loop via post-commit auto-refresh and a PreToolUse hook.",
+  "description": "The repo map your coding agent is forced to use — estimated ~98% fewer context tokens (up to ~99.9% per task, chars/4 estimate) to understand a TS/JS codebase. A queryable, ranked ts-morph code-relationship map: PageRank hubs, Aider-style symbol ranking, a token-budgeted digest, and a single --any router (file → symbol → feature → live git-grep), wired into the agent loop via post-commit auto-refresh and a PreToolUse hook.",
   "type": "module",
   "bin": {
     "agentmap": "agentmap.mjs"
@@ -18,7 +18,8 @@
   ],
   "scripts": {
     "map": "node agentmap.mjs",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs test/**/*.test.mjs",
+    "eval": "node eval/eval.mjs"
   },
   "engines": {
     "node": ">=18"