ServerPackCreator 代码审计实践:测试深度、变异验证与缺陷防御

原创2026-10-15 10:44:321,459 阅读
文章标签:后端前端桌面应用CLI游戏开发

ServerPackCreator 代码审计实践:测试深度、变异验证与缺陷防御

本篇技术指南围绕开源仓库 ServerPackCreator 中的核心审计文档 claude-docs/ANALYSIS-AUDIT.md 展开。该文档是一份持续累积的代码分析审计证据日志,记录了 2026-09-05 至 2026-09-25 期间对 -clientside、-grinder、-api、-app 及多个插件模块的十二轮测试深度与缺陷分析。读完本文,你将掌握这套审计体系的方法论内核:如何区分"覆盖率"与"测试深度"、如何用变异验证(mutation verification)证明一个测试真的能拦住回归、如何识别"通过却什么都没断言"的伪 guard,以及一份可直接复用到其他项目的审计检查清单。文中所有结论均可在仓库源码与测试中逐一核对。

一、文档定位:一份只追加、永不覆盖的证据日志

ANALYSIS-AUDIT.md 自述为 "accumulating evidence log",维护规则只有一条:Appended to, never overwritten——只追加,从不覆盖。每条记录带日期,测量数据、变异验证结果与 "verified clean, do not re-litigate"(已验证干净,勿再翻案)清单永久有效。

这一设计解决的是长期审计项目的两个核心问题:

  1. 结论可追溯:任何一天发现的问题、给出的修复、以及"为什么判定为不是问题"的理由都留档,后人不必重新推导。
  2. 避免重复劳动:每轮审计末尾的 "verified clean — do not re-litigate" 清单明确列出已被证伪或已确认无害的疑点(例如 CurseForge API key 只出现在构造参数与 headers 映射中、VerdictStore.hasVerdictFor 不是缺口、阶梯排序 16 级全部被 pin),下一轮审计直接从更短的疑点清单开始,而不是从头再来。

文档与同目录下的 claude-docs/REFACTOR-AUDIT.md 形成分工:后者负责提交卫生与约定合规(每个 fix: 提交前必须有对应的红色 test: 提交),前者负责"测试到底断言了什么、改动的代码还有什么没被覆盖"。两篇文档同日的条目互相交叉引用而非重复叙述。

二、审计方法:镜头、度量与全仓扫描

2.1 每轮审计先声明"镜头"(Lens)

每轮审计开头会明确本次的观察视角,例如:

  • 2026-09-05:"guards asserting a unit no caller reaches, tests constructing the value under test, and partially-pinned ordering invariants"——寻找没有任何调用者到达的 guard、构造被测值本身的测试、以及只被部分 pin 住的排序不变量。
  • 2026-09-09:"what the relaxed rule now lets through, functions that are not total, and stated orderings nothing asserts"——宽松规则放行了什么、哪些函数不是全函数(total)、哪些文档声称的排序没有任何断言。
  • 2026-09-20 第三遍(迭代 3):"deliberately looked where the first two had not: at the consumers of the value"——故意去看前两遍没看的地方:值的消费者。

这种"每次换一个镜头"的做法保证多轮审计不会在同一层面空转。

2.2 度量优先于推理

文档反复强调两个实测事实的价值。2026-09-11 迭代 1 开头就记录了:**fabric-api-0.116.17+1.21.1.jar(从真实构件读取)**的顶层描述符是 id = "fabric-api"、provides = ["fabric"],它随包携带 49 个嵌套 jar,而 fabric-resource-loader-v0 只以 META-INF/jars/fabric-resource-loader-v0-0.116.17.jar 的形式存在。这个测量直接决定了一个审计发现的方向(见下文 A-1 的 unless 分支问题)。

另一个典型测量:ServerPackUpdater.protects() 在单次更新中对每个文件调用一次,看起来像是热循环不变量的反面教材。实测 20,000 条路径后,protects() 全程 12.0 ms(其中构建 TreeSet 的 getter 占 2.5 ms),把列表提升到循环外一次反而要 12.7 ms——结论是"不值得缓存"。文档称这是 "the B30 lesson again — measure before optimising, and record the negative result so nobody re-opens it":负面结果也要记录,防止后人重新打开这个优化问题。

