用途
footgun-scan 用于扫描 Kotlin 或 Compose Multiplatform 的代码差异（diff），查找已知的“footgun”代码形态。它属于 maxrave-dev/kotlin-footguns 技能集，核心脚本为 scripts/scan.py。该工具匹配的是代码形态而非确定的 bug，每个命中都需要结合对应 trap 文件的判断条件来确认是否真正构成问题。
主要能力
scripts/scan.py 将 32 种模式与变更中新增的代码行进行匹配。每个模式都绑定到 kotlin-footguns 技能区中的一个 trap 文件。扫描结果分为两类：likely hit（疑似命中）和 look hit（需检查的命中）。疑似命中除非满足 trap 中列出的例外条件，否则默认视为问题；look hit 则是 trap 建议在信任代码前需要检查的位置。同一检测器在同一文件中的命中会被分组，可先对整组进行一次判断，再检查列出的各行是否存在例外。
使用方式
在用户的 git 仓库内运行，并将本技能的基础目录作为 <skill>：
python3 <skill>/scripts/scan.py：扫描工作区和索引中自 HEAD 以来新增的行（默认，适用于未提交的工作）。python3 <skill>/scripts/scan.py --base origin/main：扫描当前分支自离开 main 以来新增的行（适用于分支或拉取请求）。python3 <skill>/scripts/scan.py --all src/：扫描指定路径下的所有行（适用于审计，但噪声更多）。- 在 pre-commit 钩子或 CI 步骤中，可添加
--fail，使任何疑似命中时以退出码 1 失败。
根据请求选择扫描范围：未提交的工作使用默认模式；分支或拉取请求使用 --base 并指定目标分支；“审计代码库”使用 --all 并缩小到相关路径。
处理命中
对每个命中进行分诊：
- 阅读命中指向的 trap 文件（即 -> 路径）。
- 阅读命中周围的代码，根据 trap 自身的条件判断是否适用。疑似命中除非满足 trap 中列出的例外条件，否则视为错误；look hit 是 trap 建议在信任代码前检查的位置。
- 对每个确认的问题，报告 trap 提供的修复方法和其 Verifying 步骤。对已排除的命中，逐行列出原因，例如“column is NOT NULL”或“the fade goes to black”。
同一检测器在同一文件中的命中会被分组：先对整组进行一次分诊，然后检查列出的各行是否存在例外。
适用场景
- 提交前检查代码变更。
- 代码审查时检查分支或拉取请求的变更。
- 对代码库进行审计。
- 作为 pre-commit 钩子或 CI 步骤的一部分。
限制
该工具需要 python3 和 git 环境。如果无法运行扫描器，可以阅读 scripts/scan.py：其中的 DETECTORS 列表给出了每个模式、其消息和对应的 trap。然后使用 Grep 工具在变更文件中运行这些模式，并以相同方式进行分诊。