SuperAPI AI 工具集

dead-code-auditor

编程与开发

查看项目

更新于 10-16 05:58

技能介绍

用途

Dead Code Auditor 是一个代码审计技能,用于在任意编程语言中严格查找死代码。它的目标是“外科手术式”的精确度:不产生误报,不做假设,每一项发现都必须有来自跨项目搜索的真实证据支撑。它能够适应所面对的任何语言和工具链。

主要能力

该技能检测六类死代码:

  1. 孤立文件:没有任何其他文件导入、require 或引用的文件。文件可以存在并编译通过,但如果没有任何东西引入它,它就是死代码。
  2. 未使用的类/函数/组件:类或函数可能已定义,但从未在其自身文件之外被实例化或调用。需要同时检查它是否被导入,以及该符号本身是否真的被使用。
  3. 死方法/getter/属性:在类上公开声明,但从未在该文件之外被调用。从未在内部被调用的私有方法/函数也算。
  4. 未使用的构造函数/函数参数:函数或构造函数接受一个参数,但该参数从未出现在函数体中。数据到达后即消亡。
  5. 未使用的导入/require:import、require、use、#include 或等效语句,没有为文件贡献任何符号。
  6. 被注释掉的代码:被注释掉且不承担文档用途的真实代码块。需要区分文档注释(JSDoc /** */、Python docstrings、Dart ///)和死代码注释。

使用方式

该技能遵循固定的调查工作流,要求严格按顺序执行,不得跳过步骤:

步骤 1 — 检测语言和工具链:首先识别语言(Dart、TypeScript、Python、Go、Kotlin、Swift、Java、Rust 等)、项目结构(monorepo、单包、基于功能、分层等)和模块系统(ES modules、CommonJS、Go packages、Dart imports 等)。这决定了后续使用的 grep 模式和搜索策略。技能中提供了各语言的注意事项,例如 Dart/Flutter 使用 package: 或相对路径,查找 class、mixin、enum、extension、typedef;TypeScript/JS 使用 import/require/export,查找 export class、export function、export const;Python 使用 import/from X import,查找 class、def、all;Go 中未使用的导入是编译错误,因此聚焦未使用的导出;Kotlin/Java 使用 import,查找 class、fun、val、var、object;Rust 使用 use,查找 pub fn、pub struct、pub enum、pub trait。

步骤 2 — 发现目标中的所有文件:使用 find 命令(按语言适配扩展名)获取完整文件清单。

步骤 3 — 阅读目标中的每个文件:阅读目标文件夹中的所有文件,同时提取所有导出/公开符号(类、函数、枚举、接口、类型、常量)、所有声明的导入/require、构造函数/函数参数、被注释掉的代码块,以及可能内部也未使用的私有符号。

步骤 4 — 用跨项目搜索验证每一项发现:对每个要验证的符号,搜索整个源码根目录(而不仅是目标文件夹),例如检查文件是否被导入、类/函数是否被使用、方法/getter 是否被调用、参数是否在其自身函数内被使用。技能强调黄金法则:没有搜索支撑的发现无效;如果没有搜索,就不要报告。

步骤 5 — 处理语言特定的边界情况:某些模式看起来未使用但实际并非如此,包括依赖注入容器(Get.find<T>()、Angular DI、Spring @Autowired,类可能按名称注册)、反射/动态分发(Python、Java、Kotlin 的 getattr、Class.forName、注解)、基于字符串的路由(路由名作为字符串而非符号引用)、代码生成/宏(Rust、Dart、Java 的 @GeneratedCode、build_runner、注解处理器)、re-export 桶文件(TS、Dart 的 index.ts、barrel.dart,文件可能不导入但重新导出)、抽象类/接口(无直接实例化,检查实现者/子类)、测试文件(仅在测试中使用的类仍算被使用,不要标记)、动态 require(JS/TS 的 require(someVariable),无法静态分析)。当发现这些模式时,将风险提升为 🟡 或 🔴 并解释原因。

报告格式

该技能生成 Markdown 报告,结构固定:标题为“🔍 Dead Code Audit — <path/to/folder/>”,包含执行摘要表格(类别、数量、移除风险)、估计可移除行数与文件数,然后按类别分节:孤立文件、死方法/getter/函数、未使用的构造函数/函数参数、未使用的导入、被注释掉的代码,每项发现包含描述、证据(grep 命令与结果)和移除风险。最后附上上下文说明,简要解释死代码存在的原因(例如“从 X 模式重构到 Y 模式后遗留”)。

风险等级

  • 🟢 低:搜索确认 0 引用,可安全删除。
  • 🟡 中:可能通过反射、字符串查找、DI 容器或未搜索的测试文件使用,删除前需手动验证。
  • 🔴 高:存在引用但看似间接,或是基类且搜索范围外有未知子类,未经深入审查不要删除。

在静态类型语言(Dart、严格模式的 TypeScript、Go、Rust、Kotlin)中,几乎所有死代码都是 🟢,因为引用总是显式的。在动态类型或重度反射的语言(Python、使用 Spring 的 Java、无 TypeScript 的 JS)中,应更保守,存疑时使用 🟡。

报告之后

报告末尾始终附上:“💡 Want me to generate a /plan to remove all of this safely, with intermediate verification steps and a final static analysis pass?”如果用户同意,则调用 claude-mem:make-plan 技能,传入要删除的文件完整列表、要移除的方法/getter 及其文件路径和大致行号、要移除的参数及需要更新的调用点。规则是:不改变业务逻辑,在每个阶段结束时用项目的 linter/analyzer 验证。

适用场景

适用于任何编程语言、任何模块、文件夹或文件的死代码审计,尤其适合在重构后清理遗留代码、在代码库中查找可安全删除的冗余内容,以及需要证据支撑而非主观判断的严格审计场景。

限制

该技能依赖静态搜索,无法分析动态 require 等无法静态解析的模式;对于反射、DI 容器、字符串路由等间接引用,需要人工验证,风险等级会相应提高。在动态类型或反射密集的语言中,误报风险更高,需更保守。