2.3 全仓孤儿扫描(orphan sweep)

2026-09-05 的方法注记说明了一个关键陷阱:孤儿扫描必须全仓库进行,而不是单模块。仅扫描 -clientside 的 src/main 就报告了 17 个误报,因为 ClientsideListEditor、BootArtifacts、AttemptDirectory 会被 -app 和 -grinder 调用,且方法引用(::current、cache::evictUnusedSince)不是调用语法。统计调用、:: 引用与 override 声明后,30 个候选缩减为 4 个,其中 2 个是文档化的测试缝隙(test seam)、1 个被驳回。

三、测试深度与覆盖率的边界:guard 应该 pin 什么

文档最重要的方法论区分是:覆盖率回答"有多少行被执行过",测试深度回答"一个错误值会不会被测试抓住"。后者才是审计的关注点。

3.1 手写 18 字段映射只断言 5 个(M-1)

Grinder.kt 中 store.record(GrindVerdict(...)) 从 LoaderVerdict 手工复制 18 个字段。唯一驱动 grind 并检查记录结果的 GrinderTest 只断言了 bootedLoader、declaredClientSide、declaredServerSide、jarScan、suggestedEntry 五个,未断言的有 verdict、declared、firedRule、decidedBy、stagedDependencies、filenamePattern、detail。更糟的是:所有报告、CSV、查询与过滤测试都通过 grindVerdict(...) 辅助函数直接构造 GrindVerdict,所以没有任何测试能看到"生产者填错字段"的场景——这正是 unsatisfiedLabel 能通过测试却让两个平台都喂给它错误 slug 的同类形状。

失败场景很具体:把 filenamePattern = verdict.suggestedEntry,或把 declared 与 declaredServerSide 互换,整个测试套件依然全绿,而 /as-properties 与报告表会发布错误的列——其中 verdict 是发布闸门(publication gate)读取的字段,危害最大。

修复(同日):新增 RecordedVerdictMappingTest,用一个 fake CandidateVerifier 返回 LoaderVerdict 全部 18 个字段携带各不相同哨兵值(SENTINEL)的 ClientsideReport,跑 Grinder.grind 后逐一断言。变异验证确认两个预测的错误接线都会失败:

filenamePattern = verdict.suggestedEntry        -> "'SENTINEL_FILENAME' was dropped by the mapping"
declaredClientSide = verdict.declaredServerSide -> "expected: <REQUIRED> but was: <UNSUPPORTED>"

文档强调:"Distinctness is the mechanism, not decoration"——不同字段必须用不同的哨兵值,因为相等的值检测不出交换。两个 DeclaredSupport 字段故意取不同常量,且没有两个枚举哨兵共用名字。

3.2 四臂偏好的内部次序(M-2)

BootCandidateSelector.kt 的 pickDependencyFile 背后是一个四臂偏好阶梯(preferenceLadder):

pickFrom(satisfying.filterNot { locked })   // 1  可获取 且 满足约束
  ?: pickFrom(files.filterNot { locked })   // 2  可获取 但 违反约束
  ?: pickFrom(satisfying)                   // 3  被锁定 但 满足约束
  ?: pickFrom(files)                        // 4  全部兜底

当时的测试覆盖了"锁定 vs 可获取(无约束)"(臂 1/2 vs 3/4)、"可获取性优先于精确 loader 匹配"、以及"全部锁定仍返回文件"(臂 4),但臂 2 与臂 3 的相互作用没有被覆盖——没有一个测试让"锁定但满足约束"的文件与"未锁定但违反约束"的文件竞争,而这是唯一能把臂 2 和臂 3 区分开的场景。把臂 2、3 交换后套件依然全绿,选择器会重新偏好不可获取的文件,重蹈 2026-09-04 修复过的 306612 / Fabric-API 拒绝事件(症状是一个 ERROR 裁决覆盖掉决定性的那个)。

修复(同日):BootCandidateSelectorTest 新增两个测试——anObtainableFileBeatsALockedOneThatSatisfiesTheConstraint pin 住"可获取性压过版本约束",betweenTwoObtainableFilesTheConstraintStillDecides 作为反向砝码防止可获取性从"偏好"变成"覆盖"。变异验证:交换两臂后失败于 expected: <lib-0.9.0.jar> but was: <lib-1.5.0.jar>。

