@sdsrs/code-graph 0.74.4 → 0.74.6

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

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

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

@@ -263,8 +263,39 @@ function syncLifecycleConfig() {
 }
 
 /**
- * Check if the index is stale by comparing git HEAD timestamp vs index.db mtime.
- * If stale, spawn background incremental-index to refresh.
+ * Cheap probe for a rebuild reason that mtime/git can't see: an INDEX_VERSION
+ * mismatch (the on-disk index was built by an older extractor generation). Since
+ * P0, a reader (statusline `health-check`, `grep`) no longer wipes such an index —
+ * it serves the stale structural data and reports "rebuild pending" — so in a
+ * project where the MCP server isn't running, nothing else nudges a rebuild.
+ * health-check carries the verdict in `index_version_stale`. Best-effort: any
+ * failure → false (never force work off a bad probe).
+ */
+function indexNeedsRevalidation(bin, cwd) {
+  try {
+    let out;
+    try {
+      out = execFileSync(bin, ['health-check', '--format', 'json'],
+        { cwd, timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).toString();
+    } catch (e) {
+      // health-check exits non-zero on an unhealthy index but still writes JSON.
+      out = ((e && e.stdout) || '').toString();
+    }
+    return JSON.parse(out).index_version_stale === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether the index needs a background refresh and, if so, spawn a
+ * detached `incremental-index` (which revalidates: an indexer open wipes +
+ * rebuilds a version-stale index, then re-indexes all files).
+ *
+ * Two independent triggers:
+ *   1. git HEAD newer than index.db mtime — content drifted since last index.
+ *   2. INDEX_VERSION mismatch (post-upgrade) — see indexNeedsRevalidation.
+ *
  * Returns 'fresh' | 'refreshing' | 'skipped'.
  */
 function ensureIndexFresh() {
@@ -276,25 +307,28 @@ function ensureIndexFresh() {
   const dbPath = path.join(cwd, '.code-graph', 'index.db');
   if (!fs.existsSync(dbPath)) return 'skipped';
 
+  let needsRefresh = false;
+  // Trigger 1: git HEAD newer than index mtime.
   try {
     const dbMtime = fs.statSync(dbPath).mtimeMs;
-    // Compare with git HEAD commit timestamp
     const gitTs = parseInt(
       execSync('git log -1 --format=%ct', { cwd, timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
     ) * 1000;
-    if (gitTs <= dbMtime) return 'fresh';
+    if (gitTs > dbMtime) needsRefresh = true;
+  } catch { /* no git / not a repo — fall through to the version probe */ }
 
-    // Index is stale — run incremental-index in background
-    const child = spawn(bin, ['incremental-index', '--quiet'], {
-      cwd,
-      detached: true,
-      stdio: 'ignore',
-    });
-    if (child && typeof child.unref === 'function') child.unref();
-    return 'refreshing';
-  } catch {
-    return 'skipped';
-  }
+  // Trigger 2: INDEX_VERSION mismatch (only probe when mtime looked fresh).
+  if (!needsRefresh && indexNeedsRevalidation(bin, cwd)) needsRefresh = true;
+
+  if (!needsRefresh) return 'fresh';
+
+  const child = spawn(bin, ['incremental-index', '--quiet'], {
+    cwd,
+    detached: true,
+    stdio: 'ignore',
+  });
+  if (child && typeof child.unref === 'function') child.unref();
+  return 'refreshing';
 }
 
 /**
@@ -720,6 +754,7 @@ module.exports = {
   launchBackgroundAutoUpdate,
   syncLifecycleConfig,
   ensureIndexFresh,
+  indexNeedsRevalidation,
   injectProjectMap,
   injectRecentImpact,
   verifyBinary,

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

@@ -4,7 +4,26 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const path = require('path');
 
-const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, verifyBinary, computeQuietHooks, shouldInjectMap, shouldInjectRecentImpact, recentImpactWorthShowing, filterSourceFiles, parseGitStatusPaths, formatRecentImpact } = require('./session-init');
+const os = require('os');
+const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, indexNeedsRevalidation, verifyBinary, computeQuietHooks, shouldInjectMap, shouldInjectRecentImpact, recentImpactWorthShowing, filterSourceFiles, parseGitStatusPaths, formatRecentImpact } = require('./session-init');
+
+// Write an executable stub named `code-graph-mcp` that emits `json` to stdout on
+// `health-check` and exits with `exitCode`. Mirrors how the real binary behaves:
+// non-zero exit on an unhealthy index, but the JSON report still goes to stdout.
+function stubHealthBin(t, { json, exitCode = 0 }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-sessinit-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const bin = path.join(dir, 'code-graph-mcp');
+  const payload = String(json).replace(/'/g, `'\\''`);
+  fs.writeFileSync(bin, [
+    '#!/usr/bin/env bash',
+    `printf '%s' '${payload}'`,
+    `exit ${exitCode}`,
+    '',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+  return { bin, cwd: dir };
+}
 
 test('syncLifecycleConfig is exported as a callable helper', () => {
   assert.equal(typeof syncLifecycleConfig, 'function');
@@ -26,6 +45,36 @@ test('ensureIndexFresh returns skipped when no index exists', () => {
   }
 });
 
+test('indexNeedsRevalidation true when health-check reports index_version_stale', (t) => {
+  const { bin, cwd } = stubHealthBin(t, {
+    json: JSON.stringify({ healthy: true, nodes: 5, index_version_stale: true }),
+    exitCode: 0,
+  });
+  assert.equal(indexNeedsRevalidation(bin, cwd), true);
+});
+
+test('indexNeedsRevalidation false when index is current', (t) => {
+  const { bin, cwd } = stubHealthBin(t, {
+    json: JSON.stringify({ healthy: true, nodes: 5, index_version_stale: false }),
+    exitCode: 0,
+  });
+  assert.equal(indexNeedsRevalidation(bin, cwd), false);
+});
+
+test('indexNeedsRevalidation recovers JSON from a non-zero exit (unhealthy index)', (t) => {
+  // health-check exits 1 on an empty/unhealthy index but still emits the report.
+  const { bin, cwd } = stubHealthBin(t, {
+    json: JSON.stringify({ healthy: false, nodes: 0, index_version_stale: true }),
+    exitCode: 1,
+  });
+  assert.equal(indexNeedsRevalidation(bin, cwd), true);
+});
+
+test('indexNeedsRevalidation false on garbage output (never forces work off a bad probe)', (t) => {
+  const { bin, cwd } = stubHealthBin(t, { json: 'not json at all', exitCode: 0 });
+  assert.equal(indexNeedsRevalidation(bin, cwd), false);
+});
+
 test('verifyBinary returns available:true when binary is found and executable', () => {
   const result = verifyBinary();
   // In dev repo, binary should be found (target/release/code-graph-mcp)

package/claude-plugin/scripts/statusline.js

@@ -58,24 +58,67 @@ if (!bin) {
   process.exit(0);
 }
 
+// Render the standard health line from a parsed health-check report. An
+// unhealthy/empty index (healthy:false, 0 nodes) is a real, accurate state and
+// is distinct from "offline" \u2014 the binary ran fine, the index just has no data.
+function renderHealth(s) {
+  const icon = s.healthy ? '\u2713' : '\u2717';
+  let line = `code-graph: ${icon} ${s.nodes} nodes | ${s.files} files`;
+  // Surface vector-backfill progress so a structurally-complete but only
+  // partially-embedded index reads as "healthy and improving" (the embedding
+  // backfill is resumable and runs in the background), not as something stuck.
+  // Hidden when embeddings are complete, unavailable (no model), or there are no
+  // nodes yet \u2014 only the in-progress states add the suffix.
+  if (s.nodes > 0) {
+    if (s.embedding_status === 'partial' && typeof s.embedding_coverage_pct === 'number') {
+      line += ` | ${s.embedding_coverage_pct}% vec`;
+    } else if (s.embedding_status === 'pending') {
+      line += ' | vec pending';
+    }
+  }
+  // An index built by an older extractor generation is usable but a rebuild is
+  // owed (a background incremental-index revalidates it). Flag it so a stale
+  // index doesn't masquerade as fully current.
+  if (s.index_version_stale) line += ' | \u21bb rebuilding';
+  if (s.watching) line += ' | watching';
+  return line;
+}
+
+// A genuine report carries a boolean `healthy` field. Returns null for anything
+// that isn't a parseable report (empty string, crash banner, partial output).
+function parseReport(text) {
+  try {
+    const s = JSON.parse(text);
+    return (s && typeof s.healthy === 'boolean') ? s : null;
+  } catch { return null; }
+}
+
+// No usable report: the binary couldn't produce one (crashed / missing / schema
+// too new). A schema-version error means the resolved binary is OLDER than the
+// index it is reading \u2014 the classic post-update window where the new binary is
+// still downloading. That, or any pending update, is transient: show "updating"
+// so the user knows it self-heals, rather than the misleading "offline".
+function statusUnavailable(errText) {
+  const binaryOutdated = /schema version/i.test(errText || '');
+  return (binaryOutdated || updatePending()) ? 'code-graph: \u21bb updating' : 'code-graph: offline';
+}
+
+let report = null;
+let errText = '';
 try {
-  const out = execFileSync(bin, ['health-check', '--format', 'json'], {
+  report = parseReport(execFileSync(bin, ['health-check', '--format', 'json'], {
     timeout: 3000,
     stdio: ['pipe', 'pipe', 'pipe']
-  }).toString().trim();
-  const s = JSON.parse(out);
-  const icon = s.healthy ? '\u2713' : '\u2717';
-  process.stdout.write(
-    `code-graph: ${icon} ${s.nodes} nodes | ${s.files} files` +
-    (s.watching ? ' | watching' : '')
-  );
+  }).toString());
 } catch (e) {
-  // A schema-too-new error means the resolved binary is OLDER than the index it
-  // is reading \u2014 the classic post-update window where the new binary is still
-  // downloading. That, or any pending update, is transient: show "updating" so
-  // the user knows it self-heals, rather than the misleading "offline".
-  const errOut = ((e && (e.stderr || e.stdout)) || '').toString();
-  const binaryOutdated = /schema version/i.test(errOut);
-  process.stdout.write(
-    (binaryOutdated || updatePending()) ? 'code-graph: \u21bb updating' : 'code-graph: offline');
+  // health-check exits NON-ZERO on an unhealthy/empty index but still writes the
+  // full JSON report to stdout. The binary ran fine \u2014 recover the report from the
+  // error object so an empty index shows "\u2717 0 nodes" rather than a bogus "offline".
+  report = parseReport(((e && e.stdout) || '').toString());
+  // Scan BOTH streams for the schema marker: the binary writes it to stderr, but
+  // an empty stderr Buffer is truthy, so `stderr || stdout` would never fall
+  // through — concatenate instead of short-circuiting.
+  errText = [(e && e.stderr) || '', (e && e.stdout) || ''].map(String).join('\n');
 }
+
+process.stdout.write(report ? renderHealth(report) : statusUnavailable(errText));

package/claude-plugin/scripts/statusline.test.js

@@ -0,0 +1,166 @@
+'use strict';
+// statusline.js renders code-graph health into the Claude Code status line.
+// The states are easy to confuse, so each is pinned here with a stub binary:
+//
+//   ✓/✗ N nodes | M files   — health-check produced a report (exit 0 OR exit 1)
+//   ↻ updating              — no report + (schema-version error OR pending update)
+//   offline                 — no report + genuine failure, nothing pending
+//
+// The critical regression this guards: health-check exits NON-ZERO on an
+// empty/unhealthy index but still emits the full JSON report. statusline must
+// render that report ("✗ 0 nodes"), NOT collapse it into "offline".
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STATUSLINE = path.join(__dirname, 'statusline.js');
+
+function mkHome(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-statusline-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+// Write an executable shell stub named `code-graph-mcp` (find-binary's
+// isNativeBinary requires that exact basename) and register it in the binary
+// cache so findBinary() returns it before any dev/platform discovery.
+//   --version           → prints `version` (must be >= pkg version to be "fresh")
+//   health-check ...    → prints `report` to stdout, exits with `exitCode`
+function installStubBinary(home, { report, stderr = '', exitCode = 0, version = '9.9.9' }) {
+  const binDir = path.join(home, 'stub-bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  const binPath = path.join(binDir, 'code-graph-mcp');
+  const sh = (s) => String(s).replace(/'/g, `'\\''`);
+  const payload = typeof report === 'string' ? report : JSON.stringify(report);
+  const lines = [
+    '#!/usr/bin/env bash',
+    'if [ "$1" = "--version" ]; then',
+    `  echo "${version}"; exit 0`,
+    'fi',
+  ];
+  if (payload) lines.push(`printf '%s' '${sh(payload)}'`);
+  if (stderr) lines.push(`printf '%s' '${sh(stderr)}' >&2`);
+  lines.push(`exit ${exitCode}`, '');
+  fs.writeFileSync(binPath, lines.join('\n'));
+  fs.chmodSync(binPath, 0o755);
+
+  const cacheDir = path.join(home, '.cache', 'code-graph');
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(path.join(cacheDir, 'binary-path'), binPath);
+  return binPath;
+}
+
+function setUpdateState(home, state) {
+  const cacheDir = path.join(home, '.cache', 'code-graph');
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(path.join(cacheDir, 'update-state.json'), JSON.stringify(state));
+}
+
+// Run statusline.js in `projectDir` (must contain .code-graph/index.db) with a
+// sandboxed HOME, and return its stdout. PATH retains bash for the stub.
+function runStatusline(home, projectDir) {
+  return execFileSync('node', [STATUSLINE], {
+    cwd: projectDir,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  }).trim();
+}
+
+function mkProject(home) {
+  const dir = path.join(home, 'project');
+  const cg = path.join(dir, '.code-graph');
+  fs.mkdirSync(cg, { recursive: true });
+  fs.writeFileSync(path.join(cg, 'index.db'), 'stub'); // existence is all statusline checks
+  return dir;
+}
+
+test('healthy index → ✓ with node/file counts', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: true, nodes: 3145, files: 205, watching: true },
+    exitCode: 0,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✓ 3145 nodes | 205 files | watching');
+});
+
+test('empty index, health-check EXIT 1 with JSON → ✗ 0 nodes (not offline)', (t) => {
+  // The core regression: non-zero exit must not mask a valid report.
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: false, nodes: 0, files: 0, watching: false },
+    exitCode: 1,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✗ 0 nodes | 0 files');
+});
+
+test('no report + update pending → updating', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, { report: 'boom', exitCode: 1 });
+  setUpdateState(home, { updateAvailable: true });
+  assert.equal(runStatusline(home, project), 'code-graph: ↻ updating');
+});
+
+test('schema-version error on stderr (no report) → updating', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  // The binary writes schema errors to stderr; no parseable report on stdout.
+  installStubBinary(home, {
+    report: '',
+    stderr: 'Error: Database schema version v9 is newer than supported v8',
+    exitCode: 1,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ↻ updating');
+});
+
+test('genuine crash (no report, nothing pending) → offline', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, { report: 'segfault, core dumped', exitCode: 139 });
+  assert.equal(runStatusline(home, project), 'code-graph: offline');
+});
+
+test('partial embeddings show vector coverage', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: true, nodes: 14119, files: 922, embedding_status: 'partial', embedding_coverage_pct: 60 },
+    exitCode: 0,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✓ 14119 nodes | 922 files | 60% vec');
+});
+
+test('pending embeddings show "vec pending"', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: true, nodes: 14119, files: 922, embedding_status: 'pending', embedding_coverage_pct: 0 },
+    exitCode: 0,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✓ 14119 nodes | 922 files | vec pending');
+});
+
+test('complete embeddings add no vector suffix', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: true, nodes: 14119, files: 922, embedding_status: 'complete', embedding_coverage_pct: 100 },
+    exitCode: 0,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✓ 14119 nodes | 922 files');
+});
+
+test('version-stale index shows rebuilding marker', (t) => {
+  const home = mkHome(t);
+  const project = mkProject(home);
+  installStubBinary(home, {
+    report: { healthy: true, nodes: 14119, files: 922, embedding_status: 'complete', index_version_stale: true },
+    exitCode: 0,
+  });
+  assert.equal(runStatusline(home, project), 'code-graph: ✓ 14119 nodes | 922 files | ↻ rebuilding');
+});

package/package.json

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