@sdsrs/code-graph 0.24.0 → 0.25.0

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.24.0",
+  "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/adopt.js

@@ -33,9 +33,16 @@ function readAdoptedBy(filePath) {
 // scratch dirs, mixed repos). Per-type variants live in `buildIndexLine` and
 // are computed per-cwd at adopt + needsRefresh time. Adopted-project receives
 // the typed variant; everyone else falls back to this canonical line.
+// Tags MUST be ≥4 chars and topic-specific (per claudemd §11-EXT Tag-specificity).
+// Generic single-word English tags (impact / refs / overview / semantic / deps /
+// trace / route / similar) substring-match release-notes / commit-message prose
+// via the §11 read-the-file hook regex (word-boundary + 0–2 declension chars),
+// producing false-positive denies. Each tag below aligns with its MCP tool name
+// (impact_analysis / find_references / module_overview / …) so hyphenated literals
+// never collide with natural prose.
 const INDEX_LINE =
   '- [code-graph-mcp](plugin_code_graph_mcp.md) ' +
-  '[impact, callgraph, refs, overview, semantic, ast-search, dead-code, similar, deps, trace] — ' +
+  '[impact-analysis, callgraph, find-references, module-overview, semantic-search, ast-search, dead-code, find-similar-code, dependency-graph, trace-http-chain] — ' +
   '改 X 影响面/谁调用 X/X 被谁用/看 X 源码/Y 模块长啥样/概念查询 优先于 Grep；字面匹配走 Grep。' +
   '核心 7（get_call_graph/module_overview/semantic_code_search/ast_search/find_references/get_ast_node/project_map）' +
   '+ 进阶 5（impact_analysis/trace_http_chain/dependency_graph/find_similar_code/find_dead_code），决策表见全文';
@@ -235,12 +242,12 @@ function buildIndexLine(projectType = 'generic') {
     case 'web-py':
     case 'web-go':
       return prefix +
-        '[trace, route, callgraph, impact, refs, overview, semantic, deps] — ' +
+        '[trace-http-chain, http-route, callgraph, impact-analysis, find-references, module-overview, semantic-search, dependency-graph] — ' +
         'HTTP 路由→handler 链路用 trace_http_chain（或 get_call_graph route_path=）；改 handler 影响面用 impact；' +
         '其他结构化查询同上 优先于 Grep。' + coreSuffix;
     case 'frontend':
       return prefix +
-        '[refs, overview, semantic, callgraph, impact, ast-search] — ' +
+        '[find-references, module-overview, semantic-search, callgraph, impact-analysis, ast-search] — ' +
         '组件重命名/重构用 find_references（含 imports/inherits）；模块层级用 module_overview；' +
         '改 props/接口前用 impact 看下游；HTTP route 通常不适用。' + coreSuffix;
     case 'rust':
@@ -248,7 +255,7 @@ function buildIndexLine(projectType = 'generic') {
     case 'python':
     case 'node':
       return prefix +
-        '[callgraph, impact, refs, overview, semantic, ast-search, dead-code, deps] — ' +
+        '[callgraph, impact-analysis, find-references, module-overview, semantic-search, ast-search, dead-code, dependency-graph] — ' +
         '改 X 影响面/谁调用 X/Y 模块 优先于 Grep；HTTP route 追踪通常不适用（无 web 框架）；' +
         '字面匹配走 Grep。' + coreSuffix;
     case 'generic':

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

@@ -648,7 +648,7 @@ test('buildIndexLine generic returns the canonical INDEX_LINE byte-for-byte', ()
 
 test('buildIndexLine web-rs prepends route/trace tags + handler-focused lead', () => {
   const line = buildIndexLine('web-rs');
-  assert.match(line, /\[trace, route,/, 'web-rs index line should lead with trace/route tags');
+  assert.match(line, /\[trace-http-chain, http-route,/, 'web-rs index line should lead with trace-http-chain/http-route tags');
   assert.match(line, /HTTP 路由/, 'lead sentence should mention HTTP routes');
 });
 
@@ -675,6 +675,57 @@ test('adopt + needsRefresh agree on typed INDEX_LINE — no spurious refresh in
   } finally { sb.cleanup(); }
 });
 
+test('stale INDEX_LINE → adopt rewrites in place without duplicating sentinel blocks', () => {
+  // Regression for the v0.24+ tag-rename fix (feedback_adoption_tag_specificity).
+  // If a user's MEMORY.md was written by an older code-graph-mcp (pre-rename),
+  // SessionStart → maybeAutoAdopt → needsRefresh must detect the drift,
+  // stripSentinelBlock must locate the old v1 block by sentinel marker, and
+  // the rewrite must end with exactly one BEGIN/END pair. Breaks if anyone
+  // bumps SENTINEL_BEGIN without teaching stripSentinelBlock to also match
+  // the prior version — would leave an orphan v1 block plus a new v2 block.
+  const sb = makeSandbox();
+  try {
+    fs.writeFileSync(path.join(sb.cwd, 'Cargo.toml'), '[package]\nname="x"\n');
+    // Plant pre-rename MEMORY.md: well-formed v1 sentinel + an obsolete tag
+    // line that no current buildIndexLine variant produces. Exact prior bytes
+    // don't matter — only that it differs from today's desiredBlock.
+    const stalePayload =
+      '- [code-graph-mcp](plugin_code_graph_mcp.md) [obsolete-tag, another-stale] — stale lead sentence kept for drift detection.';
+    const indexPath = path.join(sb.dir, 'MEMORY.md');
+    const neighbor = '- [user_profile.md](user_profile.md) — neighbor (must survive)';
+    fs.writeFileSync(
+      indexPath,
+      `# Memory Index\n\n${neighbor}\n\n${SENTINEL_BEGIN}\n${stalePayload}\n${SENTINEL_END}\n`
+    );
+    // Plant target file so isAdopted/needsRefresh treat this as a real prior
+    // adoption (body bytewise-identical to shipped template — drift is only
+    // in MEMORY.md, not the template body).
+    const tplBody = fs.readFileSync(TEMPLATE_PATH);
+    const marker = Buffer.from(`<!-- adopted-by: ${sb.cwd} -->\n`);
+    fs.writeFileSync(path.join(sb.dir, TARGET_NAME), Buffer.concat([marker, tplBody]));
+
+    assert.strictEqual(isAdopted({ cwd: sb.cwd, home: sb.home }), true,
+      'precondition: planted state should look adopted');
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), true,
+      'tag-list drift must trigger refresh');
+
+    adopt({ cwd: sb.cwd, home: sb.home });
+
+    const after = fs.readFileSync(indexPath, 'utf8');
+    const escBegin = SENTINEL_BEGIN.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+    const escEnd = SENTINEL_END.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+    const beginHits = (after.match(new RegExp(escBegin, 'g')) || []).length;
+    const endHits = (after.match(new RegExp(escEnd, 'g')) || []).length;
+    assert.strictEqual(beginHits, 1, 'exactly one sentinel BEGIN after rewrite (no duplicate blocks)');
+    assert.strictEqual(endHits, 1, 'exactly one sentinel END after rewrite');
+    assert.ok(!after.includes('obsolete-tag'), 'stale tag list must be gone');
+    assert.ok(!after.includes('another-stale'), 'stale tag list must be gone');
+    assert.ok(after.includes(neighbor), 'neighbor entry preserved');
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), false,
+      'post-refresh needsRefresh must be false (no SessionStart refresh loop)');
+  } finally { sb.cleanup(); }
+});
+
 // 2A — false-positive hardening: comment-strip + section-aware scan.
 
 test('detectProjectType ignores commented-out web-framework deps in Cargo.toml', () => {

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.0",
+  "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.0",
-    "@sdsrs/code-graph-linux-arm64": "0.24.0",
-    "@sdsrs/code-graph-darwin-x64": "0.24.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.24.0",
-    "@sdsrs/code-graph-win32-x64": "0.24.0"
+    "@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"
   }
 }