@sdsrs/code-graph 0.24.1 → 0.25.1

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

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

package/claude-plugin/hooks/hooks.json

@@ -24,6 +24,16 @@
             "timeout": 4
           }
         ]
+      },
+      {
+        "matcher": "tool == \"Bash\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-grep-guide.js\"",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -87,13 +87,33 @@ function isNativeBinary(candidate) {
   }
 }
 
+/**
+ * Decide whether a cached binary path is fresh enough to skip the full
+ * discovery walk. Matches the auto-update cache logic at ~:185-188 —
+ * cache wins only when its binary's version >= pkg version. Without this
+ * check, a stale cache entry (e.g. dev checkout's `bin/code-graph-mcp`
+ * recorded once, then never refreshed) shadows newer auto-update or
+ * platform-pkg binaries forever (see mem #8454).
+ *
+ * Permissive on unknown values: missing pkg version or unreadable binary
+ * version → trust cache (don't refuse the only path we know about).
+ */
+function isCachedBinaryFresh(cachedPath, pkgVersion) {
+  if (!isNativeBinary(cachedPath)) return false;
+  if (!pkgVersion) return true;
+  const cacheVer = readBinaryVersion(cachedPath);
+  if (!cacheVer) return true;
+  return compareVersions(cacheVer, pkgVersion) >= 0;
+}
+
 /**
  * Locate the code-graph-mcp binary using multiple strategies.
  * Results are cached to disk so repeated calls (e.g. per-hook) are fast.
  *
  * Priority:
- *   cache (if valid) → dev-mode (target/release) → auto-update cache
- *   → platform npm pkg → bundled (bin/) → cargo install → PATH → npx cache
+ *   cache (if valid + version >= pkg) → dev-mode (target/release) →
+ *   auto-update cache → platform npm pkg → bundled (bin/) →
+ *   cargo install → PATH → npx cache
  *
  * Returns the absolute path or null if not found.
  */
