fix(mcp): 4 residual precision fixes after 12-tool audit (v0.11.2)

sdsrss · claude · sdsrss · commit fc547bbbca31 · 2026-04-17T05:16:00.000+08:00
Follow-up on v0.11.1 audit. All additive/tightening, no schema breakage.

1. module_overview no longer leaks inline #[cfg(test)] fns
   - SQL now filters n.is_test=0 on both explicit-exports and fallback
     paths in get_module_exports; AST flag propagates end-to-end.
   - Name-heuristic was missing `#[cfg(test)] mod tests { #[test] fn X }`
     where X lacked the test_ prefix.

2. Disambiguation suggestions carry node_id + start_line
   - NameCandidate extended with both fields; resolve_fuzzy_name and
     disambiguate_symbol emit them.
   - disambiguate_symbol now fires on same-file multi-def (not just
     cross-file), closing the 2-fn-new()-in-one-module gap.

3. find_references gains node_id parameter
   - Same-file multi-def surfaces an ambiguity response with per-def
     suggestions (node_id + start_line) instead of silently merging
     refs across defs.

4. find_dead_code gets ignore_paths (MCP) / --ignore + --no-ignore (CLI)
   - Prefix-match exclusions with default [claude-plugin/] to suppress
     shell-invoked plugin entry points that the AST graph can't reach.
   - Response carries ignored_count / ignore_paths_applied /
     ignore_paths_defaulted for transparency.

Docs: plugin_code_graph_mcp.md adds explicit param tables for hidden-5
tools — notably trace_http_chain takes route_path (not route).

