用途:对照代码审计源码注释,只报告已确认的注释与实现不符或纯噪音,默认不修改文件,除非用户单独要求修复。
范围:接受零个或多个文件或目录路径;无参数时使用当前仓库根目录。路径从当前工作目录解析,无法读取的路径需报告。发现 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、ORPHANED、MISLEADING、REDUNDANT 分类的发现;空分类和未审查部分省略。全部审查且无发现时以 Clean 开头;有文件未审查时以 Review incomplete 开头;已应用修复时以 Comments fixed 开头并附 Changed 与 Verification。分类标记、路径、行号、指令和引用注释文本保持原样。完成需给出确切范围、分析文件数、带当前行和证据的确认发现,以及无法审查的文件。