3.3 纯决策应当被直接 pin

文档明确的项目偏好:纯函数决策直接做单元测试,而不是通过间接的集成路径。典型例子:

  • 2026-09-08 的 A-4:backtrackReason——区分"该项目没发布任何可用东西"与"我们把它们全部排除了"的谓词——只能通过两条 staging 路径到达,且三个分支只被覆盖了一个。它是接收 ProjectFiles 和 Set<String> 的纯函数,是典型的单元测试领地。
  • 2026-09-09 的 M-2:BootVerifier.preventionCauseFor 不是全函数,对空 map 会抛 NoSuchElementException(PreventionCause.entries.first { it in causes })。当时唯一的调用点 refuseForMissingDependencies 在到达前就返回 null 了,所以不可达——但"今天不可达"正是这个仓库付过两次学费的形状(UnmetReason.explain 返回 null 导致两处日志在后续编辑后会打印字面 null.)。修复:空集合返回 PreventionCause.HOST(与所有其他预防点一致的"最大声解读"默认值)并 pin 住。
  • 2026-09-08 的 A-5:五个 UnmetReason 值中有两个(DISTRIBUTION_LOCKED、UNRESOLVED)只在渲染拒绝字符串处被断言(DependencyLabelTest),从未在"选择原因"处被断言。修复通过真实 staging 到达这两个值,并意外暴露了一个不忠实的 fake:测试下载器忽略了 downloadUrl,导致被锁定的文件"被下载成功",用例变成了 backtrack。

3.4 从 entries 派生,而不是手写清单

2026-09-09 的 M-3 与 M-4 指向同一类腐烂:枚举裁决列表被手写死,新成员悄悄漏掉。

  • VerdictPublicationTest 断言"损坏的主机不发布",专门防二十行 ERROR 洪水,但 2026-09-09 新增的 LOCKED 与 UNVERIFIABLE 恰好在它要保护的人群里,却不在任何断言中。
  • VerdictColumnTest.attemptRetentionAgreesWithVerdictRetention 迭代 listOf(CONFIRMED, INCONCLUSIVE, ERROR) 断言 keepsLogs,自称是 drift guard,却只覆盖六个裁决中的四个。

修复方式一致:从 Verdict.entries 派生。onlyConfirmedIsEverPublished 驱动渲染器跑过 entries 的每一行,断言只有 CONFIRMED 被发布;everyVerdictIsClassifiedForRetention 按 grindRan 分区断言——一个第七种裁决被加进来时会自动进入断言范围,无需编辑测试。可以对照 Verdict.kt 验证:六个裁决各自的 keepsLogs 与 grindRan 都是显式声明的构造参数,其中 LOCKED/UNVERIFIABLE 因"没有容器运行、无物可留"而 keepsLogs = false。

四、变异验证:唯一能证明 guard 有牙齿的方法

贯穿全部十二轮审计的最强方法论,是变异验证:故意破坏生产代码,观察哪个 guard 变红。文档的态度斩钉截铁:"Mutation is not a finishing flourish here; it is the only way this project's guards have been shown to have teeth."

4.1 一打变异实例

审计轮次 破坏方式 结果
09-05 M-1 交换 filenamePattern = verdict.suggestedEntry、declaredClientSide = declaredServerSide RecordedVerdictMappingTest 红,消息精确到字段名
09-05 M-2 交换臂 2 和臂 3 expected: <lib-0.9.0.jar> but was: <lib-1.5.0.jar>
09-05 阶梯 把 mixin-apply-failure 提升到 client-only-class 之上 16 级阶梯的整体 pin 失败
09-08 A-3 交换 nestedVersions(...) + scanned… 操作数 优先级 guard 失败于 create-6.0.8.jar 代替 create-6.0.10.jar,套件其余部分无感知
09-09 M-5 addIfAbsent → add 并发学习者 guard 失败
09-09 L-1 提升约束层级 anExactVersionTheConstraintRejectsBeatsANeighbourItAccepts 失败
09-11 A-2 强制 fromCurseForge 返回 RELEASE 两个新的 CurseForge guard 失败
09-11 A-3 把频道过滤器提升到可用性闸门之上 其 guard 失败
09-20 M4 normalize() 停止转换 \\→/;prune 改用 File(relative);startsWith("$protected/") 放宽为 startsWith(protected);zip 过滤器改为仅当开关开启时安装;readManifest 停止捕获 各自对应的 guard 逐一失败
09-23 A-6 移除"已回收 id 集合" anOrphanWithBothAnArchiveAndAnExtractedDirectoryIsReclaimedOnce 失败
09-25 A7 移除 PortAllocator.allocate 的 @Synchronized concurrentAllocationsNeverCollide 失败

