@sdsrs/code-graph 0.150.0 → 0.152.0

package/README.md

@@ -427,7 +427,7 @@ skill does is also runnable by hand.
 - **Rust has no `inherits` edges** — the language has no class inheritance, so `impl Trait for Type` is recorded as `implements` and an `inherits`-filtered query returns empty for Rust.
 - **Kotlin/Swift interface conformance** is recorded as `inherits` (both use a single `: Type` grammar for base classes and protocols/interfaces), so `implements`-filtered queries return empty for these two languages.
 - **Cross-file dead-code detection** may false-positive a type whose only cross-file reference sits beyond the 4096-byte stored-content cap per node (documented accepted limitation, v0.97.1).
-- **Rust: borrowing a binding named `raw`** (`&raw`, `&raw[..]`, `&raw.field`) is misread by the pinned `tree-sitter-rust` 0.23 grammar as the start of the `&raw const` / `&raw mut` pointer operator, so the enclosing expression can be dropped from the index. `&mut raw`, `&self.raw` and the genuine `&raw const x` operator all parse correctly. The index reports the damage rather than hiding it, but only while indexing: a run prints `Syntax errors in <file> — symbols may be incomplete` per file plus an `N file(s) parsed with syntax errors` total. Nothing replays that afterwards — `health-check` and `doctor` both report a degraded index as healthy, so re-run the index to see the list. Workaround: rename the binding. Measured on this repo: 8 of 161 Rust files trip the warning (the total says 9 — a Markdown file trips the same counter for an unrelated reason), and one symbol is lost, `cmd_affected`. Recovery is usually partial rather than total: across a fixture covering every trigger shape, the surrounding functions and their call edges survived.
+- **Rust: borrowing a binding named `raw`** (`&raw`, `&raw[..]`, `&raw.field`) is misread by the pinned `tree-sitter-rust` 0.23 grammar as the start of the `&raw const` / `&raw mut` pointer operator, so the enclosing expression can be dropped from the index. `&mut raw`, `&self.raw` and the genuine `&raw const x` operator all parse correctly. The index reports the damage rather than hiding it. A run prints `Syntax errors in <file> — symbols may be incomplete` per file plus an `N file(s) parsed with syntax errors` total, and the verdict is stored with the index, so it survives the run: `health-check` names the files (`Parse: N file(s) indexed over a damaged parse`, plus `files_with_parse_errors` / `parse_error_files` under `--json`), `doctor` shows a `Parse` row, and the MCP `get_index_status` carries the same two fields. An incremental run over unrelated files does not clear it — only re-parsing the offending file, or deleting it, does. Workaround: rename the binding. Measured on this repo by indexing it fresh at v0.150.0: **9 of 163** tracked Rust files trip the warning, and the run's total says 10 — a Markdown file trips the same counter for an unrelated reason. The stored set names the same ten, which is the cheapest way to check this table has not drifted again: it is a reading of one tree at one commit, not a constant, and an earlier revision of this bullet carried 8/161/9 long after they stopped being true. Recovery is usually partial rather than total: across a fixture covering every trigger shape, the surrounding functions and their call edges survived.
 
 ## Team-shared graph snapshot
 

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

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

package/claude-plugin/scripts/cache-paths.js

@@ -32,6 +32,17 @@ const MANIFEST_FILE = path.join(CACHE_DIR, 'install-manifest.json');
 /** Inter-process install lock (see install-lock.js). */
 const INSTALL_LOCK_FILE = path.join(CACHE_DIR, 'install.lock');
 
