dead-code

GitNexus 死代码检测器

仅 CLI — 不存在 MCP 服务。切勿对 gitnexus:// URI 使用 readMcpResource。

使用 GitNexus 知识图谱查找孤立函数、悬空导入、孤立文件和不可达代码。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生变化，或需要使用变通方法，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

适用场景

• 定期清理代码库
• 重大版本发布前缩减代码范围
• 重构后查找新出现的孤立代码
• “有没有未使用的函数？”

针对特定语言的死代码工具（vulture、knip、clippy），请改用 quality-tools:dead-code-detector。此技能使用 GitNexus 图谱进行跨文件结构分析。

工作流

步骤 0：预检 — 确保 CLI 可调用

gitnexus 二进制文件通过 npm/mise 安装。如果当前项目未启用 node，mise shim 可能会失败。运行任何 gitnexus 命令前，请先执行此预检：

# Test if gitnexus is actually callable (not just a broken shim)
gitnexus --version 2>/dev/null || mise use [email protected]

以下所有命令均从仓库根目录运行。如果工作区中索引了多个仓库，请添加 --repo <repo-name> 指定目标。否则，--repo 为可选项。

步骤 1：索引过期时自动重新索引

gitnexus status

如果索引已过期（索引的提交 ≠ HEAD），请在继续前自动重新索引，不要询问用户：

gitnexus analyze

然后再次检查状态，确认索引为最新。

步骤 2：运行 Cypher 查询

运行以下 4 个查询，检测不同类别的死代码：

孤立函数

没有传入 CALLS 边且不参与任何流程的函数：

gitnexus cypher "MATCH (f:Function) WHERE NOT EXISTS { MATCH ()-[:CALLS]->(f) } AND NOT EXISTS { MATCH ()-[:STEP_IN_PROCESS]->(f) } RETURN f.name, f.file, f.line ORDER BY f.file LIMIT 50"

悬空导入

置信度较低（< 0.5）的导入边，表示引用可能已失效：

gitnexus cypher "MATCH (a)-[r:IMPORTS]->(b) WHERE r.confidence < 0.5 RETURN a.name, b.name, r.confidence, a.file ORDER BY r.confidence LIMIT 30"

死代码（不可达）

从任何入口点都无法到达的函数——没有调用者，也不属于任何流程：

gitnexus cypher "MATCH (f:Function) WHERE NOT EXISTS { MATCH ()-[:CALLS]->(f) } AND NOT EXISTS { MATCH ()-[:STEP_IN_PROCESS]->(f) } AND NOT f.name STARTS WITH '_' AND NOT f.name STARTS WITH 'test_' RETURN f.name, f.file, f.line ORDER BY f.file LIMIT 50"

孤立文件

没有导入其他文件，也没有被其他文件导入的文件：

gitnexus cypher "MATCH (f:File) WHERE NOT EXISTS { MATCH (f)-[:IMPORTS]->() } AND NOT EXISTS { MATCH ()-[:IMPORTS]->(f) } RETURN f.path ORDER BY f.path LIMIT 30"

步骤 3：筛选结果

排除误报：

• 测试文件（**/test_*、**/tests/*、**/*_test.*）——测试函数确实可能“未被调用”
• __init__ 文件——可能确实为空，或用于重新导出
• 入口点（main、cli、__main__）——由运行时调用，而非由其他代码调用
• 以下划线 _ 开头的私有辅助函数——可能通过动态分派使用

步骤 4：结构化报告

按模块/目录分类呈现：

## Dead Code Report

### Orphan Functions (N found)
| Function | File | Line |
|----------|------|------|
| ...      | ...  | ...  |

### Dangling Imports (N found)
| Source | Target | Confidence |
|--------|--------|------------|
| ...    | ...    | ...        |

### Isolated Files (N found)
- path/to/file.py
- ...

### Summary
- Total orphans: N
- Total dangling: N
- Total isolated: N

注意事项

• 结果取决于索引是否为最新——如果结果看起来不正确，请重新索引
• 图谱仅记录静态关系——动态分派、反射和插件加载可能导致误报
• 请使用 quality-tools:dead-code-detector 进行特定语言分析（vulture、knip、clippy），以补充此结构视图

执行后反思

此技能执行完毕后，请在结束任务前进行反思：

0. 找到技能文件。 — 编辑前找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些地方比预期更顺利？ — 将其纳入推荐实践。
3. 哪些内容发生了变化？ — 修复任何与现实不符的脚本、引用或依赖项。
4. 记录下来。 — 添加演进日志条目，记录触发原因、修复内容和证据。

不要拖延。下一次调用会继承你留下的一切。