4.2 三条铁律

  1. 先写红色 pin,再写修复。文档中的每轮修复几乎都遵循 "red-pinned first":先写一个在现存(有缺陷的)代码上变红的测试,再修复让它转绿。09-20 的 H1 修复就是这样:b57efd7e2 先写红 pin,5bc4e2743 修复。
  2. 不能编译的变异毫无意义。2026-09-11 迭代 1 的记录提供了一个差点造成错误结论的真实事故:A-2 变异的第一轮运行报告了"错误的"失败测试——因为一次正则编辑留下了一个孤立的 when 主体,构建从未编译,解析器愉快地读取了上一轮的 test-results XML。变异检查的输出看起来和真实结果一模一样。因此:变异运行前必须清理 build/test-results,且把"无结果"当作与"零红"不同的独立结果对待。
  3. 运行 pin 后才能提交。09-08 的记录总结:新增 guard 中有两个先红,且两次故障都在测试本身——一个比真实更强大的 fake,和一个函数永远不会被问及的问题。二者在读到失败文本前都像代码缺陷。

五、HIGH 缺陷案例研究

5.1 首次生成 + 更新开关:本地 variables.txt 丢失(H1,2026-09-20)

这是文档中最具代表性的"隐蔽回归"案例。ServerPackHandler.kt 在生成流程中先写 manifest.json,而 ServerPackUpdater.isUpdateRun 恰好用"manifest.json 是否存在"来判断本次是否为更新——于是在一次运行的中间,isUpdateRun 从 false 翻转为 true。

首次生成时的序列是:

  1. :359 写入压缩版 variables.txt(preserve 为 false,因为文件还不存在);
  2. :375 本应用本地变体覆盖它——只有本地变体携带用户配置的 SPC_JAVA_SPC Java 路径——但此时 variables.txt 已存在且受保护,isUpdateRun 为 true,preserve 返回 true,本地变体永远写不出去。

结果:数据包保留的是压缩包里的副本,其 SPC_JAVA_SPC 已被替换成字面量 "java"(ServerPackProvisioner.kt:500-503)。该缺陷用探针实测确认(同一配置在 @TempDir 中生成两次,仅切换开关):更新开启 + 首次生成 + 期望 zip 时,variables.txt 不含配置的 Java 路径;对照组则包含。

修复:在写入任何文件之前一次性快照"哪些 provisioned 文件已经存在",图标、server.properties、运行文件决策全部读取同一份快照。preserve lambda 闭包捕获快照而非重复推导,彻底消除"同一个值在一次运行中读两次可能不一致"的意外。对照 ServerPackHandler.kt 可以看到 preserved 集合在写入前构建的注释性证据。

5.2 Content-Disposition 头注入(A-2,2026-09-23)

ModPackController.kt 原实现直接把客户端提供的文件名插入响应头:

.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"${modpack.get().name}\"")

ModPack.name 是上传文件的原始文件名——攻击者可控,且 landingName 现在故意保留原名(只剥离路径分隔符)。含 " 的名字会提前闭合引号,含 "; 的能追加第二个参数。该端点无认证且带 @CrossOrigin("*");Tomcat 拒绝 CR/LF,所以这是头参数注入而非响应拆分,但仍是公共路由上未校验的数据进入响应头。

修复经历了三次尝试,中间一次是文档明说的教训:用 Spring 的 ContentDisposition.parse 解析头再与原文件名比较,对注入也通过——因为解析器是宽容的,能从转义与未转义两种形式中恢复出 evil".zip"; filename="other.exe。最终断言落在原始头上:移除转义对后必须恰好剩两对引号。修复后的代码已改为 ContentDisposition.attachment().filename(...).build().toString()(RFC 6266 编码),可在 ModPackController.kt 中看到。

