名称: dead-code-check 描述: 为loom计划验证生成死代码检测配置。提供Rust、TypeScript、Python、Go和JavaScript的语言特定命令、失败模式和忽略模式。在将代码质量检查添加到loom计划中的验收标准或真理字段时使用。死代码检测通过识别存在但从未被调用的代码来捕获不完整的接线。允许工具: Read, Grep, Glob, Edit, Write, Bash 触发关键词: 死代码, dead-code, 未使用代码, 未使用导入, 未使用函数, 孤立代码, 死代码检测, 死代码检查, 代码清理, 未使用变量, 不可达代码, 接线验证

死代码检测

概述

死代码检测识别代码库中存在但从未被调用、导入或使用的代码。这是不完全功能集成的关键信号：如果您编写了一个函数但没有东西调用它，那么该功能未接线。

在loom计划验证中，死代码检查有两个目的：

接线验证：捕获已实现但从未集成的功能
代码质量：识别清理机会并减少维护负担

死代码检测在集成验证阶段尤其有价值，在此它作为最终检查，确保所有实现的代码实际连接到应用程序。

何时使用

集成验证阶段：所有实现阶段后的最终质量门，以捕获孤立代码
每阶段验收标准：实现期间的即时反馈
代码清理：重构或功能移除后
接线验证：与接线检查结合，以验证功能集成

如果实现后存在死代码，通常意味着：

功能未接线到应用程序（CLI命令未注册、路由未挂载等）
未运行的测试代码
重构后遗留的代码
不完整的实现

语言特定配置

Rust

Rust通过编译器和clippy具有内置的死代码检测。

推荐方法：使用clippy并所有警告作为错误

cargo clippy -- -D warnings

这捕获死代码加上许多其他问题（未使用导入、变量等）。

死代码特定检查：

RUSTFLAGS="-D dead_code" cargo build 2>&1

或仅针对死代码警告：

cargo clippy -- -D dead_code

失败模式：

warning: unused
dead_code
unused import
unused variable
never used
never constructed

忽略模式：

带有#[allow(dead_code)]属性的代码（有意）
测试模块（#[cfg(test)]）
主入口点（fn main()）
用于外部消费者的公共API项目
未启用的功能门后的项目

Loom计划的YAML模板：

# 在验收标准中（推荐 - 捕获比仅死代码更多）
acceptance:
  - "cargo clippy -- -D warnings"

# 在真理中（更具体的死代码检查）
truths:
  - "RUSTFLAGS=\"-D dead_code\" cargo build 2>&1 | grep -v 'Compiling' | grep -v 'Finished' | grep -q '^$'"

# 替代方案：检查clippy报告零死代码警告
truths:
  - "! cargo clippy -- -D dead_code 2>&1 | grep -q 'warning:'"

工作目录考虑：

Rust检查必须在Cargo.toml存在的位置运行。如果项目结构是：

.worktrees/my-stage/
└── loom/
    └── Cargo.toml

在阶段配置中设置working_dir: "loom"。

TypeScript

TypeScript死代码检测使用ts-prune，它查找未使用的导出。

安装：

npm install --save-dev ts-prune
# 或
bun add --dev ts-prune

命令：

npx ts-prune --error
# 或
bunx ts-prune --error

--error标志使ts-prune在找到未使用导出时以非零状态退出。

失败模式：

used in module but not exported
unused export
报告未使用导出的文件

忽略模式：

重新导出的index.ts文件（桶文件）
仅用于类型检查的类型导出
声明文件（.d.ts）
用于库消费者的公共API导出
入口点中的默认导出

配置文件（.tsprunerc）：

{
  "ignore": "index.ts|types.d.ts"
}

Loom计划的YAML模板：

# 在验收标准中
acceptance:
  - "bunx ts-prune --error"

# 在真理中（验证零未使用导出）
truths:
  - "bunx ts-prune | wc -l | grep -q '^0$'"

# 替代方案：显式检查无未使用导出
truths:
  - "! bunx ts-prune | grep -q 'used in module'"

工作目录：

