@sdsrs/code-graph 0.7.18 → 0.8.0

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

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

package/claude-plugin/scripts/adopt.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+// adopt / unadopt — writes plugin_code_graph_mcp.md into this project's
+// claude-mem memory dir and maintains a sentinel-bracketed index entry in
+// MEMORY.md. Idempotent. Used by invited-memory pattern with CODE_GRAPH_QUIET_HOOKS=1.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SENTINEL_BEGIN = '<!-- code-graph-mcp:begin v1 -->';
+const SENTINEL_END = '<!-- code-graph-mcp:end -->';
+const INDEX_LINE = '- [code-graph-mcp](plugin_code_graph_mcp.md) — "谁调 X / 改 X 炸啥 / 模块结构" → `get_call_graph` / `impact_analysis` / `module_overview`，替代多步 Grep/Read';
+const TEMPLATE_PATH = path.resolve(__dirname, '..', 'templates', 'plugin_code_graph_mcp.md');
+const TARGET_NAME = 'plugin_code_graph_mcp.md';
+
+function memoryDir(cwd = process.cwd(), home = os.homedir()) {
+  const slug = cwd.replace(/\//g, '-');
+  return path.join(home, '.claude', 'projects', slug, 'memory');
+}
+
+function escapeRegex(s) {
+  return s.replace(/[\\/[\]^$.*+?()|{}]/g, '\\$&');
+}
+
+function adopt({ cwd, home, templatePath } = {}) {
+  const dir = memoryDir(cwd, home);
+  if (!fs.existsSync(dir)) {
+    return { ok: false, reason: 'no-memory-dir', dir };
+  }
+  const target = path.join(dir, TARGET_NAME);
+  const tpl = templatePath || TEMPLATE_PATH;
+  if (!fs.existsSync(tpl)) {
+    return { ok: false, reason: 'no-template', template: tpl };
+  }
+  fs.copyFileSync(tpl, target);
+
+  const indexPath = path.join(dir, 'MEMORY.md');
+  let index = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '# Memory Index\n';
+  let indexed = false;
+  if (!index.includes(SENTINEL_BEGIN)) {
+    if (!index.endsWith('\n')) index += '\n';
+    index += `${SENTINEL_BEGIN}\n${INDEX_LINE}\n${SENTINEL_END}\n`;
+    fs.writeFileSync(indexPath, index);
+    indexed = true;
+  }
+  return { ok: true, target, indexPath, indexed };
+}
+
+function unadopt({ cwd, home } = {}) {
+  const dir = memoryDir(cwd, home);
+  const target = path.join(dir, TARGET_NAME);
+  const indexPath = path.join(dir, 'MEMORY.md');
+  let fileRemoved = false;
+  let indexPruned = false;
+
+  if (fs.existsSync(target)) {
+    fs.unlinkSync(target);
+    fileRemoved = true;
+  }
+  if (fs.existsSync(indexPath)) {
+    const before = fs.readFileSync(indexPath, 'utf8');
+    const re = new RegExp(`${escapeRegex(SENTINEL_BEGIN)}[\\s\\S]*?${escapeRegex(SENTINEL_END)}\\n?`, 'g');
+    const after = before.replace(re, '');
+    if (after !== before) {
+      fs.writeFileSync(indexPath, after);
+      indexPruned = true;
+    }
+  }
+  return { ok: true, fileRemoved, indexPruned, target, indexPath };
+}
+
+function formatResult(action, result) {
+  if (action === 'adopt') {
+    if (!result.ok) {
+      if (result.reason === 'no-memory-dir') {
+        return `[code-graph] Memory dir not found: ${result.dir}\n` +
+               '  Run \`claude\` at least once in this project to create it.';
+      }
+      if (result.reason === 'no-template') {
+        return `[code-graph] Template missing: ${result.template}`;
+      }
+      return `[code-graph] adopt failed: ${result.reason || 'unknown'}`;
+    }
+    const lines = [`[code-graph] Adopted → ${result.target}`];
+    if (result.indexed) lines.push(`[code-graph] Indexed → ${result.indexPath}`);
+    else lines.push(`[code-graph] Index already contains sentinel — left as-is`);
+    lines.push('[code-graph] Activate: set CODE_GRAPH_QUIET_HOOKS=1 in ~/.claude/settings.json env');
+    return lines.join('\n');
+  }
+  if (action === 'unadopt') {
+    const lines = [];
+    if (result.fileRemoved) lines.push(`[code-graph] Removed → ${result.target}`);
+    if (result.indexPruned) lines.push(`[code-graph] De-indexed → ${result.indexPath}`);
+    if (!result.fileRemoved && !result.indexPruned) lines.push('[code-graph] Nothing to unadopt');
+    return lines.join('\n');
+  }
+  return '';
+}
+
+if (require.main === module) {
+  const action = process.argv[2] === 'unadopt' ? 'unadopt' : 'adopt';
+  const result = action === 'unadopt' ? unadopt() : adopt();
+  process.stdout.write(formatResult(action, result) + '\n');
+  process.exit(result.ok === false ? 1 : 0);
+}
+
+module.exports = {
+  adopt, unadopt, memoryDir, formatResult,
+  SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH, TARGET_NAME,
+};

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

@@ -0,0 +1,114 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+  adopt, unadopt, memoryDir, SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH,
+} = require('./adopt');
+
+function makeSandbox() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-home-'));
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-cwd-'));
+  // Pre-create the memory dir (claude-mem convention — we don't create it).
+  const dir = memoryDir(cwd, home);
+  fs.mkdirSync(dir, { recursive: true });
+  return { home, cwd, dir, cleanup: () => {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }};
+}
+
+test('memoryDir slugifies cwd path', () => {
+  const dir = memoryDir('/home/alice/proj', '/home/alice');
+  assert.strictEqual(dir, '/home/alice/.claude/projects/-home-alice-proj/memory');
+});
+
+test('adopt writes template and appends sentinel block when index absent', () => {
+  const sb = makeSandbox();
+  try {
+    const res = adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res.ok, true);
+    assert.strictEqual(res.indexed, true);
+    assert.ok(fs.existsSync(res.target), 'plugin file written');
+    const index = fs.readFileSync(res.indexPath, 'utf8');
+    assert.match(index, /^# Memory Index/);
+    assert.ok(index.includes(SENTINEL_BEGIN));
+    assert.ok(index.includes(SENTINEL_END));
+    assert.ok(index.includes(INDEX_LINE));
+  } finally { sb.cleanup(); }
+});
+
+test('adopt is idempotent — no duplicate sentinel on re-run', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const res2 = adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res2.indexed, false, 'second run leaves index alone');
+    const index = fs.readFileSync(res2.indexPath, 'utf8');
+    const matches = index.match(new RegExp(SENTINEL_BEGIN.replace(/[\\/[\]^$.*+?()|{}]/g, '\\$&'), 'g'));
+    assert.strictEqual(matches.length, 1, 'sentinel appears exactly once');
+  } finally { sb.cleanup(); }
+});
+
+test('adopt preserves existing MEMORY.md content and appends', () => {
+  const sb = makeSandbox();
+  try {
+    const indexPath = path.join(sb.dir, 'MEMORY.md');
+    fs.writeFileSync(indexPath, '# Memory Index\n\n- [foo.md](foo.md) — existing entry\n');
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const index = fs.readFileSync(indexPath, 'utf8');
+    assert.ok(index.includes('existing entry'), 'preserves prior entries');
+    assert.ok(index.includes(SENTINEL_BEGIN), 'appends sentinel');
+  } finally { sb.cleanup(); }
+});
+
+test('adopt fails gracefully when memory dir missing', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-home-'));
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-adopt-cwd-'));
+  try {
+    const res = adopt({ cwd, home });
+    assert.strictEqual(res.ok, false);
+    assert.strictEqual(res.reason, 'no-memory-dir');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('unadopt removes file and sentinel block, preserves other entries', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    // add a neighboring entry
+    const indexPath = path.join(sb.dir, 'MEMORY.md');
+    const withNeighbor = fs.readFileSync(indexPath, 'utf8') + '- [bar.md](bar.md) — neighbor\n';
+    fs.writeFileSync(indexPath, withNeighbor);
+
+    const res = unadopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res.fileRemoved, true);
+    assert.strictEqual(res.indexPruned, true);
+    assert.ok(!fs.existsSync(res.target), 'plugin file gone');
+    const final = fs.readFileSync(indexPath, 'utf8');
+    assert.ok(!final.includes(SENTINEL_BEGIN), 'sentinel removed');
+    assert.ok(final.includes('neighbor'), 'neighbor preserved');
+  } finally { sb.cleanup(); }
+});
+
+test('unadopt is a no-op when never adopted', () => {
+  const sb = makeSandbox();
+  try {
+    const res = unadopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(res.fileRemoved, false);
+    assert.strictEqual(res.indexPruned, false);
+  } finally { sb.cleanup(); }
+});
+
+test('template file exists and contains decision table', () => {
+  assert.ok(fs.existsSync(TEMPLATE_PATH), `template at ${TEMPLATE_PATH}`);
+  const content = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+  assert.ok(content.includes('get_call_graph'), 'mentions get_call_graph');
+  assert.ok(content.includes('impact_analysis'), 'mentions impact_analysis');
+  assert.ok(content.includes('CODE_GRAPH_QUIET_HOOKS'), 'mentions env gate');
+});

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

@@ -277,13 +277,17 @@ function runSessionInit() {
 
   const autoUpdateLaunched = launchBackgroundAutoUpdate();
   const indexFreshness = binaryCheck.available ? ensureIndexFresh() : 'skipped';
-  const mapInjected = binaryCheck.available ? injectProjectMap() : false;
+  // 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,
   };
 }
 

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