5.3 错误形状的 200 读作"无裁决"(A-3,2026-09-06)

GrinderClient.readVerdicts 在文档既非数组、也不携带 verdicts 数组时返回 emptyList()。于是一个返回 {"error":"…"} 加 200 的代理或未来守护进程,会被读成 FetchResult.Ok(emptyList()),标签页报告 "0 confirmed, 0 other verdicts"——与一个真正什么都没磨的 grinder 无法区分。讽刺的是,已有 guard 叫 reportsAnUnparseableBodyRatherThanReturningNothingFound,但它只覆盖非 JSON,它名字所声称的案例正是它漏掉的案例。

5.4 grinder 文本进入 HTML 解释型 Swing 组件(A-2,2026-09-06 + 2026-09-25)

这是一个安全发现:slug 与 detail 来自 mod 元数据,而 grinder 守护进程无认证。Swing 的 HTML 子集会获取远程图片,所以一个精心构造的 mod 名能让 SPC GUI 发出外联请求。2026-09-25 的 servertest 分支又确认了三个 HTML 注入面:包表格(getColumnClass 返回 Object,HTML 禁用渲染器从未被咨询,实测 rendered view is HTML = true)、warn() 对话框(String 消息到 JOptionPane 会安装 HTML 视图)、以及控制台子标签标题(PLAUSIBLE,未测量)。

5.5 启动编排未测试 + 下拉框接线未 pin(A1 / B1,2026-09-25)

  • A1:ServerTestTab.launch 约 60 行决策——拒绝已在运行的包、分配端口、仅当 RCON 开启时分配第二个端口、借用 server.properties、构建会话、启动前注册、无论运行如何结束都恰好归还一次端口与文件——完全未覆盖。givenBack 的 AtomicBoolean 之所以存在,正是因为归还路径可达两次。这是 MVC 层面的发现:"视图持有控制器"。修复:把编排提取到 core 的 ServerLauncher/LaunchOutcome,7 个 guard 覆盖拒绝、端口数、借用失败路径与双重归还;RealPackBootTest 改走生产路径(对 NeoForge fixture 实测 Done (3.995s)!,fixture 逐字节不变)。
  • B1:PackListPane 的 scriptChoice.addActionListener { onScriptChanged() }——删掉这一行整个套件依然全绿(实测)。下拉框会变成摆设。既有选择 guard 直接调用 pane.show(...),那是回调最终造成的结果而不是回调本身。修复:通过真实组件设置下拉框选择并断言回调运行——唯一穿越监听器的断言。

六、MEDIUM / LOW:边界用例与非全函数

6.1 版本可读性门:toIntOrNull 而非"全是数字"(A-1,2026-09-08)

