@sdsrs/code-graph 0.54.2 → 0.56.0

package/bin/cli.js

@@ -18,17 +18,19 @@ if (sub === "adopt" || sub === "unadopt") {
   process.exit(result.ok === false ? 1 : 0);
 }
 
-const { findBinary } = require("../claude-plugin/scripts/find-binary");
+const { findBinary, unsupportedPlatformHint } = require("../claude-plugin/scripts/find-binary");
 
 const binary = findBinary();
 
 if (!binary) {
+  const hint = unsupportedPlatformHint();
   console.error(
     "Error: code-graph-mcp binary not found.\n\n" +
+    (hint ? hint + "\n\n" : "") +
     "To install:\n" +
     "  npm install -g @sdsrs/code-graph\n\n" +
     "To build from source:\n" +
-    "  cargo build --release\n"
+    "  cargo install code-graph-mcp --features embed-model\n"
   );
   process.exit(1);
 }
@@ -41,6 +43,10 @@ const child = spawn(binary, process.argv.slice(2), {
 
 child.on("error", (err) => {
   console.error(`Failed to start code-graph-mcp: ${err.message}`);
+  // A glibc binary installed on musl (older npm ignores the `libc` field) is present
+  // but fails to exec — surface the actionable platform hint instead of a bare error.
+  const hint = unsupportedPlatformHint();
+  if (hint) console.error("\n" + hint);
   process.exit(1);
 });
 

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

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

package/claude-plugin/scripts/doctor.js

@@ -13,6 +13,38 @@ const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 
 // ── Diagnostics ───────────────────────────────────────────
 
+/**
+ * Classify embedding/vector availability from a `health-check --json` payload.
+ * Pure (no I/O) so it is unit-testable. Surfaces a silent FTS5-only degradation
+ * that the prior embedding_progress-only check false-greened as "no embeddable
+ * nodes": when the binary is embed-capable and the index HAS embeddable nodes but
+ * none are embedded, the vector channel is inactive and semantic search runs
+ * FTS5-only — that is a 'warn', not 'ok'.
+ * @returns {{name:string, status:'ok'|'warn', detail:string}}
+ */
+function classifyEmbeddings(hc) {
+  const ep = (hc && hc.embedding_progress) || '0/0';
+  const [done, total] = ep.split('/').map(Number);
+  if (hc && hc.model_available === false) {
+    return { name: 'Embeddings', status: 'warn',
+      detail: 'binary built without embed-model — semantic search is FTS5-only; reinstall via npm/plugin for the hybrid binary' };
+  }
+  if (!total) {
+    return { name: 'Embeddings', status: 'ok', detail: 'no embeddable nodes' };
+  }
+  if (!done) {
+    const why = (hc && hc.embedding_status === 'pending')
+      ? 'model not downloaded/loaded yet — auto-downloads in background on first search; retry shortly or restart the MCP server'
+      : `embedding_status=${(hc && hc.embedding_status) || 'unknown'}`;
+    return { name: 'Embeddings', status: 'warn',
+      detail: `vector INACTIVE — ${total} embeddable nodes, 0 embedded; semantic search is FTS5-only (${why})` };
+  }
+  if (done < total) {
+    return { name: 'Embeddings', status: 'ok', detail: `hybrid — ${Math.round((done / total) * 100)}% embedded (${done}/${total})` };
+  }
+  return { name: 'Embeddings', status: 'ok', detail: `hybrid — embeddings complete (${done}/${total})` };
+}
+
 /**
  * Run all diagnostic checks. Returns an array of:
  *   { name: string, status: 'ok'|'warn'|'error'|'skip', detail: string, fixId?: string }
@@ -119,17 +151,9 @@ function runDiagnostics() {
             });
           }
 
-          // Embeddings
-          const ep = hc.embedding_progress || '0/0';
-          const [done, total] = ep.split('/').map(Number);
-          if (total > 0 && done < total) {
-            const pct = Math.round((done / total) * 100);
-            results.push({ name: 'Embeddings', status: 'ok', detail: `${pct}% (${done}/${total})` });
-          } else if (total === 0) {
-            results.push({ name: 'Embeddings', status: 'ok', detail: 'no embeddable nodes' });
-          } else {
-            results.push({ name: 'Embeddings', status: 'ok', detail: `100% (${done}/${total})` });
-          }
+          // Embeddings / vector availability — pure classifier; warns on FTS5-only
+          // degradation (model missing/not loaded) instead of false-greening it.
+          results.push(classifyEmbeddings(hc));
         }
       } catch (e) {
         const rawStderr = e.stderr ? e.stderr.toString() : '';
@@ -453,7 +477,7 @@ function runDoctor(opts = {}) {
   return { results, issueCount: issues.length };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage, relicRepairGuard };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, surveyHookCoverage, relicRepairGuard, classifyEmbeddings };
 
 if (require.main === module) {
   const args = process.argv.slice(2);

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

@@ -93,3 +93,32 @@ test('relicRepairGuard blocks settings repair from a relic copy and redirects',
   // Active (or dev/npm) context → repair proceeds.
   assert.equal(relicRepairGuard({ relic: false, log: () => {} }), false);
 });
+
+// ── classifyEmbeddings (vector-availability — warns on silent FTS5-only) ──
+
+test('classifyEmbeddings WARNS when embed-capable but nothing embedded (vector inactive)', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  // The exact silent-FTS5 gap: model_available compile-flag true, real embeddable
+  // nodes exist, but 0 embedded (model never downloaded/loaded).
+  const r = classifyEmbeddings({ model_available: true, embedding_progress: '0/2745',
+    embedding_status: 'pending', search_mode: 'fts_only' });
+  assert.equal(r.status, 'warn', 'must not false-green a vector-inactive index');
+  assert.match(r.detail, /FTS5-only|vector INACTIVE/);
+});
+
+test('classifyEmbeddings WARNS when binary lacks embed-model feature', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  const r = classifyEmbeddings({ model_available: false, embedding_progress: '0/0' });
+  assert.equal(r.status, 'warn');
+  assert.match(r.detail, /without embed-model/);
+});
+
+test('classifyEmbeddings OK for hybrid (partial + complete) and no-embeddable', () => {
+  const { classifyEmbeddings } = require('./doctor');
+  assert.equal(classifyEmbeddings({ model_available: true, embedding_progress: '900/2745' }).status, 'ok');
+  assert.equal(classifyEmbeddings({ model_available: true, embedding_progress: '2745/2745' }).status, 'ok');
+  // total === 0 is a non-code index, genuinely nothing to embed → ok, not a false warn.
+  const none = classifyEmbeddings({ model_available: true, embedding_progress: '0/0' });
+  assert.equal(none.status, 'ok');
+  assert.match(none.detail, /no embeddable nodes/);
+});

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

@@ -12,6 +12,45 @@ const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path'
 const BINARY_NAME = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
 const PLATFORM_PKG = `@sdsrs/code-graph-${PLATFORM}-${ARCH}`;
 
+/**
+ * libc flavor of the current Linux runtime: 'glibc' or 'musl'. musl (Alpine) has
+ * no `glibcVersionRuntime` in the Node process-report header. Best-effort; returns
+ * 'glibc' off Linux or when detection is unavailable.
+ */
+function detectLibc() {
+  if (PLATFORM !== 'linux') return 'glibc';
+  try {
+    const header = process.report.getReport().header;
+    if (header && header.glibcVersionRuntime) return 'glibc';
+    return 'musl';
+  } catch {
+    try { if (fs.existsSync('/etc/alpine-release')) return 'musl'; } catch { /* ignore */ }
+    return 'glibc';
+  }
+}
+
+/**
+ * Actionable install hint for a platform that has NO published prebuilt binary
+ * (Alpine/musl, or native Windows-on-ARM), or null when the platform is supported
+ * (generic messaging applies). Pure in (platform, arch, libc) so it is unit-testable
+ * without running on each OS. Prevents the misleading "npm install
+ * @sdsrs/code-graph-<plat>-<arch>" suggestion for a package that does not exist.
+ */
+function unsupportedPlatformHint(platform = PLATFORM, arch = ARCH, libc = null) {
+  const lc = libc || (platform === 'linux' ? detectLibc() : 'glibc');
+  if (platform === 'linux' && lc === 'musl') {
+    return 'Detected Alpine/musl libc, which has no prebuilt binary. Install from source:\n'
+      + '  cargo install code-graph-mcp --features embed-model\n'
+      + 'or use a glibc-based image (e.g. node:20-slim / debian, not node:20-alpine).';
+  }
+  if (platform === 'win32' && arch === 'arm64') {
+    return 'Detected Windows on ARM (arm64), which has no native build. Either use an x64 '
+      + 'build of Node.js (the published x64 binary runs under Windows ARM emulation), '
+      + 'or install from source:\n  cargo install code-graph-mcp --features embed-model';
+  }
+  return null;
+}
+
 /** Read the npm pkg version from this script's package.json (claude-plugin/../package.json). */
 function getPackageVersion() {
   try { return require('../../package.json').version; }
@@ -263,6 +302,7 @@ module.exports = {
   findBinary, findBinaryUncached, clearCache,
   globalNodeModulesCandidates, findPlatformBinary,
   getPackageVersion, compareVersions, isCachedBinaryFresh,
+  detectLibc, unsupportedPlatformHint,
   CACHE_FILE, BINARY_NAME, PLATFORM_PKG,
 };
 

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

@@ -6,7 +6,8 @@ const os = require('os');
 const path = require('path');
 
 const { globalNodeModulesCandidates, findPlatformBinary, BINARY_NAME,
-        compareVersions, getPackageVersion, isCachedBinaryFresh } = require('./find-binary');
+        compareVersions, getPackageVersion, isCachedBinaryFresh,
+        unsupportedPlatformHint } = require('./find-binary');
 
 function mkDir(t, prefix) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -219,3 +220,27 @@ test('isCachedBinaryFresh: file basename mismatch → not fresh', (t) => {
   if (process.platform !== 'win32') fs.chmodSync(wrongName, 0o755);
   assert.equal(isCachedBinaryFresh(wrongName, '0.25.0'), false);
 });
+
+// ── unsupportedPlatformHint (actionable message for tails with no prebuilt binary) ──
+
+test('unsupportedPlatformHint flags Alpine/musl with a source/glibc-image hint', () => {
+  const hint = unsupportedPlatformHint('linux', 'x64', 'musl');
+  assert.ok(hint, 'musl should produce a hint');
+  assert.match(hint, /musl|Alpine/);
+  assert.match(hint, /cargo install/);
+});
+
+test('unsupportedPlatformHint flags native Windows-on-ARM with emulation/source hint', () => {
+  const hint = unsupportedPlatformHint('win32', 'arm64', 'glibc');
+  assert.ok(hint, 'win32-arm64 should produce a hint');
+  assert.match(hint, /Windows on ARM|arm64/);
+  assert.match(hint, /x64|cargo install/);
+});
+
+test('unsupportedPlatformHint returns null for supported platforms', () => {
+  assert.equal(unsupportedPlatformHint('linux', 'x64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('linux', 'arm64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('darwin', 'arm64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('darwin', 'x64', 'glibc'), null);
+  assert.equal(unsupportedPlatformHint('win32', 'x64', 'glibc'), null);
+});

package/claude-plugin/scripts/mcp-launcher.js

@@ -105,7 +105,7 @@ if (process.env.CODE_GRAPH_FORCE_PLUGIN_MCP !== '1' && isNonProjectCwd(process.c
   return;
 }
 
-const { findBinary, clearCache } = require('./find-binary');
+const { findBinary, clearCache, unsupportedPlatformHint } = require('./find-binary');
 
 let binary = findBinary();
 
@@ -169,6 +169,14 @@ if (!binary) {
   const installedViaMarketplace = fs.existsSync(
     path.join(__dirname, '..', '.claude-plugin', 'plugin.json')
   );
+  const platformHint = unsupportedPlatformHint();
+  if (platformHint) {
+    // Unsupported platform (Alpine/musl or native Windows-on-ARM): the per-platform
+    // npm package does not exist, so the generic "npm install @sdsrs/code-graph-<plat>-<arch>"
+    // suggestion below would point at a nonexistent package. Show the source/emulation hint.
+    process.stderr.write('[code-graph] Binary not found.\n' + platformHint + '\n');
+    process.exit(1);
+  }
   process.stderr.write('[code-graph] Binary not found. Install manually:\n');
   if (installedViaMarketplace) {
     process.stderr.write(
@@ -217,6 +225,10 @@ child.on('error', (err) => {
       `  xattr -d com.apple.quarantine "${binary}"\n`
     );
   }
+  // A glibc binary installed on musl (older npm ignores the `libc` field) is present
+  // but execs into a loader error — surface the actionable platform hint.
+  const platformHint = unsupportedPlatformHint();
+  if (platformHint) process.stderr.write(platformHint + '\n');
   process.exit(1);
 });
 

package/claude-plugin/templates/plugin_code_graph_mcp.md

@@ -82,6 +82,9 @@ hidden 5 加载 schema —— 实操中走新 flag。CLI 子命令保持原样
 | "相似/重复函数"（需 embedding） | `code-graph-mcp similar X` | `get_ast_node symbol_name=X include_similar=true` |
 | "未使用的代码" | `code-graph-mcp dead-code [path]` | `module_overview path=<path> include_dead=true` |
 | "架构咽喉/桥节点是谁？" | `code-graph-mcp centrality` | —（CLI-only；betweenness 中心性，补 `map` 的 caller_count 度中心性） |
+| "循环导入依赖（哪些文件互相 import）？" | `code-graph-mcp cycles` | —（CLI-only；文件级 import 环 = SCC；JS/TS/Py/Go 是坏味，Rust 内部环常良性） |
+| "可疑/意外的跨模块耦合？" | `code-graph-mcp surprising` | —（CLI-only；跨文件 calls/refs 按 低置信(ambiguous>inferred)+跨模块+sole-bridge 打分） |
+| "代码健康总览（想要一份报告）？" | `code-graph-mcp report` | —（CLI-only；汇总 summary+置信度 / hot / chokepoints / cycles / surprising / dead-code） |
 
 **dead-code 的 `ignore_paths`**：CLI 默认豁免 `["claude-plugin/", "benches/"]`
 （macro/shell 入口点）；`--no-ignore` 关闭。MCP 端也接同名参数。
@@ -117,6 +120,9 @@ code-graph-mcp show SYMBOL                # 节点详情
 code-graph-mcp refs SYMBOL --relation calls  # 引用筛选
 code-graph-mcp refs SYMBOL --min-confidence extracted  # 只看精确边（滤跨文件裸名 inferred/ambiguous）
 code-graph-mcp centrality                 # 架构咽喉（betweenness 桥节点；补 map 的 caller_count）
+code-graph-mcp cycles                     # 循环导入依赖（文件级 import 环 / SCC）
+code-graph-mcp surprising                 # 可疑跨模块耦合（低置信 + 跨模块 + sole-bridge 打分）
+code-graph-mcp report                     # 代码健康总览（汇总 hot/chokepoints/cycles/surprising/dead-code）
 code-graph-mcp dead-code [path]           # 未使用代码（默认豁免 claude-plugin/）
 code-graph-mcp dead-code --ignore tmp/ --ignore scripts/bin/  # 自定义豁免前缀
 code-graph-mcp dead-code --no-ignore      # 关掉默认豁免，看完整列表

package/package.json

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