+/**
+ * Where `find-binary.js` memoizes the resolved binary.
+ *
+ * It lived in find-binary.js, built from its own `os.homedir()` join — the JS-05
+ * shape this file's header describes, and the reason the teardown-gate audit
+ * missed it: the module that re-created the whole cache directory on the first
+ * cold resolution after an uninstall was not reachable from here, so an
+ * enumeration of cache writers done from this file came up one short.
+ */
+const BINARY_PATH_FILE = path.join(CACHE_DIR, 'binary-path');
+
 /**
  * Teardown tombstone — a SIBLING of CACHE_DIR, deliberately not a file inside
  * it.
@@ -120,6 +131,7 @@ module.exports = {
   UPDATE_STATE_FILE,
   MANIFEST_FILE,
   INSTALL_LOCK_FILE,
+  BINARY_PATH_FILE,
   UNINSTALL_TOMBSTONE_FILE,
   UNINSTALL_TOMBSTONE_TTL_MS,
   writeUninstallTombstone,

package/claude-plugin/scripts/doctor.js

@@ -10,7 +10,7 @@ const {
   settingsPath, surveyHookCoverage,
   installedGlobalPkgs, GLOBAL_INSTALL_MARKER, SHELL_PKG,
 } = require('./lifecycle');
-const { UPDATE_STATE_FILE } = require('./cache-paths');
+const { UPDATE_STATE_FILE, uninstallTombstoneActive } = require('./cache-paths');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 const { hidden } = require('./proc-opts');
 const { MAX_UPDATE_ATTEMPTS, GLOBAL_PKG_HEAL_MAX_ATTEMPTS, isBinaryHealExhausted, readState } = require('./auto-update');
@@ -177,6 +177,40 @@ function classifyHealthReport(hc) {
   // degradation (model missing/not loaded) instead of false-greening it.
   rows.push(classifyEmbeddings(hc));
   rows.push(classifyIntegrity(hc));
+  // Files indexed over a tree-sitter error recovery. They look exactly like
+  // clean ones at query time — the symbols that survived are real, the ones that
+  // did not are simply absent — so a thin result reads as "the code is thin".
+  // Additive and absent on a clean index, which is why this is `!== undefined`
+  // rather than a truthiness test that would also swallow a reported 0.
+  //
+  // Today's producer cannot send 0 — `health.rs` emits both fields only inside
+  // `if !parse_error_files.is_empty()` — so the distinction is a contract for
+  // the next producer, not an observed shape. Said plainly because the comment
+  // used to imply 0 arrives in practice, and because the test that pins it had
+  // to be added after a mutation to truthiness survived.
+  //
+  // No `fixId`, and `advisory: true`. The repair is editing the source, which
+  // is the user's to do — and on this very repository the cause is a pinned
+  // tree-sitter grammar bug the README documents as unfixed, so for 8 of 161
+  // Rust files there is no user action at all.
+  //
+  // The advisory flag is the load-bearing half. `runDoctor` counts
+  // `issues.filter(r => !r.advisory)` and `runDoctorCli` exits 1 when that is
+  // non-empty, so a plain warn with no fixId pins the exit code at 1 forever on
+  // any repo holding one bad file — including under `--check-only`, and
+  // including this one. Measured: same HOME, same project, add one file with
+  // unbalanced delimiters and reindex → exit 0 → 1; remove it and reindex →
+  // back to 0. The `Embeddings` row above carries the same flag for the same
+  // reason.
+  if (hc.files_with_parse_errors !== undefined) {
+    const named = Array.isArray(hc.parse_error_files) ? hc.parse_error_files : [];
+    const more = hc.files_with_parse_errors - named.length;
+    rows.push({
+      name: 'Parse', status: 'warn', advisory: true,
+      detail: `${hc.files_with_parse_errors} file(s) indexed over a damaged parse — `
+        + `symbols may be missing: ${named.join(', ')}${more > 0 ? `, and ${more} more` : ''}`,
+    });
+  }
   return rows;
 }
 
@@ -426,6 +460,21 @@ function runDiagnostics({ checkOnly = false } = {}) {
     : healthCheck();
   if (hookResult.healthy) {
     results.push({ name: 'Hooks', status: 'ok', detail: 'all paths valid' });
+  } else if (hookResult.skippedForTeardown) {
+    // healthCheck() declined the repair half because a teardown tombstone is
+    // standing. Advisory, and with no fixId, for the same reason
+    // `teardownRepairGuard` gives on the two arms below: these broken paths are
+    // the uninstall, not damage. Without `advisory` this would exit 1 for the
+    // life of the tombstone.
+    results.push({
+      name: 'Hooks',
+      status: 'warn',
+      advisory: true,
+      detail:
+        `${hookResult.issues.length} stale path(s) — NOT repaired: a teardown ran moments ago, ` +
+        `so these are the uninstalled state. If that was not intended: ` +
+        `node "${path.join(__dirname, 'lifecycle.js')}" install`,
+    });
   } else if (hookResult.repaired && hookResult.rebuiltFrom) {
     // The repair WORKED, but it worked by replacing an unusable settings.json
     // with a freshly built one — the user's model / env / permissions / own
@@ -662,6 +711,34 @@ function formatReport(results, { checkOnly = false } = {}) {
  * Returns true (and prints redirection) when this copy must NOT write config.
  * `relic` is injectable for tests.
  */