VersionConstraint.numbersOf 的结尾是 component.takeWhile { it.isDigit() }.toIntOrNull() ?: 0。刚修过的缺陷(Balm 26.2.0.7 被读成 <a href="https://link.gitcode.com/i/63bfeb663c738f26c93173020ff0e6d8" target="_blank">0, 2, 0, 7])通过第二扇门回归:readableVersion 承认任何"全数字"组件,但 toIntOrNull 对超过 Int.MAX_VALUE(10 位数字)的组件返回 null,?: 0 于是把该组件变成 0 而不是"不可读"。一个携带日期或 CI 计数器的版本——1.20260908120000、2026.9.8.120000——会像其最大组件是 0 一样参与比较,低于几乎任何边界。这正是当初制造 47 个裁决的缺陷形状。修复方向是"一个全数字但解析不出的组件不可读,于是 satisfies 接受、没有任何东西被判定在一个我们无法容纳的数字上"——在 [VersionConstraint.kt 的 readableVersion/readableComponent 中可以看到这套"prose 是常态而非边界"的完整论证。

6.2 LearnedModIds 的线程安全与空条目(M-5 / L-2,2026-09-09)

LearnedModIds.kt 的类文档声称"Thread-safe: the grinder shares one instance across its grind workers",GrindPool 也确实让 N 个 worker 共享一个实例。该批次把值类型从不可变 String 换成了 CopyOnWriteArrayList,由 computeIfAbsent 后的 addIfAbsent 变更——组合本身正确(computeIfAbsent 原子、addIfAbsent 同步),但值得 pin 住。另一个 LOW:restore 在过滤 refs 之前执行 computeIfAbsent,遗留文档里一个 id 对应的 JSON null、数字或空数组会留下空的 CopyOnWriteArrayList,snapshot() 把它序列化为 "id": [] 使文件不断累积毫无断言的条目。修复:先过滤、后认领条目。

6.3 大小写折叠与 Locale.ROOT(M2/M3,2026-09-20)

ServerPackUpdater.prune 的 keep 集用 lowercase() 折叠比较。审计初判"在大小写敏感的文件系统上是错的",但第二遍撤回了这个结论(见下节)。ServerPackUpdater.kt 现代码中的注释完整记录了论证,且四处 lowercase() 全部显式传入 Locale.ROOT——Kotlin 无参 lowercase() 使用默认 locale,在 tr/az 下 I 会折叠成无点 ı。

6.4 嵌入式 mongod 版本三处拼写(A-3,2026-09-23)

EmbeddedMongoAvailable.kt:64 声明 MONGOD_VERSION = "8.0.5" 却从未使用;探针从 Version.Main.V8_0 启动(flapdoodle 的 Main 指向任意 8.0.x);两个测试各自硬编码字符串 8.0.5。"决定是否跳过"与"决定运行什么"是两个值,中间还躺着一个看似把它们连起来的死常量。这正是仓库自己的教训——duplicated knowledge drifts toward whichever copy is easier to reach——修复为一个常量被两边引用,探针从同一字符串派生版本名。

七、审计的自我纠错:撤回、反转与"错误是有用的部分"

这套审计体系最独特的品质是坦然记录自己错了,且把纠错过程当作最有价值的产出。

7.1 M2 撤回:大小写比较必须两面论证(2026-09-20)

初判说 prune 的 keep 集大小写不敏感比较"在大小写敏感文件系统上是错的",并建议不折叠。撤回理由:在大小写不敏感的文件系统上(Windows、macOS 默认),Mods/Alpha.jar 与 mods/alpha.jar 是同一个文件,而 prune 在复制之后运行。不折叠时,复制刚写出的条目匹配不上旧 manifest 条目,会被判为陈旧并删除本次运行刚生成的文件。折叠的代价是 Linux 上偶尔残留陈旧文件;不折叠的代价是 Windows 上删除新生成的文件。欠修剪才是安全方向。文档的总结发人深省:"这个发现命名了一个真实的非对称性,然后提出了在破坏性方向上解决它的修复。一个改变删什么的建议必须在两个文件系统上都论证之后才能落笔,而不只是论证触发它的那一个。"

7.2 A5 撤回:Kotlin lowercase() 是 locale 安全的(2026-09-06)

初判声称 ClientsideEntryInjector 的 lowercase() 对 locale 敏感。实际:Kotlin 的 lowercase()(自 1.5 起)正是为了取代 locale 敏感的 toLowerCase() 而存在,编译为 toLowerCase(Locale.ROOT)。在土耳其语默认 locale 下实测:Java toLowerCase() → ıceberg-,Kotlin lowercase() → iceberg-。为它写的 guard 首跑即绿,这正是发现真相的方式;guard 被保留为防 lowercase(Locale.getDefault()) 或 Java 互操作回归的 pin。

7.3 B-3 反转:断言形状的 guard 会骗人(2026-09-11 迭代 2)

迭代 1 声称 retry-order 修复已落地,迭代 2 按其要求补行为级 guard,结果对"已修复"的代码变红——从而暴露迭代 1 的 M-4 是个假发现。文档的总结值得背诵:"A guard that asserts shape can be green and prove nothing; a guard that asserts the consequence can be red and prove the finding wrong. Both directions are worth having, and only the second one catches a bad diagnosis."

7.4 三实例:guard 像 pin 却什么都没断言

  • StorageSystemTest(2026-09-23 A-1):它守卫的修复让 fixture 自己不再复现条件——不消毒时 "sub/dir/pack.zip" 会让 transferTo 抛 NoSuchFileException,但修复把名字缩减为 "pack.zip" 后写入直接成功。断言通过是因为"没出问题",而不是因为"失败被包住了"。修复:让写入与文件名无关地真正失败(把存储根指向一个普通文件)。
  • Settings guard(2025-09-25):发布的默认值等于代码的兜底值时,值断言是盲的。
  • PackVariables anchor:lastOrNull 掩盖了缺失的 ^。

文档的结论:区分真 pin 与装饰性 guard 的唯一方法,是把它运行在一个故意破坏的实现上。2026-09-23 的记录补充道:"本轮有三个 guard 因为错误的原因通过,变异验证找到了全部三个——读取一个都没找到。这是本仓库日志中同一失败模式的第四例,唯一抓到过它的技术是破坏生产代码并观察。"

八、实测优于推理:两个测量实例

除前文的 protects() 测量与 fabric-api 嵌套测量外,2026-09-11 迭代 1 还有一个方法论级别的教训:每次 pin 都在其自身提交处重新运行——这暴露了一个不编译的 pin(详见 REFACTOR-AUDIT.md 的表格)。"full build green" 的声明可能因 Gradle 的 UP-TO-DATE 检查而失真:./gradlew build 让未改动的模块测试 UP-TO-DATE,跨模块 guard 只有在其所在模块输入变化时才真正运行(B4 案例:KDocAttachmentTest 住在 -api,而它失败的孤立 KDoc 块在插件模块)。结论:跨模块 guard 的有效性取决于它所在的模块,--rerun-tasks 或显式运行该模块套件才是真正在提问。

九、可复用的审计检查清单

从十二轮审计中沉淀出的、可迁移到任何 Kotlin/JVM 项目的检查项:

  1. 手工字段映射逐字段断言:复制 N 个字段的代码必须用 N 个不同哨兵值驱动,杜绝等值不可检测的交换。
  2. 顺序/阶梯/优先级必须有 pin:任何"第一优先、其次、再次"的链式偏好,都要有至少一个测试把相邻两臂分开,且对调两臂做变异验证。
  3. 枚举驱动的 guard 从 entries 派生:手写 listOf(...) 的断言会随枚举扩展悄悄失效。
  4. 纯决策直接单测:分类、归因、原因函数不要只通过集成路径间接覆盖。
  5. 全函数检查:first { }、firstOrNull 链、空集合上的 entries.first 都是非全函数地雷;不可达不等于无害。
  6. "guard 为什么通过"与"为什么失败"同等重要:fixture 不再复现条件时,guard 只是装饰。
  7. 变异验证必须可编译:先清 build/test-results,把"无结果"与"零红"区分开。
  8. 测试与实现分离的提交卫生:fix: 之前应有独立的红色 test:;测试与生产代码不要混在同一个提交里(L-2,2026-09-05)。
  9. 跨模块 guard 的时效性:A 模块的 guard 覆盖 B 模块的代码时,绿色 build 在 A 的输入变化前不说明任何问题。
  10. 文档声明要写进测试:KDoc 声称的排序、线程安全、"never empty"、安全属性,每一条都需要对应的断言,否则就是会误导后人的 prose(A3 的假注释、B1 的假接线、A5 的 locale 假说)。

十、规模演进与结论

文档中的套件数字本身就是测试深度实践的成果:clientside 从 369 → 438 → 515 → 554 → 566 → 568 → 523,grinder 从 495 → 501 → 503 → 512 → 514,plugin-grinder 从 44 → 69 → 73 → 90,api 从 405 → 407 → 412 → 413 → 421,app 稳定在 149。至 2026-09-20 第三遍结束时全仓 1,910 测试、0 失败(30 个跳过均为既有 skip)。

ANALYSIS-AUDIT.md 的最终价值不在于"这个仓库没有 bug",而在于它建立了一套可证明的防御体系:每个 guard 都经过变异验证证明有牙齿,每个"看起来像问题"的疑点要么被修复、要么被记录为"已验证干净"并禁止翻案,每一条撤回与反转都被当作教训写下来。对于想要在自己的项目中复刻这套实践的工程师,文档中反复出现的三句话就是方法论的全部:

  • "Ask why a guard passed, not only why it failed."——问 guard 为什么通过,而不只是为什么失败。
  • "Mutation is the only way guards have been shown to have teeth."——只有变异验证能证明 guard 有牙齿。
  • "Measure before optimising, and record the negative result."——优化前先测量,并记录负面结果。
登录后查看全文
ServerPackCreator