Back to Details

codometer-triage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Acting on a codometer failure

处理 codometer 失败

A 
--check
run reports three different kinds of finding, and they call for three different responses. Reading which one occurred, rather than reacting to "the check failed," is most of this skill.
一次 
--check
运行会报告三类不同的问题，它们需要三种不同的响应。关键在于先判断出现的是哪一类问题，而不是一味对“检查失败”作出反应——这正是本 skill 的核心。

A breach

超限

A metric went past a limit declared for it. The report names the metric, the limit's value, and its severity:
  • warn
     prints the breach and leaves the exit code alone. Nothing about the run fails; it is advance notice that a number is moving in a direction worth watching.
  • fail
     exits 
    1
    , and only when the run asked 
    --check limits
    for a gate at all — a bare 
    codometer measure
    measuring the same breach reports nothing wrong, because nothing asked it to gate.
The instinctive fix — raising the limit's 
value
— is not an option. The limit exists to keep a promise about the codebase's shape; loosening it on the same change that broke the promise erases the evidence the check existed to produce, and the next breach starts from a codebase that is already worse. Reduce what is actually being measured instead:
  • A size breach: shrink the input's own output — trim a dependency, split a bundle, delete dead code — rather than the number that reports it. The 
    codometer-configure
    skill covers declaring an input and pointing it at compiled output correctly, which is a common reason a size looks larger than the code that produced it: an input measuring more than it should.
  • A convention-count breach (too many of something, or too few): the count is usually accurate — the fix is in the code the counter is watching, not in the counter's 
    value
    .
  • A comment budget breach is a custom statistic like any other, gated by an ordinary 
    limits[]
    entry against its 
    custom.<label>
    metric — but its 
    instances
    name a file and a line for each breaching block rather than only a total, because the thing measured is one block rather than a repository-wide count. Condense that block, or move the detail into documentation that has room for it. Check which reader measured it before trusting the count — shell, TOML, SQL, and HCL use a line scanner that reads a comment marker inside a string literal as a comment, and Python's comments go unmeasured entirely when the interpreter cannot be run. The 
    codometer-configure
    skill has both caveats in full.
  • A comment budget a language is not covered by is not a breach at all — it is simply not measured. If a repository added a language codometer can parse comments in but nobody added a 
    comment
    selector for it, that language's blocks run with no budget until one is declared; this is never something to diagnose as a false negative in the tool.
If the limit's number was simply wrong for what this metric should hold going forward — not because of this change, but as a standing decision — that is a deliberate edit to make and explain on its own, never a side effect of getting one check to pass.
某项指标超过了为其声明的限制。报告会指出该指标、限制值及其严重级别：
  • warn
     会打印超限信息，但不会改变退出码。此次运行本身并未失败；它只是提前提示某个数字正朝值得关注的趋势变化。
  • fail
     会以 
    1
    退出，而且仅当运行通过 
    --check limits
    明确要求执行门禁时才会如此——单独执行 
    codometer measure
    时，即使测得同样的超限也不会报告任何问题，因为没有要求它执行门禁。
本能的修复方式——提高限制的 
value
——并不可取。 限制的存在是为了对代码库的结构作出承诺；在破坏承诺的同一次变更中放宽限制，会抹掉检查本来要揭示的证据，而下一次超限发生时，代码库已经从更糟糕的状态继续演变。应当减少实际被测量的内容：
  • 大小超限：缩减该输入自身产生的输出，例如缩减依赖、拆分 bundle 或删除死代码，而不是修改用于报告该结果的数字。
    codometer-configure
    skill 介绍了如何正确声明输入并将其指向编译后的输出；这是尺寸看起来大于生成它的代码量的常见原因：输入实际测得的内容超出了预期。
  • 约定项数量超限（某类内容过多或过少）：计数通常是正确的——需要修复的是计数器所监控的代码，而不是计数器的 
    value
    。
  • 注释预算超限是一种与其他指标一样的自定义统计量，通过针对 
    custom.<label>
    指标的普通 
    limits[]
    条目进行门禁控制；但它的 
    instances
    会为每个超限块指出文件和行号，而不仅仅给出总数，因为被测量的对象是单个块，而不是整个仓库中的数量。应当压缩该代码块，或将细节移入有足够空间的文档中。在信任计数之前，先确认是哪种解析器测量的——shell、TOML、SQL 和 HCL 使用行扫描器，会将字符串字面量中的注释标记识别为注释；而当 Python 解释器无法运行时，其注释完全不会被测量。
    codometer-configure
    skill 完整介绍了这些注意事项。
  • 某种语言不受注释预算覆盖时，根本不存在超限——它只是未被测量。如果仓库新增了一种 codometer 能够解析其注释的语言，但没有人为它添加 
    comment
    选择器，那么在声明预算之前，该语言的代码块都不会受到任何预算限制；这绝不应被诊断为工具的 false negative。
如果限制数值只是与该指标今后应代表的含义不符——并非由本次变更造成，而是一项长期决策——则应当单独、有意识地修改并说明，绝不能把它当作让某次检查通过的副作用。

Staleness

报告过期

--check reports
compares a committed report against a fresh measurement and fails when they disagree, whether or not any limit is involved. Two causes produce this, and only one of them is a real regression:
  • The code actually changed and the committed report was never re-measured. Re-run with 
    --output-json
    /
    --output-markdown
    to refresh it.
  • The runtime changed. Compressed sizes are Node-version dependent — the bundled zlib differs release to release — so a report written on one Node version and checked on another reads as stale with zero code changes involved. Check on the exact runtime the repository pins for everything else before concluding the source moved.