Tests: +4 (1 unit, 3 integration). 347 passed default features,
340 passed --no-default-features. Clippy -D warnings clean.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AST knowledge graph plugin for Claude Code — semantic search, call graph, HTTP tracing, impact analysis",
-    "version": "0.11.1"
+    "version": "0.11.2"
   },
   "plugins": [
     {
       "name": "code-graph-mcp",
       "source": "./claude-plugin",
       "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
-      "version": "0.11.1",
+      "version": "0.11.2",
       "author": {
         "name": "sdsrs"
       },
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,52 @@
 # Changelog
 
+## v0.11.2 — Post-audit follow-up: 4 residual precision fixes
+
+Follow-up audit on top of v0.11.1. All additive/tightening — no schema breakage.
+
+### Fixes
+
+1. **`module_overview` no longer leaks inline `#[cfg(test)]` test fns.**
+   Name-heuristic `is_test_symbol` couldn't catch `#[cfg(test)] mod tests { #[test] fn anything_goes }`
+   whose names don't prefix `test_`. Root fix: `get_module_exports` SQL now
+   `WHERE n.is_test = 0` on both the explicit-exports (JS/TS) path and the
+   fallback (Rust / Go / Python) path — AST-level flag propagates through.
+
+2. **Disambiguation suggestions carry `node_id` + `start_line`.**
+   `resolve_fuzzy_name` and `disambiguate_symbol` suggestions now include
+   both fields so callers can pick a specific definition when multiple
+   same-name functions live in one file (e.g. two `fn new()` in different
+   `impl` blocks of the same module). `disambiguate_symbol` also fires on
+   same-file multi-def, not just cross-file collisions.
+
+3. **`find_references` gains `node_id` parameter.** Lets callers pass the
+   `node_id` from a suggestion directly, skipping the ambiguous name-lookup
+   step. When a name is ambiguous within one file, the tool now returns
+   a per-definition suggestion list (with `start_line`) instead of silently
+   merging refs across defs.
+
+4. **`find_dead_code` gets `ignore_paths` (MCP) / `--ignore` (CLI).**
+   Shell-invoked plugin entry points (lifecycle/hook scripts in
+   `claude-plugin/`) are not in the static AST call graph, so they surfaced
+   as false-positive orphans. Added prefix-match exclusions with a sensible
+   default (`["claude-plugin/"]`). Pass `ignore_paths: []` or
+   `--no-ignore` to see the full list. Response carries `ignored_count`,
+   `ignore_paths_applied`, `ignore_paths_defaulted` for transparency.
+
+### Docs
+
+- `plugin_code_graph_mcp.md`: hidden-5 tools now have an explicit
+  required/optional parameter table (notably `trace_http_chain` takes
+  `route_path`, not `route`) — users calling by name no longer need to
+  trigger the error message to discover arg names.
+
+### Tests
+
++4 new (+1 unit in `queries.rs`, +3 integration covering Bug #1 / Issue #3 /
+Bug #2). Full suite: **347 passed / 0 failed** default features,
+**340 passed / 0 failed** `--no-default-features`; clippy
+`-D warnings` clean under both feature configs.
+
 ## v0.11.1 — 12-tool accuracy audit: 1 critical bugfix + 5 precision improvements
 
 Post-audit fixes for tool output correctness. All changes are additive/tightening —
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "code-graph-mcp"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2021"
 
 [features]
diff --git a/claude-plugin/.claude-plugin/plugin.json b/claude-plugin/.claude-plugin/plugin.json
@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.11.1",
+  "version": "0.11.2",
   "keywords": [
     "code-graph",
     "ast",
diff --git a/claude-plugin/templates/plugin_code_graph_mcp.md b/claude-plugin/templates/plugin_code_graph_mcp.md
@@ -36,13 +36,17 @@ type: reference
 
 ### 进阶 5（隐藏但可调）
 
-| 意图 | 工具 | 关键参数 / 例子 |
-|------|------|----------------|
-| ⚙ "改 X 会炸啥？" | `impact_analysis` / `impact X` | 修改签名前用；或 `get_ast_node` + `include_impact=true` |
-| ⚙ HTTP 路由 → handler 链路 | `trace_http_chain` / `trace ROUTE` | API 调试 |
-| ⚙ "X 文件依赖谁？" | `dependency_graph` / `deps X` | file 级别 |
-| ⚙ "相似/重复函数" | `find_similar_code` / `similar X` | 需 embedding |
-| ⚙ "未使用的代码" | `find_dead_code` / `dead-code [path]` | 清理 exports |
+这 5 个工具从 `tools/list` 隐藏（省 token），但**仍可按名调用**。由于 schema 不在 list 里，**必须用下表列出的精确参数名**（猜错会返回 `"<param> is required"` 错误）。
+
+| 意图 | 工具 | 必填参数 | 可选参数 |
+|------|------|----------|----------|
+| "改 X 会炸啥？" | `impact_analysis` | `symbol_name` | `file_path`, `change_type` ∈ {signature,behavior,remove}, `depth` |
+| HTTP 路由 → handler 链路 | `trace_http_chain` | **`route_path`** ⚠（不是 `route`） | `depth` |
+| "X 文件依赖谁？" | `dependency_graph` | `file_path` | `direction` ∈ {outgoing,incoming,both}, `depth`, `compact` |
+| "相似/重复函数"（需 embedding） | `find_similar_code` | `symbol_name` 或 `node_id` | `top_k`, `max_distance` |
+| "未使用的代码" | `find_dead_code` | — | `path`, `node_type`, `include_tests`, `min_lines`, `compact`, **`ignore_paths`** (prefix glob 数组；默认 `["claude-plugin/"]`，传 `[]` 关闭默认豁免) |
+
+CLI 等价：`impact/trace/deps/similar/dead-code`（见下方 CLI 速查）。
 
 ## 不要替代
 
@@ -73,7 +77,9 @@ 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 dead-code [path]           # 未使用代码（默认豁免 claude-plugin/）
+code-graph-mcp dead-code --ignore tmp/ --ignore scripts/bin/  # 自定义豁免前缀
+code-graph-mcp dead-code --no-ignore      # 关掉默认豁免，看完整列表
 code-graph-mcp health-check              # 索引健康
 ```
 
diff --git a/npm/darwin-arm64/package.json b/npm/darwin-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-arm64",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "code-graph-mcp binary for macOS ARM64",
   "license": "MIT",
   "repository": {
diff --git a/npm/darwin-x64/package.json b/npm/darwin-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-x64",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "code-graph-mcp binary for macOS x64",
   "license": "MIT",
   "repository": {
diff --git a/npm/linux-arm64/package.json b/npm/linux-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-arm64",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "code-graph-mcp binary for Linux ARM64",
   "license": "MIT",
   "repository": {
diff --git a/npm/linux-x64/package.json b/npm/linux-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-x64",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "code-graph-mcp binary for Linux x64",
   "license": "MIT",
   "repository": {
diff --git a/npm/win32-x64/package.json b/npm/win32-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-win32-x64",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "code-graph-mcp binary for Windows x64",
   "license": "MIT",
   "repository": {
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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.11.1",
-    "@sdsrs/code-graph-linux-arm64": "0.11.1",
-    "@sdsrs/code-graph-darwin-x64": "0.11.1",
-    "@sdsrs/code-graph-darwin-arm64": "0.11.1",
-    "@sdsrs/code-graph-win32-x64": "0.11.1"
+    "@sdsrs/code-graph-linux-x64": "0.11.2",
+    "@sdsrs/code-graph-linux-arm64": "0.11.2",
+    "@sdsrs/code-graph-darwin-x64": "0.11.2",
+    "@sdsrs/code-graph-darwin-arm64": "0.11.2",
+    "@sdsrs/code-graph-win32-x64": "0.11.2"
   }
 }
diff --git a/src/cli.rs b/src/cli.rs
@@ -128,6 +128,23 @@ fn has_flag(args: &[String], flag: &str) -> bool {
     args.iter().any(|a| a == flag)
 }
 
+/// Collect all repeated values for a flag (e.g. `--ignore a --ignore b` → ["a","b"]).
+fn collect_flag_values(args: &[String], flag: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut i = 0;
+    while i < args.len() {
+        if args[i] == flag {
+            if let Some(v) = args.get(i + 1) {
+                out.push(v.clone());
+                i += 2;
+                continue;
+            }
+        }
+        i += 1;
+    }
+    out
+}
+
 /// Get a flag value that represents a file path, normalizing `./` prefix.
 fn get_path_flag<'a>(args: &'a [String], flag: &str) -> Option<&'a str> {
     get_flag_value(args, flag).map(|p| p.strip_prefix("./").unwrap_or(p))
@@ -2077,13 +2094,38 @@ pub fn cmd_dead_code(project_root: &Path, args: &[String]) -> Result<()> {
     let compact = !has_flag(args, "--no-compact");
     let json_mode = has_flag(args, "--json");
 
+    // --ignore <pref>: repeatable, prefix-match exclusion. --no-ignore disables defaults.
+    // Default = claude-plugin/ (hook/lifecycle scripts the AST graph can't reach).
+    let ignore_prefixes: Vec<String> = if has_flag(args, "--no-ignore") {
+        Vec::new()
+    } else {
+        let explicit: Vec<String> = collect_flag_values(args, "--ignore");
+        if explicit.is_empty() {
+            crate::domain::default_dead_code_ignores()
+        } else {
+            explicit
+        }
+    };
+
     let ctx = CliContext::open(project_root)?;
     let conn = ctx.db.conn();
 
-    let results = queries::find_dead_code(conn, path_filter, type_filter, include_tests, min_lines, 200)?;
+    let raw = queries::find_dead_code(conn, path_filter, type_filter, include_tests, min_lines, 200)?;
+    let pre_count = raw.len();
+    let results: Vec<_> = raw.into_iter()
+        .filter(|r| !ignore_prefixes.iter().any(|p| r.file_path.starts_with(p)))
+        .collect();
+    let ignored = pre_count - results.len();
 
     if results.is_empty() {
-        eprintln!("[code-graph] No dead code found.");
+        if ignored > 0 {
+            eprintln!(
+                "[code-graph] No dead code found after filtering; {} suppressed by --ignore (use --no-ignore to see them).",
+                ignored,
+            );
+        } else {
+            eprintln!("[code-graph] No dead code found.");
+        }
         return Ok(());
     }
 
diff --git a/src/domain.rs b/src/domain.rs
@@ -103,6 +103,18 @@ pub fn is_test_symbol_or_annotated(name: &str, file_path: &str, is_test_from_ast
     is_test_from_ast || is_test_symbol(name, file_path)
 }
 
+// -- Dead-code ignore defaults --
+/// Path-prefix defaults for `find_dead_code` ignore_paths.
+///
+/// Shell-invoked entry points (Claude Code plugin hook handlers, lifecycle
+/// scripts, auto-update hooks) are not in the static AST call graph because
+/// their callers are settings.json hook definitions / shell commands, not
+/// JS imports. Without this default they dominate orphan results with false
+/// positives. Callers wanting the unfiltered list pass `ignore_paths: []`.
+pub fn default_dead_code_ignores() -> Vec<String> {
+    vec!["claude-plugin/".to_string()]
+}
+
 // -- Node type normalization --
 /// Normalize shorthand type filter into canonical AST node types.
 /// Shared by CLI and MCP tool implementations.
diff --git a/src/main.rs b/src/main.rs
@@ -170,6 +170,8 @@ fn print_help() {
     println!("    --impact            Show impact summary (show; alias: --include-impact)");
     println!("    --context-lines N   Surrounding source lines (show; default: 0)");
     println!("    --min-lines N       Min lines to report (dead-code; default: 3)");
+    println!("    --ignore <prefix>   Exclude path prefix (dead-code; repeatable; default: claude-plugin/)");
+    println!("    --no-ignore         Disable default --ignore prefixes (dead-code)");
     println!("    --relation <type>   Filter: calls, imports, inherits, implements (refs)");
     println!("    -h, --help          Show this help message");
     println!("    -V, --version       Show version");
diff --git a/src/mcp/server/mod.rs b/src/mcp/server/mod.rs
@@ -782,6 +782,7 @@ impl McpServer {
             // to the exact matches so callers disambiguate the real collision.
             let suggestions = exact.iter().map(|c| json!({
                 "name": c.name, "file_path": c.file_path, "type": c.node_type,
+                "node_id": c.node_id, "start_line": c.start_line,
             })).collect();
             return Ok(FuzzyResolution::Ambiguous(suggestions));
         }
@@ -790,36 +791,36 @@ impl McpServer {
         } else if !candidates.is_empty() {
             let suggestions = candidates.iter().map(|c| json!({
                 "name": c.name, "file_path": c.file_path, "type": c.node_type,
+                "node_id": c.node_id, "start_line": c.start_line,
             })).collect();
             Ok(FuzzyResolution::Ambiguous(suggestions))
         } else {
             Ok(FuzzyResolution::NotFound)
         }
     }
 
-    /// Check if a symbol name is ambiguous (exists in multiple files).
+    /// Check if a symbol name is ambiguous (multiple non-test definitions).
+    /// Fires on both cross-file collisions AND same-file multi-definitions
+    /// (e.g. two `fn new()` in one module for different impl blocks) — the
+    /// latter needs `node_id`/`start_line` to disambiguate because `file_path`
+    /// alone doesn't uniquely identify the target.
     /// Returns Some(suggestions) if ambiguous, None if unambiguous or not found.
     fn disambiguate_symbol(&self, name: &str) -> Result<Option<Vec<serde_json::Value>>> {
         let candidates = queries::get_nodes_with_files_by_name(self.db.conn(), name)?;
         let non_test: Vec<_> = candidates.iter()
             .filter(|nf| !is_test_symbol(&nf.node.name, &nf.file_path))
             .collect();
         if non_test.len() > 1 {
-            let mut seen_files = std::collections::HashSet::new();
-            for nf in &non_test {
-                seen_files.insert(nf.node.file_id);
-            }
-            if seen_files.len() > 1 {
-                let suggestions: Vec<_> = non_test.iter().map(|nf| {
-                    json!({
-                        "name": &nf.node.name,
-                        "file_path": &nf.file_path,
-                        "type": &nf.node.node_type,
-                        "node_id": nf.node.id,
-                    })
-                }).collect();
-                return Ok(Some(suggestions));
-            }
+            let suggestions: Vec<_> = non_test.iter().map(|nf| {
+                json!({
+                    "name": &nf.node.name,
+                    "file_path": &nf.file_path,
+                    "type": &nf.node.node_type,
+                    "node_id": nf.node.id,
+                    "start_line": nf.node.start_line,
+                })
+            }).collect();
+            return Ok(Some(suggestions));
         }
         Ok(None)
     }
diff --git a/src/mcp/server/tools.rs b/src/mcp/server/tools.rs
diff --git a/src/mcp/tools.rs b/src/mcp/tools.rs
diff --git a/src/storage/queries.rs b/src/storage/queries.rs
diff --git a/tests/integration.rs b/tests/integration.rs

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-darwin-arm64",`
`3`		`- "version": "0.11.1",`
	`3`	`+ "version": "0.11.2",`
`4`	`4`	`"description": "code-graph-mcp binary for macOS ARM64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-darwin-x64",`
`3`		`- "version": "0.11.1",`
	`3`	`+ "version": "0.11.2",`
`4`	`4`	`"description": "code-graph-mcp binary for macOS x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-linux-arm64",`
`3`		`- "version": "0.11.1",`
	`3`	`+ "version": "0.11.2",`
`4`	`4`	`"description": "code-graph-mcp binary for Linux ARM64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-linux-x64",`
`3`		`- "version": "0.11.1",`
	`3`	`+ "version": "0.11.2",`
`4`	`4`	`"description": "code-graph-mcp binary for Linux x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`