@sdsrs/code-graph 0.7.16 → 0.8.0

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

@@ -6,8 +6,10 @@ const os = require('os');
 const fs = require('fs');
 const {
   install, update, readManifest, getPluginVersion, checkScopeConflict,
-  cleanupDisabledStatusline, isPluginInactive, readJson,
+  cleanupDisabledStatusline, isPluginInactive, readJson, CACHE_DIR,
+  clearStalePluginCacheHooks, findStalePluginHooksJson,
 } = require('./lifecycle');
+const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-utils');
 
 function launchBackgroundAutoUpdate(spawnFn = spawn, env = process.env) {
   try {
@@ -161,6 +163,94 @@ function verifyBinary() {
   return { available: true, binary };
 }
 
+/**
+ * Lightweight consistency checks — called from runSessionInit().
+ * Returns an array of issue objects: { id, msg, fix }.
+ * Empty array = all consistent (silent).
+ */
+function consistencyCheck(binary) {
+  const issues = [];
+
+  // Check 1: Binary version vs plugin version
+  try {
+    const pluginVersion = getPluginVersion();
+    const binaryVersion = readBinaryVersion(binary);
+    if (binaryVersion && binaryVersion !== pluginVersion) {
+      issues.push({
+        id: 'version-mismatch',
+        msg: `Binary v${binaryVersion}, plugin expects v${pluginVersion}`,
+        fix: isDevMode() ? 'cargo build --release' : 'code-graph-mcp doctor',
+      });
+    }
+  } catch { /* skip check on error */ }
+
+  // Check 2: Source freshness (dev mode only)
+  try {
+    if (isDevMode()) {
+      const srcDir = path.resolve(__dirname, '..', '..', 'src');
+      const binaryMtime = fs.statSync(binary).mtimeMs;
+      const latestSrcMtime = getNewestMtime(srcDir, '.rs');
+      if (latestSrcMtime > binaryMtime) {
+        const deltaMin = Math.round((latestSrcMtime - binaryMtime) / 60000);
+        issues.push({
+          id: 'binary-stale',
+          msg: `src/ modified ${deltaMin}min after last build`,
+          fix: 'cargo build --release',
+        });
+      }
+    }
+  } catch { /* skip check on error */ }
+
+  // Check 3: Auto-update incomplete
+  try {
+    const statePath = path.join(CACHE_DIR, 'update-state.json');
+    const state = readJson(statePath);
+    if (state && state.updateAvailable && state.binaryUpdated === false) {
+      issues.push({
+        id: 'update-incomplete',
+        msg: `Plugin updated to v${state.latestVersion}, binary not updated`,
+        fix: 'code-graph-mcp doctor',
+      });
+    }
+  } catch { /* skip check on error */ }
+
+  // Output warnings to stderr
+  if (issues.length > 0) {
+    const lines = [`[code-graph] ${issues.length} consistency issue(s):`];
+    issues.forEach((issue, i) => {
+      lines.push(`  ${i + 1}. ${issue.msg}`);
+      lines.push(`     → ${issue.fix}`);
+    });
+    process.stderr.write(lines.join('\n') + '\n');
+  }
+
+  return issues;
+}
+
+/**
+ * Self-heal: Claude Code auto-update can re-populate cache hooks.json from the
+ * marketplace source, which would double-fire every hook we registered to
+ * settings.json. If our hooks are already in settings.json (install has run),
+ * any non-empty cache/marketplace hooks.json is stale — clear it.
+ * Gated on settings.json registration so pure plugin-only users (no install
+ * script run; cache hooks.json is their only registration) are not broken.
+ */
+function healStaleCacheHooks() {
+  try {
+    const settings = readJson(path.join(os.homedir(), '.claude', 'settings.json')) || {};
+    const manifest = readManifest();
+    if (!manifest || !manifest.version) return { checked: false, cleared: 0 };
+    const serialized = JSON.stringify(settings.hooks || {});
+    if (!serialized.includes('code-graph')) return { checked: false, cleared: 0 };
+    const stale = findStalePluginHooksJson();
+    if (stale.length === 0) return { checked: true, cleared: 0 };
+    const cleared = clearStalePluginCacheHooks();
+    return { checked: true, cleared: cleared.length };
+  } catch {
+    return { checked: false, cleared: 0 };
+  }
+}
+
 function runSessionInit() {
   if (isPluginInactive()) {
     cleanupDisabledStatusline();
@@ -177,13 +267,28 @@ function runSessionInit() {
 
   const lifecycle = syncLifecycleConfig();
 
+  // Self-heal stale plugin cache hooks.json (prevents double-firing after auto-update).
+  // syncLifecycleConfig's install/update path already clears; this catches the
+  // 'noop' case where version matches but cache was re-populated externally.
+  const cacheHookHeal = healStaleCacheHooks();
+
   // Verify binary availability — catch issues early with actionable diagnostics
   const binaryCheck = verifyBinary();
 
   const autoUpdateLaunched = launchBackgroundAutoUpdate();
   const indexFreshness = binaryCheck.available ? ensureIndexFresh() : 'skipped';
-  const mapInjected = binaryCheck.available ? injectProjectMap() : false;
-  return { inactive: false, lifecycle, autoUpdateLaunched, indexFreshness, mapInjected, binaryCheck };
+  // CODE_GRAPH_QUIET_HOOKS=1 → skip the 60-line project-map injection; rely
+  // on MEMORY.md pointer + on-demand `project_map` tool call instead.
+  const quietHooks = process.env.CODE_GRAPH_QUIET_HOOKS === '1';
+  const mapInjected = binaryCheck.available && !quietHooks ? injectProjectMap() : false;
+  const consistencyIssues = binaryCheck.available
+    ? consistencyCheck(binaryCheck.binary)
+    : [];
+  return {
+    inactive: false, lifecycle, cacheHookHeal,
+    autoUpdateLaunched, indexFreshness, mapInjected, binaryCheck, consistencyIssues,
+    quietHooks,
+  };
 }
 
 /**
@@ -221,6 +326,8 @@ module.exports = {
   ensureIndexFresh,
   injectProjectMap,
   verifyBinary,
+  consistencyCheck,
+  healStaleCacheHooks,
   runSessionInit,
 };
 

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

@@ -1,6 +1,8 @@
 'use strict';
 const test = require('node:test');
 const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
 
 const { launchBackgroundAutoUpdate, syncLifecycleConfig, ensureIndexFresh, verifyBinary } = require('./session-init');
 
@@ -70,3 +72,34 @@ test('launchBackgroundAutoUpdate spawns detached silent updater', () => {
   assert.equal(calls[0].unrefCalled, true);
 });
 
+const { consistencyCheck } = require('./session-init');
+
+test('consistencyCheck is exported as a function', () => {
+  assert.equal(typeof consistencyCheck, 'function');
+});
+
+test('consistencyCheck returns empty array when binary version matches plugin', () => {
+  const result = consistencyCheck('/tmp/nonexistent-binary');
+  assert.ok(Array.isArray(result));
+});
+
+test('consistencyCheck returns version-mismatch when versions differ', () => {
+  const os = require('os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-'));
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, [
+    '#!/usr/bin/env bash',
+    'if [ "$1" = "--version" ]; then',
+    '  echo "code-graph-mcp 0.0.1"',
+    '  exit 0',
+    'fi',
+    'exit 0',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+
+  const issues = consistencyCheck(bin);
+  const versionIssue = issues.find(i => i.id === 'version-mismatch');
+  assert.ok(versionIssue, 'should detect version mismatch');
+  assert.ok(versionIssue.msg.includes('0.0.1'));
+});
+

package/claude-plugin/scripts/user-prompt-context.js

@@ -53,6 +53,10 @@ function markCooldown(type) {
   } catch { /* ok */ }
 }
 
+// CODE_GRAPH_QUIET_HOOKS=1 → skip passive per-prompt injection entirely.
+// Users opt in to this mode when MEMORY.md + explicit tool calls cover their needs.
+if (process.env.CODE_GRAPH_QUIET_HOOKS === '1') process.exit(0);
+
 // --- Read user message ---
 let message;
 try {

package/claude-plugin/scripts/user-prompt-context.test.js

@@ -464,3 +464,17 @@ test('skills: only expected skills exist', () => {
   const files = fs.readdirSync(skillsDir).filter(f => f.endsWith('.md')).sort();
   assert.deepEqual(files, ['explore.md', 'index.md']);
 });
+
+test('CODE_GRAPH_QUIET_HOOKS=1 short-circuits before reading stdin', () => {
+  const { execFileSync } = require('node:child_process');
+  const script = path.join(__dirname, 'user-prompt-context.js');
+  const out = execFileSync(process.execPath, [script], {
+    input: JSON.stringify({ message: 'impact analysis for fn_that_would_trigger_search' }),
+    env: { ...process.env, CODE_GRAPH_QUIET_HOOKS: '1' },
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 2000,
+  });
+  // Quiet mode must produce no stdout — no [code-graph:*] prefix, nothing.
+  assert.equal(out, '');
+});

package/claude-plugin/scripts/version-utils.js

@@ -0,0 +1,49 @@
+'use strict';
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const VERSION_OUTPUT_RE = /^code-graph-mcp\s+(\d+\.\d+\.\d+)$/;
+
+function readBinaryVersion(binaryPath) {
+  try {
+    const out = execFileSync(binaryPath, ['--version'], {
+      timeout: 2000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).toString().trim();
+    const match = out.match(VERSION_OUTPUT_RE);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function isDevMode() {
+  // Always derive from __dirname — CLAUDE_PLUGIN_ROOT can leak from other plugins
+  const pluginRoot = path.resolve(__dirname, '..');
+  // Dev mode: running from source repo (has Cargo.toml nearby)
+  if (fs.existsSync(path.join(pluginRoot, '..', 'Cargo.toml'))) return true;
+  // Dev mode: plugin root is a symlink
+  try { if (fs.lstatSync(pluginRoot).isSymbolicLink()) return true; } catch { /* ok */ }
+  return false;
+}
+
+function getNewestMtime(dir, ext = '.rs') {
+  let newest = 0;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const sub = getNewestMtime(full, ext);
+        if (sub > newest) newest = sub;
+      } else if (entry.name.endsWith(ext)) {
+        const mt = fs.statSync(full).mtimeMs;
+        if (mt > newest) newest = mt;
+      }
+    }
+  } catch { /* dir doesn't exist or not readable */ }
+  return newest;
+}
+
+module.exports = { readBinaryVersion, isDevMode, getNewestMtime, VERSION_OUTPUT_RE };

package/claude-plugin/scripts/version-utils.test.js

@@ -0,0 +1,83 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function mkDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+// ── readBinaryVersion ──
+
+test('readBinaryVersion returns version from valid binary', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  const dir = mkDir('vu-');
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, [
+    '#!/usr/bin/env bash',
+    'if [ "$1" = "--version" ]; then',
+    '  echo "code-graph-mcp 1.2.3"',
+    '  exit 0',
+    'fi',
+    'exit 0',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+  assert.equal(readBinaryVersion(bin), '1.2.3');
+});
+
+test('readBinaryVersion returns null for non-existent binary', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  assert.equal(readBinaryVersion('/tmp/does-not-exist-binary'), null);
+});
+
+test('readBinaryVersion returns null for binary with unexpected output', () => {
+  const { readBinaryVersion } = require('./version-utils');
+  const dir = mkDir('vu-');
+  const bin = path.join(dir, 'code-graph-mcp');
+  fs.writeFileSync(bin, '#!/usr/bin/env bash\necho "something else"');
+  fs.chmodSync(bin, 0o755);
+  assert.equal(readBinaryVersion(bin), null);
+});
+
+// ── isDevMode ──
+
+test('isDevMode returns true in source repo (Cargo.toml nearby)', () => {
+  const { isDevMode } = require('./version-utils');
+  // Running from source repo: __dirname/../.. has Cargo.toml → true
+  assert.equal(isDevMode(), true);
+});
+
+// ── getNewestMtime ──
+
+test('getNewestMtime returns 0 for non-existent directory', () => {
+  const { getNewestMtime } = require('./version-utils');
+  assert.equal(getNewestMtime('/tmp/no-such-dir-xyz'), 0);
+});
+
+test('getNewestMtime finds newest .rs file mtime', () => {
+  const { getNewestMtime } = require('./version-utils');
+  const dir = mkDir('vu-mtime-');
+  const sub = path.join(dir, 'sub');
+  fs.mkdirSync(sub);
+
+  const older = path.join(dir, 'old.rs');
+  const newer = path.join(sub, 'new.rs');
+  fs.writeFileSync(older, 'fn old() {}');
+
+  fs.writeFileSync(newer, 'fn new() {}');
+  const futureMs = Date.now() + 1000;
+  fs.utimesSync(newer, futureMs / 1000, futureMs / 1000);
+
+  const newerMtime = fs.statSync(newer).mtimeMs;
+  const result = getNewestMtime(dir, '.rs');
+  assert.equal(result, newerMtime, 'should return exactly the newest file mtime');
+});
+
+test('getNewestMtime ignores non-matching extensions', () => {
+  const { getNewestMtime } = require('./version-utils');
+  const dir = mkDir('vu-ext-');
+  fs.writeFileSync(path.join(dir, 'file.js'), 'hello');
+  assert.equal(getNewestMtime(dir, '.rs'), 0);
+});

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -0,0 +1,70 @@
+---
+name: code-graph-mcp 插件契约
+description: code-graph-mcp 工具调度规则 — 何时用 MCP/CLI 替代 Grep/Read，invited-memory 模式
+type: reference
+---
+# code-graph-mcp 插件契约
+
+> Invited-memory 模式：MCP `instructions` 仅留指针，决策细则集中在此。
+> 启用条件：`CODE_GRAPH_QUIET_HOOKS=1`（在 `~/.claude/settings.json` 的 `env` 中设置）。
+
+## 何时调用 MCP/CLI（替代多步 Grep/Read）
+
+| 意图 | 工具 | 关键参数 / 例子 |
+|------|------|----------------|
+| "谁调用 X？" / "X 调了啥？" | `get_call_graph` / `callgraph X` | 替代 `grep "X("` |
+| "改 X 会炸啥？" | `impact_analysis` / `impact X` | 修改函数签名前必跑 |
+| "Y 模块长啥样？" | `module_overview` / `overview Y/` | 替代逐文件 Read |
+| "找做 Z 的代码"（概念） | `semantic_code_search` / `search "Z"` | 不知道精确名 |
+| "返回 T 类型的函数" | `ast_search --returns T` | 结构化筛选 |
+| "X 在哪被引用？" | `find_references` / `refs X` | 含 callers/importers |
+| "未使用的代码" | `find_dead_code` / `dead-code [path]` | 清理 exports |
+| "相似/重复函数" | `find_similar_code` / `similar X` | 需 embedding |
+| "X 文件依赖谁？" | `dependency_graph` / `deps X` | file 级别 |
+| "看 X 的源码 / 签名" | `get_ast_node` / `show X` | `--include-impact` 含影响面 |
+| "项目结构总览" | `project_map` / `map` | 起手势用 `--compact` |
+| HTTP 路由 → handler 链路 | `trace_http_chain` / `trace ROUTE` | API 调试 |
+
+## 不要替代
+
+- 精确字符串 / 常量 / 正则 → 仍用 `Grep`
+- 非代码文件（README/JSON/log） → 仍用 `Grep`
+- 即将编辑的具体文件 → 仍用 `Read`
+
+## 工作流惯例
+
+1. 起手 `project_map --compact` 看架构
+2. `semantic_code_search` 默认带 `compact=true`，省 token
+3. 展开节点：`get_ast_node node_id=N compact=true` 看签名 / 不带 compact 看全文
+4. 改前必跑 `impact_analysis`
+5. 搜不到结果 → `code-graph-mcp health-check` 检查索引与 embedding 覆盖率
+
+可用 prompts：`impact-analysis`、`understand-module`、`trace-request`
+
+## CLI 速查（替 Bash）
+
+```
+code-graph-mcp grep "pattern" [path]     # ripgrep + AST 上下文
+code-graph-mcp search "concept"          # FTS5 语义搜索
+code-graph-mcp ast-search "q" --type fn  # 结构化筛选
+code-graph-mcp map                       # 项目架构
+code-graph-mcp overview src/mcp/         # 模块总览
+code-graph-mcp callgraph SYMBOL          # 调用图
+code-graph-mcp impact SYMBOL             # 影响面
+code-graph-mcp show SYMBOL                # 节点详情
+code-graph-mcp refs SYMBOL --relation calls  # 引用筛选
+code-graph-mcp dead-code [path]           # 未使用代码
+code-graph-mcp health-check              # 索引健康
+```
+
+完整列表：`code-graph-mcp --help`。
+
+## 质量门槛
+
+- `compact=true` 一般够用；要看完整代码再去掉
+- `impact` 在 `--change-type signature` 时返回最严格的破坏面
+- 索引陈旧 → SessionStart 自带 `ensureIndexFresh`；手动跑 `incremental-index`
+
+## 卸载
+
+`code-graph-mcp unadopt` 精确移除 sentinel 段 + 本文件；或取消 `CODE_GRAPH_QUIET_HOOKS` 即恢复原注入。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.7.16",
+  "version": "0.8.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": {
@@ -34,10 +34,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.7.16",
-    "@sdsrs/code-graph-linux-arm64": "0.7.16",
-    "@sdsrs/code-graph-darwin-x64": "0.7.16",
-    "@sdsrs/code-graph-darwin-arm64": "0.7.16",
-    "@sdsrs/code-graph-win32-x64": "0.7.16"
+    "@sdsrs/code-graph-linux-x64": "0.8.0",
+    "@sdsrs/code-graph-linux-arm64": "0.8.0",
+    "@sdsrs/code-graph-darwin-x64": "0.8.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.8.0",
+    "@sdsrs/code-graph-win32-x64": "0.8.0"
   }
 }