A breach and staleness are reported as separate findings even when they come from the same run; do not read one as a symptom of the other.
--check reports
会将已提交的报告与最新测量结果进行比较，并在两者不一致时失败，无论其中是否涉及限制。造成这种情况的原因有两种，但只有一种是真正的回归：
  • 代码确实发生了变化，但已提交的报告从未重新测量。使用 
    --output-json
    /
    --output-markdown
    重新运行以刷新报告。
  • 运行环境发生了变化。 压缩后的大小取决于 Node 版本——不同发行版本内置的 zlib 有所差异——因此，在一个 Node 版本上生成并在另一个版本上检查的报告，即使代码没有任何变化，也会显示为过期。在断定源代码发生变化之前，应使用仓库为其他所有环节固定的准确运行时版本进行检查。
即使超限和报告过期来自同一次运行，它们也会作为独立的问题分别报告；不要将其中一个问题视为另一个问题的症状。

A run that failed outright

运行彻底失败

Distinct from both of the above: the run itself could not finish, collected into 
failures
in the report rather than folded into any metric.
  • A limit bound to nothing. The metric path names no measurement the run actually took — misspelled, or naming an analysis its input never ran, or genuinely ambiguous between two inputs. Fix the path in the configuration; the 
    codometer-configure
    skill covers how a metric path resolves and why an ambiguous one is refused rather than guessed.
  • An input matched no files while carrying a limit. Declaring a limit against an input asserts its files exist, so an empty match means the glob stopped matching or the build that should have produced those files never ran — check the build step before touching the configuration. An input nobody limited that matches nothing is unremarkable and reports no failure.
  • The configuration itself was rejected before anything measured. A missing 
    format
    , two 
    outputs
    entries of the same type, a custom statistic naming none of 
    patterns
    /
    symbols
    /
    comment
    , or an 
    outputs
    entry selecting a 
    custom
    label the top-level 
    custom
    array never declared each fail the run at load time with the reason named. A configuration exporting a function instead of a plain object is a quieter version of the same problem: there is no config-as-function escape hatch any more, so it is not recognized and falls back to an empty configuration — which then fails on the missing 
    format
    rather than on anything naming the real cause. Fix the configuration rather than the command line.
Every failure in one run is collected and reported together, so treat a report naming three as three things to fix, not one flaky run to retry.
这与上述两种情况不同：运行本身无法完成，错误会被收集到报告中的 
failures
中，而不会归入任何指标。
  • 限制未绑定到任何对象。 指标路径没有指向运行实际测量的任何内容——可能拼写错误、指向了输入从未执行的分析，或在两个输入之间确实存在歧义。应修复配置中的路径；
    codometer-configure
    skill 介绍了指标路径如何解析，以及为什么存在歧义的路径会被拒绝而不是被猜测。
  • 输入携带限制，却未匹配任何文件。 针对输入声明限制，就等于断言其文件存在，因此空匹配意味着 glob 已失效，或者本应生成这些文件的构建步骤从未运行——应先检查构建步骤，而不是修改配置。没有任何限制的输入如果未匹配到文件，则属于正常情况，不会报告失败。
  • 配置在任何测量开始前就被拒绝。 缺少 
    format
    、存在两个同类型的 
    outputs
    条目、自定义统计量没有指定 
    patterns
    /
    symbols
    /
    comment
    中的任何一种，或者 
    outputs
    条目选择了一个顶层 
    custom
    数组从未声明的 
    custom
    标签——这些问题都会在加载时使运行失败，并指出相应原因。配置导出函数而不是普通对象，是同一问题的另一种更隐蔽的表现：现在已不再提供以函数形式导出配置的逃生方式，因此配置不会被识别，而是回退为空配置——随后它会因缺少 
    format
    而失败，而不会指出真正的原因。应修复配置，而不是修改命令行。
一次运行中的所有失败都会被统一收集并报告，因此，如果报告中列出了三个问题，就应将其视为三个需要修复的问题，而不是一次不稳定的运行，值得直接重试。

Before reaching for 
--output-json
/
--output-markdown

在使用 
--output-json
/
--output-markdown
之前

Remember that the two 
--output-*
flags and 
--check
are independent, with no inferred relationship between them — the 
codometer-measure
skill has the full flag table. Combining an 
--output-*
flag with 
--check reports
is refused outright: nothing can be stale in a report the same run just wrote, so that combination is a configuration mistake to fix, not a way to force a report current.
--inputs [globs...]
is independent of 
--check
too — narrowing a 
measure
run to exactly the given globs does not change whether it gates or writes. There is no 
--directory
on 
measure
: a run always measures the process's own working directory. The 
configuration
subcommand is the one place 
-d, --directory
still exists, for listing what a directory's configuration resolves to rather than for measuring it.
请记住，两个 
--output-*
标志与 
--check
相互独立，彼此之间没有推断关系——
codometer-measure
skill 提供了完整的标志表。将 
--output-*
标志与 
--check reports
组合会直接被拒绝：同一次运行刚写出的报告不可能已经过期，因此这种组合是需要修复的配置错误，而不是强制更新报告的方式。
--inputs [globs...]
与 
--check
同样相互独立——将一次 
measure
运行限定为给定的 glob，并不会改变它是执行门禁还是写出报告。
measure
没有 
--directory
：运行始终测量进程当前的工作目录。
configuration
子命令是唯一仍保留 
-d, --directory
的地方，它用于列出一个目录的配置最终解析为什么，而不是用于执行测量。