codometer-measure

运行 codometer 测量

Codometer 会遍历目录，解析所有能识别的内容，并报告统计结果——可以输出到控制台、生成 JSON 报告或 Markdown 文档，也可以将徽章内容插入现有文件。它会像任何分析器一样统计语言相关信息——文件、行、类、函数——还会统计仓库自身遵循的约定；后者通常更值得关注。

一次测量一个目录

Codometer 测量一个目录，不了解工作区、任务运行器或项目图。 指定一个项目后，它会测量该项目自身的源文件，以及其配置声明的输入——仅此而已，不会涉及其他内容，也不会涉及同级项目。没有 --directory：每次运行都会测量进程的工作目录，无法按次覆盖。

cd packages/widgets && codometer --config codometer.config.ts --check limits

不要假设它会接收项目名称、包名称或任何可由任务运行器解析的内容。如果工作区按项目运行它，迭代工作由运行器负责，而不是 codometer。--inputs [globs...] 会将单次运行限定为给定的 glob，只对这些内容运行 language 分析，不启用任何已配置的输入——甚至包括内置的 codebase 输入。

指定配置

必须指定 --config <path>。 Codometer 从不搜索配置文件，也没有默认配置：未提供该标志时会拒绝运行，并报错指出这一要求。指定的文件独立生效——不会合并任何其他文件的内容——相对路径会先相对于工作目录解析，再相对于仓库根目录解析。在此仓库中，工作区文件是 configuration/codometer.config.ts；项目自身的配置文件是 codometer.config.ts。配置文件始终作为普通对象读取——导出函数不受识别，并会回退为空配置。

通过文件发现机制，.gitignore 已生效——被忽略文件排除的构建目录或虚拟环境无需再次命名排除；并且不会调用 git 本身，因此无论目录是否受版本控制，测量结果都相同。

每个标志彼此独立

--output-json、--output-markdown、--check 和 --format 需要分别指定，互不启用：

调用方式	写入	过期时失败	超限时失败
codometer --config <path>	否	否	否
codometer --config <path> --check limits	否	否	是
codometer --config <path> --check reports	否	是	否
codometer --config <path> --check limits,reports	否	是	是
codometer --config <path> --output-json	是	否	否
codometer --config <path> --output-json --check limits	是	否	是，写入后

单独传入 不带参数值 的 --output-json/--output-markdown 时，会写入已解析配置中相应类型输出所声明的位置；如果配置未声明此类输出，就会在开始测量前拒绝执行——因为没有可写入的位置。带路径 传入时，此路径仅用于本次运行，无论配置是否声明了相应类型的输出：codometer --config <path> --output-json report.json 会写入该路径，不受 outputs 内容影响。

将 --output-* 标志与 --check reports 组合时会被拒绝，而不会执行：刚刚写入的内容不可能过期。既写入又执行检查的运行会在失败前生成所有已解析的输出，因此即使运行的退出代码表示失败，磁盘上的报告仍反映当前测量结果。

超限与过期是不同的问题，不会合并报告。严重级别为 warn 的超限会打印出来，但不影响退出代码；严重级别为 fail 的超限会以 1 退出，而且只有在指定 --check limits、要求执行检查时才会如此。若要了解如何处理这两种情况，请使用 codometer-triage 技能。

- run: npx @codometer/cli --config codometer.config.ts --check limits,reports

阅读报告

JSON 报告按目标分组列出指标。每个指标都包含其值、在目标中的路径、单位（"bytes" 或 null）、针对它声明的所有限制；对于 comment 选择器的指标，还包含找到每个超限区块的 instances：

{
  "failures": [],
  "targets": [
    {
      "empty": false,
      "files": 42,
      "name": "codebase",
      "metrics": [
        {
          "instances": null,
          "limits": [{ "breached": false, "label": null, "severity": "fail", "value": 500 }],
          "name": "codebase.typescript.interfaces",
          "path": "typescript.interfaces",
          "unit": null,
          "value": 118
        },
        {
          "instances": [{ "file": "src/main.ts", "line": 4, "measured": 214 }],
          "limits": [{ "breached": true, "label": null, "severity": "fail", "value": 0 }],
          "name": "codebase.custom.TypeScript Comment Budget",
          "path": "custom.TypeScript Comment Budget",
          "unit": null,
          "value": 1
        }
      ]
    }
  ]
}

无论限制是否满足，都会以相同方式写出，因此使用方可以呈现剩余空间，而不只是失败项。comment 选择器的 value 统计超出自身预算的区块数量，instances 则列出每个区块所在的文件和行号——仅统计数量的指标中，该字段为 null。failures 记录运行完全无法完成的事项——例如，带有限制的目标未匹配到任何文件，或某个限制绑定的指标没有测量结果——与超限或过时无关。

输出位置

运行时打印的内容和写入的内容分别指定。--format json 会打印报告，--format markdown 会打印渲染后的徽章；路径始终指向文件，而非控制台。如果未指定 --format，则使用解析后的配置中必需的 format 字段，不会根据其他标志推断。

有两个文件输出选项——--output-json [path] 和 --output-markdown [path]——二者互不隐含，也都不意味着要打印内容。

--output-markdown 会将内容写入一个可能已有其他内容的文件。内容块位于两个标记之间，默认标记为 /，也可由配置重命名；如果文件中已有这两个标记，就在它们之间替换内容；如果没有，就连同标记一起追加；如果文件不存在，则创建该文件。

每次运行时，codometer 都会排除所有将要写入的文件，不论使用了哪些标志——若将写入的报告计入测量，报告落盘的瞬间就会过时；而插入内容也会把刚写入的 markdown 指标计入测量。

一处看似 bug 的运行时细节

压缩后的大小取决于 Node 版本，因为不同版本捆绑的 zlib 不同。在一个 Node 运行时写出的报告，在另一个运行时检查时会被判定为过时，即使源代码完全没有变化。请使用仓库为其他操作指定的同一运行时执行 --check reports，并在认定报告过时属于真实回归之前，先查阅 codometer-triage 技能。