在package.json和tsconfig.json存在的位置运行。

Python

Python死代码检测使用vulture，它查找未使用的代码包括函数、类、变量和导入。

安装：

pip install vulture
# 或
uv add --dev vulture

命令：

vulture src/ --min-confidence 80

--min-confidence标志（0-100）控制误报率。较高的值意味着较少的误报但可能错过一些死代码。

失败模式：

unused function
unused class
unused variable
unused import
unreachable code

忽略模式：

__init__.py文件
__all__定义（显式公共API）
魔术方法（__str__、__repr__、__eq__等）
测试文件和夹具（通常使用动态发现）
Setup.py和配置文件

配置文件（pyproject.toml）：

[tool.vulture]
min_confidence = 80
paths = ["src", "tests"]
ignore_names = ["setUp", "tearDown", "test_*"]

Loom计划的YAML模板：

# 在验收标准中
acceptance:
  - "vulture src/ --min-confidence 80"

# 在真理中（验证零问题）
truths:
  - "vulture src/ --min-confidence 80 | wc -l | grep -q '^0$'"

# 替代方案：检查特定模式
truths:
  - "! vulture src/ --min-confidence 80 | grep -q 'unused function'"
  - "! vulture src/ --min-confidence 80 | grep -q 'unused import'"

工作目录：

在Python源代码所在位置运行（通常是项目根目录或pyproject.toml存在的位置）。

Go

Go死代码检测使用staticcheck，一个全面的静态分析工具。

安装：

go install honnef.co/go/tools/cmd/staticcheck@latest

命令：

staticcheck ./...

相关检查：

U1000 - 未使用代码（函数、类型、常量、变量）
U1001 - 未使用字段

失败模式：

is unused
field .* is unused
func .* is unused
U1000检查代码
U1001检查代码

忽略模式：

库包中的导出符号（公共API）
接口方法实现（即使未直接调用，由接口要求）
分配给变量以通过反射使用的函数
当前未启用的构建标签后的代码

配置文件（.staticcheck.conf）：

checks = ["all", "-ST1000"]

Loom计划的YAML模板：

# 在验收标准中
acceptance:
  - "staticcheck ./..."

# 在真理中（验证无未使用代码）
truths:
  - "! staticcheck ./... | grep -q 'U1000'"
  - "! staticcheck ./... | grep -q 'is unused'"

# 替代方案：检查退出代码
truths:
  - "staticcheck ./... 2>&1 | wc -l | grep -q '^0$'"

工作目录：

在go.mod存在的位置运行（通常是项目根目录）。

JavaScript

JavaScript死代码检测使用unimported，它查找未使用的文件和未解析的导入。

安装：

npm install --save-dev unimported
# 或
bun add --dev unimported

命令：

npx unimported
# 或
bunx unimported

失败模式：

unresolved import
unused file
输出中列出的文件

忽略模式：

配置文件（.eslintrc.js、jest.config.js等）
入口点（index.js、main.js）
使用变量的动态导入
通过构建工具导入的文件（Webpack、Vite等）

配置文件（.unimportedrc.json）：

{
  "entry": ["src/index.js", "src/server.js"],
  "extensions": [".js", ".jsx"],
  "ignorePatterns": ["**/node_modules/**", "**/*.config.js"]
}

Loom计划的YAML模板：

# 在验收标准中
acceptance:
  - "bunx unimported"

# 在真理中（验证无未使用文件）
truths:
  - "bunx unimported | wc -l | grep -q '^0$'"

# 替代方案：检查特定问题
truths:
  - "! bunx unimported | grep -q 'unused file'"
  - "! bunx unimported | grep -q 'unresolved import'"

工作目录：

在package.json存在的位置运行。

处理误报

死代码检测工具在这些常见场景中报告误报：

1. 入口点

问题： 主函数、CLI处理程序、API路由处理程序——代码中没有直接调用它们，但它们由运行时/框架调用。

解决方案：

Rust：像fn main()这样的入口点自动排除。对于CLI子命令，确保它们在命令枚举中注册。
TypeScript/JavaScript：在工具配置中配置入口点（ts-prune、unimported）
Python：使用__all__标记公共API，vulture尊重它
Go：main包中的导出函数被排除

