SuperAPI AI 工具集

stale-comments-audit

编程与开发

查看项目

更新于 10-16 03:16

技能介绍

用途:对照代码审计源码注释,修复已确认的过时、孤立、误导或冗余注释。只改注释,绝不为了让注释成立而修改可执行代码。

范围:接受零个或多个文件或目录路径;无参数时使用当前仓库根目录,路径基于当前工作目录解析,无法读取的路径需报告。发现 JavaScript、JSX、TypeScript、TSX 和 Go 源文件;默认排除测试、testdata、fixtures、snapshots、stories,以及生成、vendor、依赖、覆盖率、缓存和构建输出目录,还有压缩 JavaScript 与生成的 Go 文件。显式指定的测试文件或目录只覆盖测试排除项。可用时使用 git ls-files 或 rg --files 做仓库感知发现,保留用户路径顺序,不设任意结果上限。

分析:将文件分成约十个一批,支持时交给只读子代理,否则直接检查。逐条比较注释与相邻代码、引用符号、调用方、配置及相关历史,只分类明确发现:STALE(描述代码已不具备的行为)、ORPHANED(引用已不存在的符号、路径、标志或概念)、MISLEADING(实质暗示与实现不同的行为)、REDUNDANT(仅复述自解释代码且无意图、约束或上下文)。不报告风格偏好、措辞不佳、有用理由或不确定项。

Go 行为性注释://go:*、//line、//nolint 等指令、构建约束及其位置、cgo 前导、go:embed 模式、包注释与导出符号文档、并发与所有权等契约,均按程序行为或必需文档处理,不得仅因相邻声明明显而标为冗余。

修复与验证:汇总去重后重新打开每个候选位置,确认行号与证据,丢弃无法验证项。仅做最小注释修改:STALE 与 MISLEADING 在意图可证时重写,否则删除;ORPHANED 仅在替代项可证时更新,否则删除;REDUNDANT 直接删除。行为性 Go 注释仅在语义可证时修改,否则保留并报告未修复。写入在主执行上下文完成,不委托。重新打开改动位置确认一致,并运行最窄的格式化、lint、类型检查、测试、构建或 Go 工具验证。

报告:输出已修复数量、范围与文件统计表、按分类的修复清单、验证命令与结果,以及未修复和未审查项;无发现且全部审查时以 Clean 开头,未全部审查时以 Review incomplete 开头,存在无法安全修复项时以 Comments partially fixed 开头。分类标记、路径、行号、命令、指令和引用注释文本需保持原样。

限制:仅支持 JavaScript、JSX、TypeScript、TSX 和 Go;默认排除测试与生成文件;不修改可执行代码;无法安全判断时保留注释并报告。