@sdsrs/code-graph 0.24.1 → 0.25.0

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.24.1",
+  "version": "0.25.0",
   "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/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.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.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.0",
+    "@sdsrs/code-graph-linux-arm64": "0.25.0",
+    "@sdsrs/code-graph-darwin-x64": "0.25.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.25.0",
+    "@sdsrs/code-graph-win32-x64": "0.25.0"
   }
 }