@sdsrs/code-graph 0.139.0 → 0.141.0

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.139.0",
+  "version": "0.141.0",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/scripts/adopt.js

@@ -71,6 +71,21 @@ function writeFileAtomic(filePath, data, { followLink = false } = {}) {
 // the full table at .claude/plugin_code_graph_mcp.md (opened on demand, never
 // auto-loaded). Project-type tailoring swaps a couple of rows (web → HTTP-route
 // tracing; frontend → reference audits) — body of the detail doc is unchanged.
+//
+// Every row spends the bare name `code-graph-mcp`, and a plugin-only install has
+// it nowhere on PATH: findBinary() resolves the plugin's own download at
+// ~/.cache/code-graph/bin (auto-update.js `cachedBinaryPath`), and the global-npm
+// tiers below it exist only for users who ran `npm i -g` themselves. Issue #41 is
+// what that reads like from the other side — a table of commands the user's shell
+// answers with "command not found". Hence the fallback line below the table.
+//
+// It names a path SHAPE, never a resolved one. This file goes into a git-tracked
+// CLAUDE.md (the adopt output says so two screens down), so a resolved
+// /home/<user>/… is right on one machine and wrong on every teammate's — and
+// buildBlock's byte-determinism is exactly what needsRefresh diffs, so
+// machine-varying content would rewrite the block on every clone's next
+// SessionStart. No `.exe` variant for the same reason it is safe not to have one:
+// platformGuard() refuses adopt on win32, so this block never exists there.
 const BLOCK_HEADING = '## Code Graph (repo-wide AST index)';
 
 function buildTriggerRows(projectType = 'generic') {
@@ -116,6 +131,9 @@ function buildBlock(projectType = 'generic') {
     '',
     table,
     '',
+    'Not on PATH? A plugin-only install keeps its own copy — same commands, run',
+    '`~/.cache/code-graph/bin/code-graph-mcp` (or `npm i -g @sdsrs/code-graph` once).',
+    '',
     "Still use Grep for literal strings/regex in non-code files; still Read files you'll edit.",
     'Full command + MCP-tool table: `.claude/plugin_code_graph_mcp.md`',
   ].join('\n');
@@ -891,7 +909,25 @@ function formatResult(action, result) {
 }
 
 if (require.main === module) {
-  const action = process.argv[2] === 'unadopt' ? 'unadopt' : 'adopt';
+  // Strict, because SessionStart now hands users this entry point directly
+  // (`node <…>/adopt.js unadopt`) rather than the binary, which validates its
+  // arguments in main.rs before dispatching here. The old `argv[2] === 'unadopt'
+  // ? … : 'adopt'` fell back to ADOPT for anything else, so `--help` performed
+  // an unadopt where the binary prints help, and a mistyped verb silently
+  // adopted the current project — the footgun main.rs's `reject_extra_args`
+  // exists to prevent.
+  //
+  // Both binary call sites stay valid: main.rs passes `["unadopt"]` for unadopt
+  // and no arguments at all for adopt.
+  const argv = process.argv.slice(2);
+  const action = argv.length === 0 ? 'adopt' : argv[0];
+  if (argv.length > 1 || (action !== 'adopt' && action !== 'unadopt')) {
+    process.stderr.write(
+      `[code-graph] Usage: node ${path.basename(__filename)} [adopt|unadopt]\n` +
+      '  Exactly one verb and no flags. No argument means `adopt`.\n' +
+      '  Refusing rather than guessing: both verbs write to your CLAUDE.md.\n');
+    process.exit(2);
+  }
   const result = action === 'unadopt' ? unadopt() : adopt();
   process.stdout.write(formatResult(action, result) + '\n');
   process.exit(result.ok === false ? 1 : 0);

package/claude-plugin/scripts/find-binary.js

@@ -33,6 +33,34 @@ function pathProbeTimeoutMs(remaining = require('./hook-fail-open').remainingMs)
   const ms = left === null ? PATH_PROBE_MIN_MS : Math.floor(left);
   return Math.max(ms, PATH_PROBE_MIN_MS);
 }
+
+// `readBinaryVersion`'s own default. Kept here as the number this module asks
+// for so the clamp below is expressed against the same figure the callee would
+// have used on its own.
+const VERSION_PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * How long ONE `--version` probe in the discovery chain may run (JS-23, audit
+ * 2026-09-07).
+ *
+ * The version gate execs the candidate binary, and `findBinary()` walks up to
+ * six candidates — so a chain of default 5 s probes is 30 s of children on the
+ * first thing every hook does, all of it BEFORE the hook has consulted its
+ * budget even once. Cold cache (first install, a version bump,
+ * `auto-update.clearCache()`) is exactly when the chain is longest and every
+ * candidate is a cold page-in.
+ *
+ * Same shape and the same two edges as `pathProbeTimeoutMs`: never 0 (node
+ * reads `timeout: 0` as no timeout), never fractional (ERR_OUT_OF_RANGE, which
+ * `readBinaryVersion`'s catch would report as "no version" → a good binary
+ * judged stale). With no deadline armed — doctor, statusline, the launcher —
+ * it returns the unchanged 5 s default.
+ */
+function versionProbeTimeoutMs(remaining = require('./hook-fail-open').remainingMs) {
+  const left = remaining(VERSION_PROBE_TIMEOUT_MS);
+  const ms = left === null ? PATH_PROBE_MIN_MS : Math.floor(left);
+  return Math.max(ms, PATH_PROBE_MIN_MS);
+}
 const PLATFORM_PKG = `@sdsrs/code-graph-${PLATFORM}-${ARCH}`;
 
 /**
@@ -129,9 +157,13 @@ function globalNodeModulesCandidates() {
 
   // 4. Last resort: ask npm directly. Slow (~50-200ms) but most accurate when
   //    user has a non-standard prefix. Cached at the disk-cache layer above.
+  // Budget-aware like the sibling probes in this file (JS-23 / pre-ship review
+  // 2026-09-07): this runs on the same `findBinaryUncached()` chain, and every
+  // hook calls `findBinary()` before it consults its own budget. `remainingMs`
+  // returns the default unchanged when nothing armed a deadline.
   try {
     const npm = npmInvocation(['root', '-g'], {
-      timeout: 2000,
+      timeout: pathProbeTimeoutMs(),
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
     });
@@ -186,7 +218,9 @@ function isCachedBinaryFresh(cachedPath, pkgVersion, knownVersion) {
   // `knownVersion` lets the caller skip the `--version` spawn when the cache
   // entry already recorded it AND the file has not changed since — see
   // `readCacheEntry`. Absent, behaviour is exactly as before.
-  const cacheVer = knownVersion || readBinaryVersion(cachedPath);
+  // Clamped: this fires whenever the cache stamp mismatches — i.e. right after
+  // an auto-update, on the hook path (JS-23 / pre-ship review 2026-09-07).
+  const cacheVer = knownVersion || readBinaryVersion(cachedPath, { timeoutMs: versionProbeTimeoutMs() });
   if (!cacheVer) return true;
   return compareVersions(cacheVer, pkgVersion) >= 0;
 }
@@ -243,7 +277,9 @@ function writeCacheEntry(binPath) {
       CACHE_FILE,
       JSON.stringify({
         path: binPath,
-        version: readBinaryVersion(binPath) || null,
+        // Clamped: this is on the COLD-CACHE path, which is exactly the case
+        // JS-23 is about (pre-ship review 2026-09-07).
+        version: readBinaryVersion(binPath, { timeoutMs: versionProbeTimeoutMs() }) || null,
         stamp: binaryStamp(binPath),
       })
     );
@@ -396,13 +432,19 @@ function findPlatformBinary() {
  * gracefully on a slightly-old binary than on "offline", and the stale-binary
  * self-heal in auto-update.js re-downloads shortly anyway.
  */
-function createVersionGate(pkgVersion, { readVersion = readBinaryVersion } = {}) {
+function createVersionGate(
+  pkgVersion,
+  { readVersion = readBinaryVersion, probeTimeoutMs = versionProbeTimeoutMs } = {},
+) {
   let bestStale = null;
   return {
     consider(bin) {
       if (!isNativeBinary(bin)) return null;
       if (!pkgVersion) return bin;
-      const ver = readVersion(bin);
+      // Re-read per candidate, not once for the gate: the budget shrinks as the
+      // chain walks, and the point is that candidate six cannot still ask for a
+      // fresh 5 s (JS-23).
+      const ver = readVersion(bin, { timeoutMs: probeTimeoutMs() });
       if (!ver || compareVersions(ver, pkgVersion) >= 0) return bin;
       if (!bestStale || compareVersions(ver, bestStale.ver) > 0) bestStale = { bin, ver };
       return null;
@@ -554,6 +596,7 @@ module.exports = {
   detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
   pathProbeTimeoutMs, PATH_PROBE_TIMEOUT_MS, PATH_PROBE_MIN_MS,
+  versionProbeTimeoutMs, VERSION_PROBE_TIMEOUT_MS,
 };
 
 // Allow direct invocation for testing

package/claude-plugin/scripts/incremental-index.js

@@ -12,6 +12,24 @@ const { execFileSync } = require('child_process');
 const { findBinary } = require('./find-binary');
 const { hidden } = require('./proc-opts');
 
+// Default allowance for this hook's one child, spent through the hook budget
+// below. The PostToolUse deadline armed at the top of this file is 10 s.
+const CHILD_TIMEOUT_MS = 8000;
+
+/**
+ * How long the indexer child may run: the default when nothing armed a deadline
+ * (a test importing this module, a manual invocation), or whatever is LEFT of
+ * the PostToolUse budget. `null` means the budget is exhausted — do not run.
+ *
+ * JS-32: the child spent a literal 8 s no matter how much of the 10 s deadline
+ * `findBinary()` had already consumed, so a cold cache overran it and Claude
+ * Code killed the hook on the user's own edit. Exported because `runMain()`
+ * cannot be reached from a test without spawning the hook (JS-18's shape).
+ */
+function childBudgetMs() {
+  return require('./hook-fail-open').remainingMs(CHILD_TIMEOUT_MS);
+}
+
 // v0.21 — gated default-off. v0.18.0 added query-time freshness
 // (ensure_file_indexed) inside MCP tools that take a file_path arg, so a
 // PostToolUse hook spawning a fresh process on every Edit/Write was redundant
@@ -37,9 +55,14 @@ function runMain() {
   const bin = findBinary();
   if (!bin) return; // silent — binary not installed yet
 
+  // Read AFTER findBinary(): that chain is what eats the budget on a cold
+  // cache, and asking before it would hand the child an allowance nobody had.
+  const budget = childBudgetMs();
+  if (budget === null) return; // exhausted — the index waits for the next edit
+
   try {
     execFileSync(bin, ['incremental-index', '--quiet'], hidden({
-      timeout: 8000,
+      timeout: budget,
       stdio: ['pipe', 'pipe', 'pipe']
     }));
   } catch { /* timeout or error — silent for hook */ }
@@ -49,4 +72,4 @@ if (require.main === module) {
   runMain();
 }
 
-module.exports = { shouldRun };
+module.exports = { shouldRun, childBudgetMs, CHILD_TIMEOUT_MS };

package/claude-plugin/scripts/lifecycle.js

@@ -1616,8 +1616,18 @@ function uninstall({ purgeGlobal = false, unadoptAll = false, runNpm = defaultRu
     }
   }
 
-  // 6. Remove cache directory
-  try { fs.rmSync(CACHE_DIR, { recursive: true, force: true }); } catch { /* ok */ }
+  // 6. Remove cache directory — through `removeCacheResidue()`, not a bare
+  // rmSync (JS-17, audit 2026-09-07). Without `--unadopt-all` the sweep above
+  // does not run, so the registry is still NON-EMPTY here and a wholesale wipe
+  // strands every managed block — while step 8's own guidance, and `cli.js`,
+  // tell the user their next move is `--unadopt-all`, which then reads an
+  // absent registry and reports nothing to clean. `adoptedProjects` was
+  // captured at 5.5 for the RETURN value; that capture never protected the
+  // file. With `--unadopt-all` the sweep leaves the registry empty (or holding
+  // only projects whose CLAUDE.md could not be rewritten, which is exactly what
+  // must survive), and `removeCacheResidue` preserves only a non-empty one, so
+  // the clean case still leaves nothing behind.
+  try { removeCacheResidue(); } catch { /* ok */ }
 
   // 6.5. The shared tmp dir (cooldown flags, read-fanout state, interrupted
   // `update-*` staging). Nothing in it outlives an uninstall, and the periodic
@@ -1954,12 +1964,14 @@ function isPluginUninstalled(settings = readJson(settingsPath()) || {}) {
 // of which repos carry a managed CLAUDE.md block. Wiping it strands every block
 // — `uninstall({unadoptAll:true})` afterwards reads an empty registry, reports
 // `unadopted: []`, and the blocks stay in the user's repos with nothing left
-// that knows where they are. `uninstall()` captures the list before calling
-// here; `cleanupDisabledStatusline` does not, and by this function's own comment
-// that is the ONE path guaranteed to run after `/plugin uninstall`. So the
-// preservation belongs here, at the wipe, rather than at each caller — the same
-// "fix it at the shared layer, not per surface" the <external> query filter
-// needed.
+// that knows where they are. No caller can be trusted to protect it first:
+// `cleanupDisabledStatusline` cannot (it is the ONE path guaranteed to run after
+// a CC `/plugin uninstall`, and it has no list), and `uninstall()` did not —
+// it captured the list for its RETURN value and then wiped the file with a bare
+// rmSync, which is the JS-17 data loss (audit 2026-09-07); it routes through
+// here now. So the preservation belongs here, at the wipe, rather than at each
+// caller — the same "fix it at the shared layer, not per surface" the
+// <external> query filter needed.
 function removeCacheResidue() {
   // Path comes from adopt.js rather than a second spelling of the basename —
   // a literal here would silently stop matching the day adopt.js renames it,

package/claude-plugin/scripts/session-init.js

@@ -557,6 +557,35 @@ function verifyBinary() {
   return { available: true, binary };
 }
 
+/**
+ * The `unadopt` invocation to hand the user, spelled so their shell can run it.
+ *
+ * Issue #41: the reporter drives this plugin through `/plugin install` only and
+ * has no `code-graph-mcp` on PATH, so every remedy this hook printed spent a
+ * bare name their shell answers with "command not found".
+ *
+ * The obvious repair — print the binary `verifyBinary()` resolved — is WRONG,
+ * and a pre-ship review caught it as a net regression. `unadopt` is one of the
+ * three JS-dispatched subcommands (`main.rs`: doctor / adopt / unadopt): the
+ * native binary re-execs `claude-plugin/scripts/adopt.js`, which it locates via
+ * `$_FIND_BINARY_ROOT` or a path relative to its own exe. The plugin's cached
+ * binary at ~/.cache/code-graph/bin has no such neighbour, so
+ * `<cache>/code-graph-mcp unadopt` exits 1 with "adopt.js not found" —
+ * reproduced. Worse, npm-global users reach adopt.js today through the
+ * `bin/cli.js` shim that sets `_FIND_BINARY_ROOT`, so printing a resolved
+ * platform-package binary would BREAK a path that currently works.
+ *
+ * So point at the script itself. `adopt.js` carries its own
+ * `require.main === module` arm (`node adopt.js unadopt`), and this file is its
+ * neighbour in every install layout — plugin cache, npm package, dev checkout —
+ * because both are shipped inside `claude-plugin/scripts/`. `__dirname` is
+ * therefore the one locator that cannot be wrong. Quoted, since a plugin cache
+ * path under a home directory with a space is otherwise not runnable as printed.
+ */
+function unadoptCommand() {
+  return `node ${JSON.stringify(path.join(__dirname, 'adopt.js'))} unadopt`;
+}
+
 /**
  * Lightweight consistency checks — called from runSessionInit().
  * Returns an array of issue objects: { id, msg, fix }.
@@ -806,7 +835,7 @@ function runSessionInit({ source } = {}) {
         '[code-graph] Installed code-graph block into project CLAUDE.md (plugin install → knowing consent).\n' +
         '            Detail table: .claude/plugin_code_graph_mcp.md (generated; safe to gitignore)\n' +
         '            Opt out:    CODE_GRAPH_NO_AUTO_ADOPT=1 in ~/.claude/settings.json env\n' +
-        '            Reverse:    code-graph-mcp unadopt\n'
+        `            Reverse:    ${unadoptCommand()}\n`
       );
     }
     // `adopt()` has returned `registryRecorded` since it stopped throwing on a
@@ -820,7 +849,7 @@ function runSessionInit({ source } = {}) {
       process.stderr.write(
         '[code-graph] Note: this project could not be recorded in the adopted-projects registry,\n' +
         '            so `/plugin uninstall` will NOT strip the block from this CLAUDE.md.\n' +
-        '            Remove it by hand with `code-graph-mcp unadopt` before uninstalling.\n'
+        `            Remove it by hand with \`${unadoptCommand()}\` before uninstalling.\n`
       );
     }
   }
@@ -1090,7 +1119,7 @@ module.exports = {
   indexNeedsRevalidation,
   injectProjectMap,
   injectRecentImpact,
-  verifyBinary, missingBinaryMessage,
+  verifyBinary, missingBinaryMessage, unadoptCommand,
   consistencyCheck,
   runSessionInit,
   computeQuietHooks,

package/claude-plugin/scripts/user-prompt-context.js

@@ -8,6 +8,21 @@
 // would swallow the test's own failures.
 if (require.main === module) require('./hook-fail-open').installHookFailOpen('UserPromptSubmit');
 
+// Default per-child allowance, spent through the hook budget below.
+const CHILD_TIMEOUT_MS = 3000;
+
+/**
+ * How long ONE child of this hook may run: the default when nothing armed a
+ * deadline (a test importing this module), or whatever is LEFT of the
+ * UserPromptSubmit budget. `null` means the budget is exhausted — do not run.
+ *
+ * Exported so the three states are testable; `run()` below is a closure over
+ * the resolved binary and cannot be reached from a test (JS-18).
+ */
+function childBudgetMs() {
+  return require('./hook-fail-open').remainingMs(CHILD_TIMEOUT_MS);
+}
+
 // UserPromptSubmit hook: inject relevant code-graph RESULTS based on user's intent.
 // Strategy: PUSH structural context (not suggestions) that Grep/Read cannot provide.
 // This is a CODE INDEX — only inject structural code context (impact, overview, callgraph).
@@ -518,9 +533,18 @@ function runMain() {
   if (!binary) return;
 
   function run(args) {
+    // JS-18 (audit 2026-09-07): spend the UserPromptSubmit budget, don't ask
+    // for a fresh 3 s. This file armed a deadline at line 1 and then never
+    // consulted it — the literal here plus the `findBinary()` chain above ran
+    // outside it, so a cold cache had the hook killed by Claude Code and the
+    // user saw a hook error on THEIR prompt. `null` means the budget is gone:
+    // do not run (node reads `timeout: 0` as no timeout at all). Returning ''
+    // lands on the same "nothing to say" path as an empty result.
+    const budget = childBudgetMs();
+    if (budget === null) return '';
     return execFileSync(binary, args, hidden({
       cwd,
-      timeout: 3000,
+      timeout: budget,
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
       env: buildRunEnv(),
@@ -553,4 +577,4 @@ if (require.main === module) {
   runMain();
 }
 
-module.exports = { COOLDOWNS, shouldSkip, extractFilePaths, extractSymbols, detectIntents, scoreIntent, INTENT_PATTERNS, INTENT_THRESHOLD, determineQueryType, computeQuietHooks, STOP_WORDS, PLAIN_WORD_EXCLUDE, hasSymptom, SYMPTOM_PATTERNS, buildRunEnv };
+module.exports = { COOLDOWNS, shouldSkip, extractFilePaths, extractSymbols, detectIntents, scoreIntent, INTENT_PATTERNS, INTENT_THRESHOLD, determineQueryType, computeQuietHooks, STOP_WORDS, PLAIN_WORD_EXCLUDE, hasSymptom, SYMPTOM_PATTERNS, buildRunEnv, childBudgetMs, CHILD_TIMEOUT_MS };

package/claude-plugin/templates/code-graph-snapshot.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
       - name: Build snapshot
         run: |
-          npx -y -p @sdsrs/code-graph@0.139.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.141.0 code-graph-mcp snapshot create --out snapshot.db
           zstd -9 snapshot.db -o snapshot.db.zst
           mv snapshot.db.zst "code-graph-snapshot-${GITHUB_SHA:0:7}.db.zst"
       - name: Upload to release

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -49,6 +49,19 @@ type: reference
 > ToolSearch 加载），而 Bash 永远在线——真实编程夜（2026-06-12）观测到的全部
 > 转化都是 CLI 调用。结构化查询的最快路径是 Bash 直呼
 > `code-graph-mcp callgraph X / show X / overview <dir> / grep "pat" / impact X`。
+>
+> **裸名字不在 PATH 上时**（纯 `/plugin install`，没跑过 `npm i -g`）：插件自己
+> 下载的那份在 `~/.cache/code-graph/bin/code-graph-mcp`，本文下面所有查询类子命令
+> （callgraph / impact / overview / show / search / grep / refs / similar / deps /
+> dead-code / trace）都能直接用它跑；`npm i -g @sdsrs/code-graph` 则把裸名字放上
+> PATH（issue #41）。
+>
+> **三个例外**：`doctor` / `adopt` / `unadopt` 是 JS 派发的——二进制会去自己旁边
+> 找对应脚本（前者 `doctor.js`，后两者 `adopt.js`），而缓存目录里没有那些邻居，
+> 所以从缓存路径调它们会报 `<脚本名> not found`。直接跑脚本即可：
+> `node <插件目录>/claude-plugin/scripts/adopt.js unadopt`（SessionStart 的提示行
+> 会印出这台机器上的完整路径）、`node <插件目录>/claude-plugin/scripts/doctor.js`。
+>
 > `grep` 是 drop-in 替代：`-F` 字面 / `-i` / `-w` / `-l` / `-c` 计数 / `-t <lang>` 按语言筛 /
 > `-g <glob>` 路径过滤 / `-A/-B/-C N` 上下文 / `-M N` 行宽上限（默认 512，防长行刷屏）/
 > 多路径 / `-m 0` 取消每文件上限，退出码兼容 grep（0/1/2），召回达 git-grep 级

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.139.0",
+  "version": "0.141.0",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.139.0",
-    "@sdsrs/code-graph-linux-arm64": "0.139.0",
-    "@sdsrs/code-graph-darwin-x64": "0.139.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.139.0",
-    "@sdsrs/code-graph-win32-x64": "0.139.0"
+    "@sdsrs/code-graph-linux-x64": "0.141.0",
+    "@sdsrs/code-graph-linux-arm64": "0.141.0",
+    "@sdsrs/code-graph-darwin-x64": "0.141.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.141.0",
+    "@sdsrs/code-graph-win32-x64": "0.141.0"
   }
 }