@raymondchins/agentmap 0.2.3 → 0.4.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.
@@ -133,15 +146,24 @@ the installed `agentmap` binary, then `npx --no-install @raymondchins/agentmap`.
 
 ### 2. Force the agent to use it — `PreToolUse` hook
 
-[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** `PreToolUse(Grep)`
-hook for Claude Code. When a `Grep` looks like a dependency / who-imports / component-usage /
-reuse search, it injects a reminder steering the agent to `agentmap --any` first. It never
-denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
-sweeps — so it's high-signal, not nagging.
-
-`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
-preserves existing settings and won't duplicate on re-run). For reference, or to wire
-it by hand:
+[`hooks/agentmap-nudge.mjs`](./hooks/agentmap-nudge.mjs) is a **non-blocking** hook for
+Claude Code that covers **both** the `Grep` tool and raw Bash text-searchers
+(`grep`/`rg`/`egrep`/`fgrep`/`ag`/`ack`). When either looks like a dependency /
+who-imports / component-usage / reuse / where-is-symbol search, it injects a reminder
+steering the agent to `agentmap --any` first. It never denies the call, and stays silent
+for raw-string / Tailwind-class / lowercase-HTML-tag sweeps and for pipe-filtered commands
+like `ps aux | grep node` — so it's high-signal, not nagging.
+
+**Fires on:** `import`/`require`/`export`/`from '...'` patterns, JSX component tags
+(`<Hero`, `<ProviderCard`), explicit intent words (`where is`, `who imports`, `reuse`,
+`existing component`), and — in the Bash branch — bare multi-hump PascalCase identifiers
+(`ProviderCard`, `TopProviders`) that almost always mean "where is this symbol / who uses
+it". The Bash branch only fires when the searcher is the *primary* command (at the start,
+or after `;`/`&&`); piped log-filters stay silent.
+
+`--install-hooks` writes both matchers into `.claude/settings.json` for you (merge-safe —
+preserves existing settings, won't duplicate on re-run). The single hook file dispatches
+internally on `tool_name`. For reference, or to wire it by hand:
 
 ```json
 {
@@ -149,9 +171,11 @@ it by hand:
     "PreToolUse": [
       {
         "matcher": "Grep",
-        "hooks": [
-          { "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }
-        ]
+        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "node ./hooks/agentmap-nudge.mjs" }]
       }
     ]
   }
@@ -159,7 +183,7 @@ it by hand:
 ```
 
 That's the "forced to use it" in the tagline: the map stays current on its own, and the
-agent is steered to it the moment it reaches for a dependency-shaped grep.
+agent is steered to it the moment it reaches for a dependency-shaped grep or Bash search.
 
 ---
 
@@ -493,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,7 +26,8 @@ const _require = createRequire(import.meta.url);
 let _tsm = null;
 const tsMorph = () => (_tsm ??= _require("ts-morph"));
 
-const MAP = ".claude/agentmap.json";
+const MAP = ".claude/agentmap/map.json";
+const MAP_LEGACY = ".claude/agentmap.json"; // pre-namespacing path; read for migration
 const SCHEMA_VERSION = 2;
 
 // ---------------------------------------------------------------------------
@@ -58,9 +59,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");
@@ -92,7 +105,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}`);
       }