@@ -101,7 +121,7 @@ function findBinary() {
   // Try disk cache first (avoids spawning `which` on hot paths)
   try {
     const cached = fs.readFileSync(CACHE_FILE, 'utf8').trim();
-    if (isNativeBinary(cached)) return cached;
+    if (isCachedBinaryFresh(cached, getPackageVersion())) return cached;
     if (cached) clearCache();
   } catch { /* no cache or stale */ }
 
@@ -242,7 +262,7 @@ function clearCache() {
 module.exports = {
   findBinary, findBinaryUncached, clearCache,
   globalNodeModulesCandidates, findPlatformBinary,
-  getPackageVersion, compareVersions,
+  getPackageVersion, compareVersions, isCachedBinaryFresh,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
 };
 

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

@@ -6,7 +6,7 @@ const os = require('os');
 const path = require('path');
 
 const { globalNodeModulesCandidates, findPlatformBinary, BINARY_NAME,
-        compareVersions, getPackageVersion } = require('./find-binary');
+        compareVersions, getPackageVersion, isCachedBinaryFresh } = require('./find-binary');
 
 function mkDir(t, prefix) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -145,3 +145,77 @@ test('getPackageVersion reads root package.json', () => {
   const v = getPackageVersion();
   assert.match(v, /^\d+\.\d+\.\d+$/, `expected semver-ish, got: ${v}`);
 });
+
+// ─── isCachedBinaryFresh: disk cache version-check (mem #8454) ────────────
+//
+// Builds a fake binary that responds to `--version` with a controllable
+// string. process.execPath (node itself) won't do — we need a binary
+// whose --version line we control. Smallest approach: shell wrapper.
+
+function buildFakeBinary(t, versionLine) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cgmcp-fake-bin-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const binPath = path.join(dir, BINARY_NAME);
+  // readBinaryVersion parses "code-graph-mcp X.Y.Z" via the binary's first
+  // stdout line on `--version`. Shell wrapper is simpler than compiling.
+  const script = process.platform === 'win32'
+    ? `@echo off\r\necho ${versionLine}\r\n`
+    : `#!/bin/sh\necho '${versionLine}'\n`;
+  fs.writeFileSync(binPath, script);
+  if (process.platform !== 'win32') fs.chmodSync(binPath, 0o755);
+  return binPath;
+}
+
+test('isCachedBinaryFresh: cache binary version >= pkg → fresh', (t) => {
+  const bin = buildFakeBinary(t, 'code-graph-mcp 9.9.9');
+  assert.equal(isCachedBinaryFresh(bin, '0.25.0'), true);
+});
+
+test('isCachedBinaryFresh: cache binary version equals pkg → fresh', (t) => {
+  const bin = buildFakeBinary(t, 'code-graph-mcp 0.25.0');
+  assert.equal(isCachedBinaryFresh(bin, '0.25.0'), true);
+});
+
+test('isCachedBinaryFresh: cache binary version < pkg → stale (THE BUG)', (t) => {
+  // Reproduces mem #8454: cache pointed at bin/code-graph-mcp v0.5.28
+  // while pkg was v0.25.0 → cache was returned silently with no
+  // version-check, shadowing the installed 0.25.0 platform binary.
+  // After this fix, returns false → caller clears cache + falls through.
+  const bin = buildFakeBinary(t, 'code-graph-mcp 0.5.28');
+  assert.equal(isCachedBinaryFresh(bin, '0.25.0'), false);
+});
+
+test('isCachedBinaryFresh: missing pkg version → permissive (trust cache)', (t) => {
+  // Caller couldn't read package.json; refusing the cache would leave us
+  // with nothing. Better to trust the one path we have.
+  const bin = buildFakeBinary(t, 'code-graph-mcp 0.5.28');
+  assert.equal(isCachedBinaryFresh(bin, null), true);
+  assert.equal(isCachedBinaryFresh(bin, ''), true);
+});
+
+test('isCachedBinaryFresh: unreadable cache binary version → permissive', (t) => {
+  // Old binary that doesn't support `--version`, or output we can't
+  // parse. Same permissive path as missing pkg version.
+  const bin = buildFakeBinary(t, 'whatever garbage no semver here');
+  assert.equal(isCachedBinaryFresh(bin, '0.25.0'), true);
+});
+
+test('isCachedBinaryFresh: cache path does not exist → not fresh', () => {
+  assert.equal(isCachedBinaryFresh('/nonexistent/path/code-graph-mcp', '0.25.0'), false);
+});
+
+test('isCachedBinaryFresh: empty/null cache path → not fresh', () => {
+  assert.equal(isCachedBinaryFresh('', '0.25.0'), false);
+  assert.equal(isCachedBinaryFresh(null, '0.25.0'), false);
+  assert.equal(isCachedBinaryFresh(undefined, '0.25.0'), false);
+});
+
+test('isCachedBinaryFresh: file basename mismatch → not fresh', (t) => {
+  // realpathSync.basename check inside isNativeBinary — wrong name = not ours.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cgmcp-wrongname-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const wrongName = path.join(dir, 'other-tool');
+  fs.writeFileSync(wrongName, '#!/bin/sh\necho wrong\n');
+  if (process.platform !== 'win32') fs.chmodSync(wrongName, 0o755);
+  assert.equal(isCachedBinaryFresh(wrongName, '0.25.0'), false);
+});