+/**
+ * Second gate on the same two settings-writing arms: is this the state a
+ * teardown just produced, rather than damage?
+ *
+ * `doctor` repairs by default and is the natural way to check an uninstall
+ * worked. Reproduced: a clean teardown, then one `doctor` with no flags, and
+ * all six hook entries were back in settings.json and the teardown tombstone
+ * was gone — re-opening the 41 MB auto-update race the tombstone closes, since
+ * `install({ clearTombstone: true })` erases the one marker the three gates in
+ * auto-update.js read.
+ *
+ * `relicRepairGuard` cannot cover this: it asks whether THIS copy is the active
+ * install, and returns false the moment `activeInstallPath()` is null — exactly
+ * the post-uninstall state.
+ *
+ * Bounded by the tombstone's own TTL, and deliberately: past the window a
+ * torn-down install is indistinguishable from one that was installed but never
+ * set up, which IS a repair case. `torndown` is injectable for tests.
+ */
+function teardownRepairGuard({ log = console.log, torndown = undefined } = {}) {
+  const isTorndown = torndown !== undefined ? torndown : uninstallTombstoneActive();
+  if (!isTorndown) return false;
+  log('  ⚠ A teardown ran moments ago — skipping settings repair.');
+  log('     Missing hooks ARE the uninstalled state here, not damage to repair.');
+  log(`     If that was not intended: node "${path.join(__dirname, 'lifecycle.js')}" install`);
+  return true;
+}
+
 function relicRepairGuard({ log = console.log, relic = undefined } = {}) {
   const { isStaleRelicContext, activeInstallPath } = require('./lifecycle');
   const isRelic = relic !== undefined ? relic : isStaleRelicContext();
@@ -1133,6 +1210,7 @@ function runRepairs(results, {
       case 'hooks-invalid': {
         console.log('\n  Repairing hooks...');
         if (relicRepairGuard()) break;
+        if (teardownRepairGuard()) break;
         const { install, scanForBrokenPaths } = require('./lifecycle');
         const installResult = install({ clearTombstone: true });
         // Diagnosis already ran install()+re-scan and the paths were STILL
@@ -1172,6 +1250,7 @@ function runRepairs(results, {
       case 'missing-hooks-in-settings': {
         console.log('\n  Registering code-graph hooks in settings.json...');
         if (relicRepairGuard()) break;
+        if (teardownRepairGuard()) break;
         const { install } = require('./lifecycle');
         const r = install({ clearTombstone: true });
         if (r.hooksRegistered) {
@@ -1289,7 +1368,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, binaryBrokenResolved, autoUpdateNoOpReason, autoUpdateLastError, silentFailureReason };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, teardownRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, binaryBrokenResolved, autoUpdateNoOpReason, autoUpdateLastError, silentFailureReason };
 
 // Shared by BOTH doctor entry points: `node doctor.js …` and `node lifecycle.js
 // doctor …`. It exists as one function because the first version of this guard

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

@@ -7,10 +7,18 @@ const os = require('os');
 const { readBinaryVersion, compareVersions } = require('./version-utils');
 const { npmInvocation } = require('./npm-exec');
 const { hidden } = require('./proc-opts');
+// The teardown predicate and this module's own cache path. cache-paths.js is
+// deliberately tiny and builtin-only for exactly this kind of hook-path
+// consumer, so the import costs nothing measurable.
+const { uninstallTombstoneActive, BINARY_PATH_FILE } = require('./cache-paths');
 
 const PLATFORM = os.platform();
 const ARCH = os.arch();
-const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path');
+// Still exported under this name — several modules and tests import
+// `CACHE_FILE` from here — but no longer spelled here. `cache-paths.js` owns
+// every `~/.cache/code-graph` file name, so an audit of who writes into that
+// directory can be done from one file instead of by grep.
+const CACHE_FILE = BINARY_PATH_FILE;
 const BINARY_NAME = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
 // PATH lookup bound (NEW-07). 2 s matches the sibling `npm root -g` probe; the
 // floor is what a budget-exhausted hook still gives it, because a `which` that
@@ -318,6 +326,22 @@ function readCacheEntry() {
 }
 
 function writeCacheEntry(binPath) {
+  // A teardown is in flight, and `path.dirname(CACHE_FILE)` IS the directory it
+  // just reclaimed — so the mkdir below re-creates it to hold a resolution
+  // nobody will read. auto-update.js guards its three writers the same way;
+  // this one was missed because it reaches CACHE_DIR through its own
+  // `os.homedir()` join instead of cache-paths.js, and it is the most-called of
+  // the four (every cold binary resolution on every hook). Measured: one
+  // findBinary() after a complete uninstall brought `~/.cache/code-graph/` back.
+  //
+  // Skipping costs a re-probe on the next call, not a wrong answer: the caller
+  // already has the resolved path, and this only memoizes it. Measured, so the
+  // trade is on the record rather than asserted: `findBinary()` runs ~5 ms warm
+  // (4-5 ms, n=5) against ~84 ms with the memo suppressed (71-93 ms, n=5) on a
+  // box where the binary resolves through a global npm install — roughly +79 ms
+  // per cold hook process, bounded by the tombstone's 5-minute TTL (pre-ship
+  // review).
+  if (uninstallTombstoneActive()) return;
   try {
     fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
     fs.writeFileSync(

package/claude-plugin/scripts/launcher-install.js

@@ -109,6 +109,36 @@ function installBinaryInBackground({
   lockPath = null,
 }) {
   let lock = null;
+  // DELIBERATELY outside the teardown tombstone, unlike every other writer that
+  // can re-create CACHE_DIR (auto-update.js gates its three; find-binary.js's
+  // cold-cache memo is gated too). The reason, corrected twice by pre-ship
+  // review — the first version of this comment got both the cost and the
+  // benefit wrong:
+  //
+  // COST, measured rather than assumed. `acquireLock` mkdirs the lock file's
+  // parent, which IS CACHE_DIR, so a teardown landing here does get the
+  // directory back. What lands in it is `install.lock` — **47 bytes**, measured
+  // with a tombstone standing in a sandbox HOME. Not the ~41 MB an earlier
+  // version of this comment claimed: the npm arm below installs into the npm
+  // global prefix, not CACHE_DIR.
+  //
+  // BENEFIT, and it is narrower than it looks. The tombstone cannot tell a
+  // teardown from a REINSTALL: `/plugin install` reaches `install()` through
+  // session-init, which by design does not pass `clearTombstone` (a record any
+  // concurrent session may erase protects nobody — see lifecycle.js's
+  // install()). So right after a legitimate reinstall the tombstone still
+  // stands and the cache is empty, and this path is what puts a binary back.
+  // But only its FIRST arm is: the GitHub fallback below spawns auto-update
+  // with --install-missing, and `downloadBinary` opens with its own
+  // `tombstoneActive()` check, so on a machine where `npm install -g` fails —
+  // offline registry, npm absent, EACCES on the global prefix, precisely why
+  // that fallback exists — the reinstall already gets nothing for the rest of
+  // the TTL. Gating here would extend that to the npm arm as well, which is the
+  // arm that currently works.
+  //
+  // So: 47 bytes of residue against the one reinstall path that survives the
+  // window. Not a crash either way — the missing-binary path already answers
+  // the handshake with `serveEmptyMcpStub`.
   if (lockPath) {
     lock = acquireLock(lockPath);
     if (!lock) {

package/claude-plugin/scripts/lifecycle.js

@@ -22,7 +22,7 @@ const MARKETPLACE_NAME = 'code-graph-mcp';
 // `MANIFEST_FILE` is module-private and always was, so nothing importable moved.
 const {
   CACHE_DIR, MANIFEST_FILE, INSTALL_LOCK_FILE,
-  writeUninstallTombstone, clearUninstallTombstone,
+  writeUninstallTombstone, clearUninstallTombstone, uninstallTombstoneActive,
 } = require('./cache-paths');
 // Bound for the `ps` fallback in getActiveCmdlines (pre-ship review 2026-09-06).
 // 2 s matches the other hook-path probes; the floor is what a budget-exhausted
@@ -1340,7 +1340,15 @@ function install({ reclaimStatusline = false, clearTombstone = false } = {}) {
   // So only the two genuinely user-initiated entry points pass true: the
   // `lifecycle.js install` CLI and doctor's repair pass. Everything automatic —
   // session-init's install reporting, healthCheck's repair — leaves it standing
-  // and lets the TTL expire it. The cost is that a reinstall inside the window
+  // and lets the TTL expire it.
+  //
+  // Doctor's half is now vestigial, and saying so beats leaving a reader to
+  // work it out: `teardownRepairGuard` returns before both of doctor's
+  // `install({ clearTombstone: true })` sites, so doctor can only ever clear a
+  // tombstone that has already expired — at which point there is nothing to
+  // clear. Kept rather than removed because a concurrent teardown can still
+  // write one between the guard check and the install, and because the flag is
+  // the honest statement of intent for that call site. The cost is that a reinstall inside the window
   // may skip one update check, which the spec already accepts; the install
   // itself supplies the binary.
   if (clearTombstone) clearUninstallTombstone();
@@ -1959,13 +1967,38 @@ function scanForBrokenPaths() {
   return issues;
 }
 
-function healthCheck() {
+function healthCheck({ torndown = uninstallTombstoneActive } = {}) {
   const issues = scanForBrokenPaths();
 
   if (issues.length === 0) {
     return { healthy: true, issues, repaired: false };
   }
 
+  // A teardown just ran: these broken paths ARE the uninstall, and the
+  // auto-repair below is an install().
+  //
+  // This is the second door to the same room. `doctor`'s two settings-writing
+  // repair arms are guarded, but `runDiagnostics` reaches HERE first on the
+  // default (repairing) path, and this call site sits in front of neither
+  // guard. Reproduced: sandbox HOME, plugin installed, all six hook commands
+  // repointed at a nonexistent dir, fresh tombstone standing, one `node
+  // doctor.js` — `Hooks ✅ 6 issue(s) auto-repaired`, settings.json back from
+  // six broken paths to zero, and doctor's own guard never printed. Guarding
+  // the repair arms while leaving the diagnosis free to install is a fix that
+  // only looks like one (pre-ship review, reviewer-reproduced).
+  //
+  // Placed in healthCheck rather than at doctor's call site so `lifecycle.js
+  // health` is covered by the same gate: both are "scan and auto-repair"
+  // entry points, and one of the two remembering is how this reappears.
+  //
+  // Honest return: `healthy: false` with `repaired: false` is exactly what the
+  // caller should render — the paths really are broken, and nothing fixed
+  // them. `skippedForTeardown` lets a caller say WHY instead of implying the
+  // repair was attempted and failed.
+  if (torndown()) {
+    return { healthy: false, issues, repaired: false, skippedForTeardown: true };
+  }
+
   // Attempt auto-repair, then re-scan to confirm the issues actually went
   // away. install() may legitimately fail to resolve a problem (binary path
   // permanently gone, registry corrupted, etc.) and the previous code lied

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.150.0 code-graph-mcp snapshot create --out snapshot.db
+          npx -y -p @sdsrs/code-graph@0.152.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.150.0",
+  "version": "0.152.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.150.0",
-    "@sdsrs/code-graph-linux-arm64": "0.150.0",
-    "@sdsrs/code-graph-darwin-x64": "0.150.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.150.0",
-    "@sdsrs/code-graph-win32-x64": "0.150.0"
+    "@sdsrs/code-graph-linux-x64": "0.152.0",
+    "@sdsrs/code-graph-linux-arm64": "0.152.0",
+    "@sdsrs/code-graph-darwin-x64": "0.152.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.152.0",
+    "@sdsrs/code-graph-win32-x64": "0.152.0"
   }
 }