codometer-triage

处理 codometer 检查失败

一次 --check 运行会报告三种不同类型的问题，需要采取三种不同的应对方式。与其对“检查失败”作出反应，不如先看清发生了哪一种问题，这正是掌握此技能的大部分内容。

超限

某项指标超过了为其声明的限值。报告会列出指标、限值及其严重程度：

• warn 会打印超限信息，但不影响退出代码。运行本身不会失败；这只是提前提醒你某个数值正在朝值得关注的方向变化。
• fail 会以 1 退出，但只有运行时要求进行 --check limits 门禁检查才会如此——使用 codometer measure --config <path> 测量同一个超限情况时，不会报告问题，因为没有要求它进行门禁检查。

本能想到的修复方式——提高限值的 value——不可取。 这项限值旨在维护关于代码库形态的承诺；在同一次改动破坏承诺后放宽限值，会抹去这项检查原本要留下的证据，而下次超限时，代码库只会在已经更糟的基础上继续恶化。应减少实际测量的内容：

• 尺寸超限：缩减输入本身的输出——精简依赖、拆分包、删除死代码——而不是改动用于报告尺寸的数值。codometer-configure 技能介绍了如何声明输入并正确指向编译后的输出；这也是尺寸看起来大于生成它的代码实际大小的常见原因：输入测量的范围超过了应有的范围。
• 约定计数超限（某项内容过多或过少）：计数通常是准确的——应修复计数器监测的代码，而不是修改计数器的 value。
• 注释预算超限 是一种与其他自定义统计信息类似的指标，通过普通的 limits[] 条目针对其 custom.<label> 指标进行门禁检查；但它的 instances 会为每个超限代码块列出文件和行号，而不只是给出总数，因为测量对象是单个代码块，而不是整个代码库的总数。精简该代码块，或将详细内容移到有足够空间的文档中。在相信计数之前，先确认使用了哪种读取器来测量——对于 shell、TOML、SQL 和 HCL，行扫描器会把字符串字面量中的注释标记也识别为注释；而如果无法运行解释器，Python 注释就完全不会被测量。codometer-configure 技能完整说明了这两项注意事项。
• 不支持的语言，其注释预算根本不算超限——它们只是没有被测量。如果代码库新增了一种 codometer 能解析注释的语言，却没有人为其添加 comment 选择器，那么在声明预算之前，该语言的代码块都不会受预算限制；绝不能将这种情况诊断为工具漏报。

如果限值本身的数值确实不符合该指标今后应维持的标准——而不是因为这次改动才不符合——那就应作为一项独立的、有意为之的修改，并说明原因，绝不能为了让某次检查通过而顺带修改。

过时

--check reports 会将已提交的报告与最新测量结果进行比较，无论是否涉及任何限值，只要两者不一致就会失败。这可能由两种原因导致，其中只有一种是真正的回归：

• 代码确实发生了变化，而已提交的报告尚未重新测量。使用 --output-json/--output-markdown 重新运行以刷新报告。
• 运行时发生了变化。 压缩后的尺寸取决于 Node 版本——捆绑的 zlib 会因版本发布而不同——因此，在一个 Node 版本上生成的报告，在另一个版本上检查时会被视为过时，即便代码完全没有变化。在认定源码发生变化前，请先使用仓库为其他检查所固定的确切运行时进行检查。

即使 超限 和 过时 来自同一次运行，它们仍会作为不同的问题分别报告；不要将其中一种视为另一种的征兆。

一次彻底失败的运行

这与上述两种情况都不同：运行本身无法完成，相关问题会收集到报告的 failures 中，而不是计入任何指标。

• 限制条件未绑定到任何内容。 指标路径没有指向运行实际测量的内容——可能是拼写错误、指定了输入从未运行的分析，或在两个输入之间确实存在歧义。请在配置中修正路径；codometer-configure 技能会介绍指标路径的解析方式，以及为什么遇到歧义时会拒绝而不是猜测。
• 某个输入匹配不到任何文件，但却设置了限制。 对输入声明限制意味着其文件确实存在，因此匹配结果为空，说明 glob 已不再匹配，或者本应生成这些文件的构建从未运行——请先检查构建步骤，再修改配置。未设置限制且匹配不到任何文件的输入并不异常，也不会报告失败。
• 配置本身在进行任何测量之前就被拒绝。 缺少 format、存在两个类型相同的 outputs 条目、自定义统计项没有指定 patterns/symbols/comment 中的任何一项，或者某个 outputs 条目选择了顶层 custom 数组中从未声明的 custom 标签，都会在加载时导致运行失败，并指出原因。导出函数而非普通对象的配置，是同类问题中不那么明显的一种：现在已不再支持将配置作为函数的特殊用法，因此它无法被识别，会回退为空配置，随后因缺少 format 而失败，而不是指出真正的原因。请修正配置，而不是命令行。完全没有传入 --config 的运行会在进行任何测量之前被拒绝：请传入 --config <path> 并指定配置文件。

一次运行中的所有失败都会被汇总并一并报告，因此如果报告列出了三项，就应将其视为三个需要修复的问题，而不是一次不稳定的运行，重试即可。

使用 --output-json/--output-markdown 前须知

请记住，两个 --output-* 标志和 --check 彼此独立，它们之间没有隐含关联——codometer-measure 技能提供了完整的标志表。将 --output-* 标志与 --check reports 组合使用会被直接拒绝：同一次运行刚刚写入的报告不可能过期，因此这种组合属于配置错误，应予修正，而不是用来强制更新报告。

--inputs [globs...] 也独立于 --check——将 measure 运行范围缩小到指定的 glob，不会改变它是执行门禁检查还是写入内容。measure 没有 --directory：运行始终测量进程自身的工作目录。configuration 子命令是唯一仍提供 -d, --directory 的地方，用于列出某个目录的配置解析结果，而不是对其进行测量。