package/claude-plugin/scripts/pre-grep-guide.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict';
+// PreToolUse(Bash) hook: detect raw `grep`/`rg`/`ag` on the indexed source tree
+// and suggest code-graph CLI alternatives. Closes the "Bash comfort zone" leak —
+// pre-training bias has Claude reach for `grep -rn` ~13× more than the indexed
+// CLI on bash-heavy days (15-day baseline: 429 raw grep vs 191 functional CLI).
+//
+// Fires when ALL conditions met:
+//   1. Command HEAD is grep/rg/ag (NOT piped — pipe-greps are output filters)
+//   2. Args include an indexed source-tree path (src/ tests/ lib/ scripts/ ...)
+//   3. Not searching only a config/lockfile (Cargo.toml/.gitignore/*.md/*.json)
+//   4. Command doesn't already invoke code-graph-mcp (no double-suggest)
+//   5. .code-graph/index.db exists in CWD
+//   6. Same command-hash not hinted within last 60s (per-command cooldown)
+//
+// Exits silently otherwise — zero noise for build greps, log filters, config
+// lookups, or the rare legitimate use of raw grep on indexed source.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// --- Pure logic (testable) ---
+
+const GREP_HEAD = /^\s*(?:env\s+\S+=\S+\s+)*(grep|rg|ag)\b/;
+const SRC_PATH = /(?:^|\s|["'])(src|tests|lib|scripts|claude-plugin|tools|pkg|cmd|internal|app|components?|server|client|crates|packages)\//;
+const PIPE_INTO_GREP = /\|\s*(?:grep|rg|ag)\b/;
+const CG_INVOKED = /\bcode-graph-mcp\b/;
+// A file argument that ends in a config/lockfile extension AND no source-tree
+// path appears elsewhere → grep is searching config, not code.
+const CONFIG_TARGET_ONLY =
+  /(?:^|\s)[^\s|<>]*\.(toml|md|json|yml|yaml|lock|txt|cfg|env|gitignore|properties)(?:\s|$)/i;
+
+function shouldHint(cmd) {
+  if (!cmd || typeof cmd !== 'string') return false;
+  if (cmd.length > 1000) return false;             // sanity — oversize commands are noise
+  if (CG_INVOKED.test(cmd)) return false;          // already using cg
+  if (PIPE_INTO_GREP.test(cmd)) return false;      // `cargo test | grep FAILED` is output filter
+  if (!GREP_HEAD.test(cmd)) return false;          // not a search command
+  if (!SRC_PATH.test(cmd)) return false;           // not against indexed source tree
+  // If a config file appears AND no source path remains after stripping it, skip.
+  if (CONFIG_TARGET_ONLY.test(cmd)) {
+    const stripped = cmd.replace(CONFIG_TARGET_ONLY, ' ');
+    if (!SRC_PATH.test(stripped)) return false;
+  }
+  return true;
+}
+
+function commandHash(cmd) {
+  return crypto.createHash('sha1').update(cmd).digest('hex').slice(0, 12);
+}
+
+function isOnCooldown(cmd, now = Date.now(), windowMs = 60000) {
+  const flag = path.join(os.tmpdir(), `.code-graph-bash-${commandHash(cmd)}`);
+  try {
+    return now - fs.statSync(flag).mtimeMs < windowMs;
+  } catch { return false; }
+}
+
+function markCooldown(cmd) {
+  const flag = path.join(os.tmpdir(), `.code-graph-bash-${commandHash(cmd)}`);
+  try { fs.writeFileSync(flag, ''); } catch { /* ok */ }
+}
+
+function buildHint() {
+  // Terse, no banner spam. Single message budget ~600 bytes.
+  return [
+    '[code-graph] Raw `grep`/`rg` on indexed source — consider AST-aware equivalents:',
+    '  • code-graph-mcp grep "<pat>" <path>          # grep + containing fn/module per hit',
+    '  • code-graph-mcp ast-search "<pat>" --type fn # filter by type/returns/params',
+    '  • code-graph-mcp callgraph SYMBOL             # callers + callees, repo-wide',
+    '  • code-graph-mcp show SYMBOL                  # one symbol: signature + source',
+    'Repo-wide index (LSP only sees open files). Skip this hint if you specifically need raw-text regex.',
+  ].join('\n');
+}
+
+// --- Main execution (only when run directly) ---
+
+// Kill switch: matches user-prompt-context.js convention. =1 forces silence
+// even when the rest of the hook tier is noisy. Default (unset) is noisy here
+// — this hook only fires on raw grep against the source tree, which is the
+// exact comfort-zone leak it was designed to catch.
+function isSilenced(env = process.env) {
+  return env.CODE_GRAPH_QUIET_HOOKS === '1';
+}
+
+function runMain() {
+  if (isSilenced()) return;
+  const cwd = process.cwd();
+  const dbPath = path.join(cwd, '.code-graph', 'index.db');
+  if (!fs.existsSync(dbPath)) return;  // no index — no hint
+
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
+  } catch { return; }
+
+  const cmd = (input.tool_input && input.tool_input.command) || '';
+  if (!shouldHint(cmd)) return;
+  if (isOnCooldown(cmd)) return;
+
+  markCooldown(cmd);
+  process.stdout.write(buildHint() + '\n');
+}
+
+if (require.main === module) {
+  runMain();
+}
+
+module.exports = {
+  shouldHint,
+  buildHint,
+  commandHash,
+  isOnCooldown,
+  markCooldown,
+  isSilenced,
+};

package/claude-plugin/scripts/pre-grep-guide.test.js

@@ -0,0 +1,195 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { shouldHint, buildHint, commandHash, isSilenced } = require('./pre-grep-guide');
+
+// ── Should fire: bare grep/rg/ag on indexed source tree ─────────────
+
+test('shouldHint: grep -rn on src/', () => {
+  assert.equal(shouldHint('grep -rn "fn fts5_search" src/storage/'), true);
+});
+
+test('shouldHint: rg on tests/', () => {
+  assert.equal(shouldHint('rg "expand_acronym" tests/'), true);
+});
+
+test('shouldHint: grep -n on single file in src/', () => {
+  assert.equal(shouldHint('grep -n "fn split_identifier" src/search/tokenizer.rs'), true);
+});
+
+test('shouldHint: grep -rn on claude-plugin/', () => {
+  assert.equal(shouldHint('grep -rn "computeQuietHooks" claude-plugin/scripts/'), true);
+});
+
+test('shouldHint: grep with alternation against src/', () => {
+  assert.equal(shouldHint('grep -rn "set_hook\\|panic_handler" src/main.rs src/lib.rs'), true);
+});
+
+test('shouldHint: grep with stderr redirect + head pipe (still a source search)', () => {
+  // head/tail/sort pipes don't disqualify — the SEARCH operation is grep on src/
+  assert.equal(shouldHint('grep -rn "fn fts5_search\\|MATCH" src/storage/ 2>&1 | head -10'), true);
+});
+
+test('shouldHint: ag on lib/', () => {
+  assert.equal(shouldHint('ag "TODO" lib/'), true);
+});
+
+test('shouldHint: env-prefixed grep on src/', () => {
+  assert.equal(shouldHint('env LANG=C grep -rn "Foo" src/'), true);
+});
+
+// ── Should NOT fire: pipe-grep (output filter, not search) ──────────
+
+test('shouldHint: pipe-grep on cargo test output', () => {
+  assert.equal(shouldHint('cargo test 2>&1 | grep "test result"'), false);
+});
+
+test('shouldHint: pipe-grep with -E flag', () => {
+  assert.equal(shouldHint("cargo test --no-default-features 2>&1 | grep -E 'test result|FAILED'"), false);
+});
+
+test('shouldHint: pipe-rg', () => {
+  assert.equal(shouldHint("cargo build 2>&1 | rg 'warning|error'"), false);
+});
+
+test('shouldHint: pipe-grep with src/ in pattern (still output filter)', () => {
+  assert.equal(shouldHint("cargo build 2>&1 | grep 'src/main.rs'"), false);
+});
+
+// ── Should NOT fire: already using code-graph-mcp ───────────────────
+
+test('shouldHint: code-graph-mcp grep itself', () => {
+  assert.equal(shouldHint('code-graph-mcp grep "fn parse" src/'), false);
+});
+
+test('shouldHint: pipe through code-graph-mcp', () => {
+  assert.equal(shouldHint('code-graph-mcp show foo | grep src/'), false);
+});
+
+// ── Should NOT fire: not source-tree paths ──────────────────────────
+
+test('shouldHint: grep on Cargo.toml only', () => {
+  assert.equal(shouldHint('grep "^version" Cargo.toml'), false);
+});
+
+test('shouldHint: grep -i docs on .gitignore', () => {
+  assert.equal(shouldHint('grep -i docs .gitignore'), false);
+});
+
+test('shouldHint: grep on package.json', () => {
+  assert.equal(shouldHint('grep "version" package.json'), false);
+});
+
+test('shouldHint: grep on a markdown changelog', () => {
+  assert.equal(shouldHint('grep "v0.24" CHANGELOG.md'), false);
+});
+
+// ── Should NOT fire: not search tools ───────────────────────────────
+
+test('shouldHint: ls src/', () => {
+  assert.equal(shouldHint('ls src/storage/'), false);
+});
+
+test('shouldHint: cat src/main.rs', () => {
+  assert.equal(shouldHint('cat src/main.rs'), false);
+});
+
+test('shouldHint: git log on src/', () => {
+  assert.equal(shouldHint('git log --oneline -10 src/'), false);
+});
+
+test('shouldHint: find on src/ (file path tool, not content search)', () => {
+  // find is path-based, not pattern-based. Out of scope for this hook.
+  assert.equal(shouldHint('find src/ -name "*.rs"'), false);
+});
+
+// ── Edge cases ──────────────────────────────────────────────────────
+
+test('shouldHint: empty command', () => {
+  assert.equal(shouldHint(''), false);
+});
+
+test('shouldHint: non-string input', () => {
+  assert.equal(shouldHint(null), false);
+  assert.equal(shouldHint(undefined), false);
+  assert.equal(shouldHint(42), false);
+});
+
+test('shouldHint: oversize command (>1000 chars)', () => {
+  assert.equal(shouldHint('grep -rn "x" src/ ' + 'y'.repeat(1100)), false);
+});
+
+// ── Hint content ────────────────────────────────────────────────────
+
+test('buildHint: includes all four code-graph subcommands', () => {
+  const out = buildHint();
+  assert.match(out, /code-graph-mcp grep/);
+  assert.match(out, /code-graph-mcp ast-search/);
+  assert.match(out, /code-graph-mcp callgraph/);
+  assert.match(out, /code-graph-mcp show/);
+});
+
+test('buildHint: stays under 700-byte budget (~175 tokens)', () => {
+  const out = buildHint();
+  assert.ok(out.length < 700, `hint length ${out.length} exceeds budget`);
+});
+
+test('buildHint: mentions repo-wide / LSP boundary', () => {
+  assert.match(buildHint(), /Repo-wide index|LSP/);
+});
+
+// ── Cooldown hash ───────────────────────────────────────────────────
+
+test('commandHash: deterministic + 12-char', () => {
+  const h1 = commandHash('grep -rn "foo" src/');
+  const h2 = commandHash('grep -rn "foo" src/');
+  assert.equal(h1, h2);
+  assert.equal(h1.length, 12);
+});
+
+test('commandHash: different commands → different hashes', () => {
+  assert.notEqual(commandHash('grep -rn "foo" src/'), commandHash('grep -rn "bar" src/'));
+});
+
+// ── Kill switch ─────────────────────────────────────────────────────
+
+test('isSilenced: default (no env) → not silenced (noisy)', () => {
+  assert.equal(isSilenced({}), false);
+});
+
+test('isSilenced: CODE_GRAPH_QUIET_HOOKS=1 → silenced', () => {
+  assert.equal(isSilenced({ CODE_GRAPH_QUIET_HOOKS: '1' }), true);
+});
+
+test('isSilenced: CODE_GRAPH_QUIET_HOOKS=0 → not silenced', () => {
+  assert.equal(isSilenced({ CODE_GRAPH_QUIET_HOOKS: '0' }), false);
+});
+
+test('isSilenced: VERBOSE_HOOKS=1 alone → not silenced (noisy by default already)', () => {
+  // pre-grep-guide is noisy-by-default; VERBOSE is irrelevant here.
+  assert.equal(isSilenced({ CODE_GRAPH_VERBOSE_HOOKS: '1' }), false);
+});
+
+// ── Regression cases from real session telemetry (2026-05-11) ───────
+
+test('regression: grep -n "Error\\|anyhow" src/main.rs (sess 5052e2a1)', () => {
+  assert.equal(shouldHint('grep -n "Error\\|anyhow\\|context" src/main.rs'), true);
+});
+
+test('regression: grep -rn "fn fts5_search" src/storage/ (sess 25fa8050)', () => {
+  assert.equal(shouldHint('grep -rn "fn fts5_search\\|MATCH\\|fts.*tokenize" src/storage/'), true);
+});
+
+test('regression: grep multi-extension MEMORY.md tag search (sess 5052e2a1)', () => {
+  // This one targets MEMORY.md files — should NOT fire because the --include flags
+  // are for non-source extensions and there's no `src/` etc. in the args.
+  assert.equal(shouldHint("grep -rn 'callgraph, impact' --include='*.md'"), false);
+});
+
+test('regression: cargo test pipe filter NOT fires (sess 45691293)', () => {
+  assert.equal(shouldHint('cargo test --no-default-features 2>&1 | grep -E "test result|FAILED|error\\[" | tail -15'), false);
+});
+
+test('regression: grep -m1 "^version" Cargo.toml NOT fires', () => {
+  assert.equal(shouldHint('grep -m1 "^version" Cargo.toml'), false);
+});

package/package.json

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