用途:对照代码审计源码注释,只报告已确认的注释与实现不符或纯噪音,除非用户另行要求修复,否则不修改文件。
范围:接受零个或多个文件或目录路径;无参数时使用当前仓库根目录。路径从当前工作目录解析,无法读取的路径需报告。发现 JavaScript、JSX、TypeScript、TSX 和 Go 源文件。默认排除测试、testdata、fixtures、快照和 stories;排除生成、vendor、依赖、覆盖率、缓存和构建输出目录;排除压缩 JavaScript 和生成的 Go 文件。显式指定的测试文件或目录只覆盖测试排除项,生成、vendor、压缩和构建输出文件仍被排除,除非用户明确要求。可用时使用仓库感知发现方式(git ls-files 或 rg --files),保留用户路径顺序,不设任意结果上限。
分析:将文件分成约十个一批,支持时交给只读子代理并行处理,否则直接检查。对每行、块和文档注释,将声明与相邻代码、引用符号、调用方、配置及相关仓库历史比对。仅分类明确发现:STALE(描述代码已不具备的行为)、ORPHANED(引用已不存在的符号、路径、标志或概念)、MISLEADING(实质暗示与实现不同的行为)、REDUNDANT(仅复述自解释代码,无意图、约束或上下文)。不报告风格偏好、措辞不佳、有用理由或不确定项。
Go 行为性注释:编译器与工具指令(如 //go:*、//line、//nolint)、构建约束及其位置、import "C" 的 cgo 前导、go:embed 模式及其填充的声明、包注释与导出符号文档、并发/所有权/锁定/生命周期/安全契约,均视为程序行为或必需文档,不得仅因相邻声明显而易见就标为冗余。
验证与报告:汇总去重候选发现,重新打开每个位置确认当前行号和证据,无法验证的丢弃。干净结果有效,不应以低置信观察填充。报告包含范围、分析文件数、确认数、未审查数,以及按 STALE、ORPHANED、MISLEADING、REDUNDANT 分类的发现;省略空分类和未审查部分。全部审查且无发现时以 Clean 开头;有文件未审查时以 Review incomplete 开头。若已请求并应用修复,以 Comments fixed 开头并附 Changed 与 Verification,不将写入回执并入 Clean。分类标记、路径、行号、指令和引用注释文本保持原样。