2. 测试代码

问题： 测试函数由测试运行器调用，而不是应用程序代码。

解决方案：

Rust：#[cfg(test)]模块中的代码自动排除
TypeScript/JavaScript：在配置中排除测试目录
Python：忽略模式如test_*、setUp、tearDown
Go：测试文件（*_test.go）自动处理

3. 框架魔法

问题： 装饰器、派生宏、隐式使用代码的注解。

示例：

Rust：#[derive(Serialize)]使用私有字段
Python：@dataclass、@property装饰器
TypeScript：Angular、NestJS等框架中的装饰器

解决方案：

使用语言特定的忽略注解
配置工具以忽略装饰项目
对于Rust，在特定项目上使用#[allow(dead_code)]

4. 公共API / 库代码

问题： 为外部消费者导出的代码在项目内显示未使用。

解决方案：

Rust：库箱中的公共项目（pub）默认排除
TypeScript：使用.tsprunerc忽略库入口点
Python：定义__all__以标记公共API
Go：库包中的导出符号（大写）被排除

5. 功能标志和条件编译

问题： 禁用功能标志或构建标签后的代码。

解决方案：

Rust：运行检查时启用相关功能（--features=all）
Go：使用构建标签包括所有变体
Python/TypeScript/JavaScript：在检查期间注释或临时启用功能

6. 动态加载和反射

问题： 动态加载或通过反射调用的代码。

解决方案：

清楚记录这些案例
使用工具特定的忽略注释
考虑执行动态代码路径的集成测试

与Loom计划集成

在计划阶段中的放置

最佳实践：集成验证阶段

死代码检查作为最终质量门最有价值：

stages:
  - id: integration-verify
    name: "集成验证"
    stage_type: integration-verify
    working_dir: "loom"
    acceptance:
      - "cargo test"
      - "cargo clippy -- -D warnings" # 包括死代码检查
    truths:
      - "! cargo clippy -- -D dead_code 2>&1 | grep -q 'warning:'"

每阶段检查：

也可以添加到单个实现阶段以获取即时反馈：

stages:
  - id: implement-auth
    name: "实现认证"
    stage_type: standard
    working_dir: "loom"
    acceptance:
      - "cargo test auth"
      - "cargo clippy --package auth -- -D warnings"

与接线检查结合

死代码检测是一个强信号但不是决定性证据。与wiring检查结合：

stages:
  - id: integration-verify
    name: "集成验证"
    stage_type: integration-verify
    working_dir: "loom"
    acceptance:
      - "cargo clippy -- -D warnings"
    wiring:
      - source: "src/main.rs"
        pattern: "Commands::NewCommand"
        description: "新命令在CLI枚举中注册"
      - source: "src/commands/mod.rs"
        pattern: "pub mod new_command"
        description: "新命令模块导出"
    truths:
      - "loom new-command --help" # 功能验证

这种三重检查方法（死代码 + 接线 + 功能）可靠地捕获集成问题。

工作目录和路径

关键提醒： working_dir字段决定命令执行的位置。

示例项目结构：

.worktrees/my-stage/
├── loom/
│   ├── Cargo.toml       <- 构建工具期望此目录
│   └── src/
└── CLAUDE.md

正确配置：

- id: verify
  working_dir: "loom" # Cargo.toml存在的位置
  acceptance:
    - "cargo clippy -- -D warnings"
  truths:
    - "test -f src/new_feature.rs" # 相对于working_dir（loom/）

错误配置：

- id: verify
  working_dir: "." # 错误 - 此处无Cargo.toml
  acceptance:
    - "cargo clippy -- -D warnings" # 失败：找不到Cargo.toml

路径解析规则： 验收、真理、工件和接线中的所有路径都相对于working_dir。

YAML最佳实践

永远不要在YAML描述中使用三重反引号

错误：

truths:
  - description: |
      像这样检查死代码：
      ```
      cargo clippy -- -D warnings
      ```
    command: "cargo clippy -- -D warnings"