@@ -394,9 +412,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 +518,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,67 +564,156 @@ 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) 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) 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.
-  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 ??= [];
-  const alreadyWired = settings.hooks.PreToolUse.some(
-    (e) => Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  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")),
+  );
+  const hasBash = settings.hooks.PreToolUse.some(
+    (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;
+
+  // 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
+  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) {
-    settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
     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) → agentmap nudge — left as-is`
-    : `wired PreToolUse(Grep) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
+    ? `${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.");
 }
 
@@ -628,7 +739,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",
 ]);
@@ -662,7 +773,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
@@ -695,7 +808,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

@@ -1,24 +1,35 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 // ============================================================================
-//  agentmap — PreToolUse(Grep) nudge hook
+//  agentmap — PreToolUse nudge hook (Grep tool + Bash text-searchers)
 //
-//  Steers dependency / who-imports / reuse / component-usage greps toward the
-//  agentmap repo-map instead of serial grep. NON-BLOCKING: only ever injects a
-//  reminder via `additionalContext`; never denies the Grep. Exits 0 on every
-//  path. Dependency-free (Node stdlib only) — Claude Code pipes the tool-call
-//  JSON on stdin.
+//  Steers dependency / who-imports / reuse / component-usage / where-is-symbol
+//  searches toward the agentmap repo-map instead of serial grep. NON-BLOCKING:
+//  only ever injects a reminder via `additionalContext`; never denies the call.
+//  Exits 0 on every path. Dependency-free (Node stdlib only) — Claude Code
+//  pipes the tool-call JSON on stdin.
 //
-//  Heuristic: fires when the grep PATTERN looks like (a) a dependency hunt
+//  Why the Bash branch: the original hook only watched the Grep TOOL, so any
+//  search run as raw `grep`/`rg` via Bash bypassed the nudge entirely — the
+//  exact gap that let an agent forget agentmap and fall back to manual
+//  Read/sed/awk. This closes it.
+//
+//  Heuristic: fires when the search looks like (a) a dependency hunt
 //  (import/require/export / "from '..." / who-imports), (b) a component /
 //  "where-is" / reuse lookup (a JSX component tag like <Heading, or where-is /
-//  who-uses / reuse / existing-component intent words). A raw string or
-//  Tailwind-class search (e.g. "bg-white", "text-3xl") and lowercase HTML-tag
-//  sweeps (<div, <h1) produce NO output — no nagging.
+//  who-uses / reuse / existing-component intent words), (c) — Bash only — a
+//  bare multi-hump PascalCase identifier (ProviderCard, TopProviders), almost
+//  always a "where is this symbol / who uses it" hunt. A raw string or
+//  Tailwind-class search (bg-white, text-3xl) and lowercase HTML-tag sweeps
+//  (<div, <h1) produce NO output — no nagging.
+//
+//  Bash branch only fires when grep/rg/ag is the PRIMARY command (at start, or
+//  after `;` / `&&` — NOT after a pipe, so `… | grep SomeError` log-filtering
+//  stays silent).
 //
-//  agentmap's `--any` router falls back to a live git-grep on its own, so it
-//  still covers the raw-string / copy case — but only when the agent reaches
-//  for it deliberately, not on every content sweep.
+//  Injection-safe: the user's pattern/command is ONLY regex-tested, never
+//  interpolated into the emitted message or executed. Output is a single fixed
+//  JSON object.
 // ============================================================================
 
 let raw = "";
@@ -27,14 +38,8 @@ process.stdin.on("data", (c) => (raw += c));
 process.stdin.on("end", () => {
   try {
     const payload = JSON.parse(raw || "{}");
+    const tool = String(payload.tool_name || "");
     const ti = payload.tool_input || {};
-    const pattern = String(ti.pattern || "");
-
-    // Defensive guard: pathological-input belt-and-suspenders.
-    // If the pattern is unreasonably long, skip nudging entirely.
-    if (pattern.length > 2000) {
-      process.exit(0);
-    }
 
     // (a) Dependency / who-imports / reuse intent signals in the pattern itself.
     const DEP_RE =
@@ -45,11 +50,14 @@ process.stdin.on("end", () => {
     // raw HTML/content sweeps of <div>/<h1> silent, so it stays high-signal for
     // "where is this component used/defined".
     //
-    // Denylist: common TS generic/utility type containers that start with an
-    // uppercase letter but are NOT React components. Without this, a grep for
-    // `<Promise<` or `<Record<string` fires the nudge spuriously.
+    // Denylist: common TS generic/utility type containers (e.g. <Promise<,
+    // <Record<string) that look like a component tag but are NOT React components.
+    // NOT ^-anchored — matches ANYWHERE, because the Bash branch tests the whole
+    // command (the generic sits mid-string, e.g. `rg "<Promise<Foo>"`) and a
+    // generic can also appear mid-pattern in Grep (e.g. useState<Promise>). The
+    // `\b` after the name keeps real components like <PromiseCard / <MapView firing.
     const GENERIC_DENYLIST =
-      /^<(Promise|Array|Map|Set|Record|Partial|Readonly|Pick|Omit|Required|Exclude|Extract|NonNullable|ReturnType|Awaited|Parameters|InstanceType)\b/;
+      /<(Promise|Array|Map|Set|Record|Partial|Readonly|Pick|Omit|Required|Exclude|Extract|NonNullable|ReturnType|Awaited|Parameters|InstanceType)\b/;
     const COMPONENT_TAG_RE = /<[A-Z][\w.]*/;
 
     // (c) Explicit reuse / "where-is" intent words (case-insensitive): "where is",
@@ -58,21 +66,63 @@ process.stdin.on("end", () => {
     const INTENT_RE =
       /\bwhere\s+is\b|\bwho\s+(imports|uses|renders)\b|\breuse\b|\b(existing|shared)\s+(util|component|hook|helper)\b|\bis\s+there\s+(an?\s+)?(existing|shared)\b/i;
 
-    if (
-      pattern &&
-      (DEP_RE.test(pattern) ||
-        (COMPONENT_TAG_RE.test(pattern) && !GENERIC_DENYLIST.test(pattern)) ||
-        INTENT_RE.test(pattern))
-    ) {
+    // (d) Bare multi-hump PascalCase identifier (e.g. ProviderCard, TopProviders).
+    // Bash branch only. Two humps required so all-caps (TODO, API), single-word
+    // (Error, Button) and lowercase (useState) stay silent → high signal, no
+    // Tailwind/raw-string noise.
+    const SYMBOL_RE = /\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b/;
+
+    let fire = false;
+
+    if (tool === "Grep") {
+      const pattern = String(ti.pattern || "");
+
+      // Defensive guard: pathological-input belt-and-suspenders.
+      // If the pattern is unreasonably long, skip nudging entirely.
+      if (pattern.length > 2000) {
+        process.exit(0);
+      }
+
+      fire =
+        !!pattern &&
+        (DEP_RE.test(pattern) ||
+          (COMPONENT_TAG_RE.test(pattern) && !GENERIC_DENYLIST.test(pattern)) ||
+          INTENT_RE.test(pattern));
+    } else if (tool === "Bash") {
+      const cmd = String(ti.command || "");
+      // Only when grep/rg/ag is the PRIMARY command (start, or after ; / && — NOT
+      // after a pipe, so `… | grep SomeError` log-filtering stays silent). Then
+      // test the whole command, plus the symbol rule for bare-identifier symbol
+      // hunts.
+      const SEARCHER_RE = /(^|[;&]\s*)(rg|ripgrep|grep|egrep|fgrep|ag|ack)\b/;
+      if (SEARCHER_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);
+        }
+      }
+    }
+
+    if (fire) {
+      const AM = "node node_modules/@raymondchins/agentmap/agentmap.mjs";
       const msg =
-        "This Grep looks like a dependency / component / who-imports / reuse search. " +
-        "Use agentmap FIRST — it's faster than serial grep. Easiest: " +
-        "`npx @raymondchins/agentmap --any <query>` (or `node agentmap.mjs --any <query>`) " +
-        "— one command, auto-routes file → symbol → feature → live content. " +
-        "Or be specific: `--relates <path>` (blast radius / who-imports), " +
-        "`--find <symbol>` (reuse-before-rebuild / where a component is defined), " +
-        "`--feature <name>` (files in a feature), `--hubs` (most-imported files). " +
-        "Rebuild the map with `npx @raymondchins/agentmap` (or `node agentmap.mjs`) if it's stale. " +
+        "This looks like a dependency / component / who-imports / reuse / where-is-symbol " +
+        "search. Use agentmap FIRST — it's faster than serial grep. Easiest: " +
+        "`" + AM + " --any <query>` " +
+        "(one command — auto-routes file → symbol → feature → live content). " +
+        "Or be specific: `" + AM + " --relates <path>` (blast radius / who-imports), " +
+        "`" + AM + " --find <symbol>` (reuse-before-rebuild / where a component is defined), " +
+        "`" + AM + " --feature <name>` (files in a feature). " +
+        "Rebuild the map with `npm run agentmap` (or `npx @raymondchins/agentmap`) if it's stale. " +
         "Only fall back to grep if agentmap doesn't cover it.";
       process.stdout.write(
         JSON.stringify({

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.2.3",
+  "version": "0.4.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",
+    "eval": "node eval/eval.mjs"
   },
   "engines": {
     "node": ">=18"