这破坏YAML解析。

正确：

truths:
  - "cargo clippy -- -D warnings" # 检查死代码

或带有显式描述：

truths:
  - description: "使用clippy并所有警告作为错误检查死代码"
    command: "cargo clippy -- -D warnings"

使用-q进行静默Grep

在真理中使用grep时，使用-q（安静）标志以抑制输出：

truths:
  - "! cargo clippy -- -D dead_code 2>&1 | grep -q 'warning:'"

!否定结果（如果grep未找到任何内容，则退出0）。

退出代码检查

找到问题时以非零退出的工具可以直接使用：

acceptance:
  - "cargo clippy -- -D warnings" # 警告时以非零退出
  - "staticcheck ./..." # 问题时以非零退出
  - "bunx ts-prune --error" # 未使用导出时以非零退出

工具安装检查清单

在将死代码检查添加到计划之前，确保工具可用：

Rust：

内置：rustc、cargo
cargo install clippy（通常随rustup包含）

TypeScript：

bun add --dev ts-prune或npm install --save-dev ts-prune

Python：

uv add --dev vulture或pip install vulture

Go：

go install honnef.co/go/tools/cmd/staticcheck@latest

JavaScript：

bun add --dev unimported或npm install --save-dev unimported

将安装步骤添加到knowledge-bootstrap阶段或记录在项目README中。

示例

示例1：具有全面检查的Rust项目

stages:
  - id: integration-verify
    name: "集成验证"
    stage_type: integration-verify
    working_dir: "loom"
    acceptance:
      - "cargo test"
      - "cargo clippy -- -D warnings"
      - "cargo build --release"
    truths:
      - "test -f src/commands/new_feature.rs"
      - "! cargo clippy -- -D dead_code 2>&1 | grep -q 'warning:'"
    wiring:
      - source: "src/main.rs"
        pattern: "Commands::NewFeature"
        description: "新功能命令注册"

示例2：具有死导出检查的TypeScript API

stages:
  - id: verify-api
    name: "验证API实现"
    stage_type: integration-verify
    working_dir: "api"
    acceptance:
      - "bun test"
      - "bunx ts-prune --error"
      - "bun run typecheck"
    truths:
      - "bunx ts-prune | wc -l | grep -q '^0$'"
      - "curl -f http://localhost:3000/api/health"

示例3：Python数据管道

stages:
  - id: verify-pipeline
    name: "验证数据管道"
    stage_type: integration-verify
    working_dir: "pipeline"
    acceptance:
      - "pytest"
      - "vulture src/ --min-confidence 80"
      - "mypy src/"
    truths:
      - "! vulture src/ --min-confidence 80 | grep -q 'unused function'"
      - "test -f src/pipeline/transform.py"
    wiring:
      - source: "src/main.py"
        pattern: "from pipeline.transform import TransformStage"
        description: "转换阶段在主管道中导入"

示例4：Go微服务

stages:
  - id: verify-service
    name: "验证微服务"
    stage_type: integration-verify
    working_dir: "service"
    acceptance:
      - "go test ./..."
      - "staticcheck ./..."
      - "go build"
    truths:
      - "! staticcheck ./... | grep -q 'U1000'"
      - "! staticcheck ./... | grep -q 'is unused'"
      - "test -f cmd/server/main.go"

总结

死代码检测是loom计划的强大验证工具：

捕获不完整接线：代码存在但未被调用 = 功能未集成
语言特定工具：Rust（clippy）、TypeScript（ts-prune）、Python（vulture）、Go（staticcheck）、JavaScript（unimported）
最佳在集成验证中：所有实现阶段后的最终质量门
与接线检查结合：死代码检测 + 接线模式 + 功能测试 = 全面验证
处理误报：入口点、测试、框架魔法 — 适当配置工具
工作目录重要：设置working_dir到构建工具期望的位置（Cargo.toml、package.json、go.mod存在的位置）

在设计loom计划的验证策略时使用此技能。复制粘贴YAML模板并调整工具配置以适应项目结构。