@zxyycom/vibe-check 0.0.1 → 0.0.3

package/docs/checks/file-metrics.md

@@ -1,30 +1,61 @@
 # `fileMetrics`
 
-本页完整说明 package consumer 如何构造、配置和读取 `fileMetrics`。package 总入口见
-[README 的随包 Check 概览](../../README.md#随包提供的-check)；普通 Check 的 preflight、Run 与结果读取机制见
-[深入 API 机制](../api-mechanics.md)。
-
 ## 用途
 
-`fileMetrics(options?)` 返回一个普通 `file-metrics` Check。该 Check 使用 SCC 测量各区域所选文件的代码行数，
-将超过区域策略的文件发布为 supplemental Records，并分别报告 finding 总数与 blocking finding 数量。可选的声明式
-waiver 在完整 finding 集合形成后对账；它不会把路径排除在 SCC 输入之外。
+`fileMetrics(options?)` 构造 `file-metrics` Check，用 SCC 测量文件代码行数，报告超限 Records 及总数、blocking 数量。
+waiver 在完整 Finding 集合上对账，不从 SCC 输入排除路径。
+
+运行环境须提供默认 `scc` command，或配置已授权的 `scanner.executable`；两者均须支持精确 SCC 4.0.0 version output
+与 CSV contract。安装与协议见[定制 SCC executable](#定制-scc-executable)。
+
+## 构造器项目声明
+
+`fileMetrics` 有三类 overload：`fileMetrics(options?: FileMetricsOptions<"file-metrics">)` 保留默认 literal；
+`fileMetrics<Id>(options: FileMetricsOptions<Id> & { checkId: Id })` 保留 custom literal；已宽化为
+`FileMetricsOptions` 的变量返回 `string` identity。默认 `checkId` 是 `file-metrics`，默认 `displayName` 是 `File metrics`；`codeAreas`、`findingPolicy`、
+`findingWaivers` 与 `scanner` 仍是本 Check 的领域 options。
+
+例如，可在同一 Definition 中用独立 identity 选择 source 指标，并保留默认展示名：
+
+```ts
+const sourceMetrics = fileMetrics({
+  checkId: "source-file-metrics",
+  enabledByFlags: { when: "source-changed" },
+  codeAreas: { source: { files: { include: ["src/**/*.ts"] } } }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `sourceMetrics.options` 或执行时的
+`context.options`；完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
 
-无参调用使用完整默认策略：
+示例保留终端进度，不写 machine files。
 
 ```ts
-import { fileMetrics } from "@zxyycom/vibe-check";
+import { defineConfig, fileMetrics, run } from "@zxyycom/vibe-check";
 
-const check = fileMetrics();
+const check = fileMetrics({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`File metrics did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
 ```
 
-执行这个 Check 时，project runtime 需要让默认 `scc` command 可用，或在 `scanner.executable` 中选择项目已授权且
-兼容 SCC 3.7.0 version output 与 CSV contract 的 executable。
+示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
-顶层 `codeAreas`、`findingPolicy`、`findingWaivers` 与 `scanner` 都可省略。每个 `codeAreas[areaId]` 同时拥有文件选择和代码行
-策略，因此不同区域可以选择不同文件并使用不同上限。无参调用物化以下完整、冻结的 Check options：
+顶层 options 都可省略；每个 area 独立选择文件与代码行策略。无参调用物化以下完整、冻结的 options：
 
 ```ts
 {
@@ -46,20 +77,18 @@ const check = fileMetrics();
 }
 ```
 
-这里的 `defaultProjectFileSelection` 是从 package root 公开的深冻结完整基线；constructor 会把同值 files branch 物化到
-自己的 resolved options，调用方无需复制该对象；完整默认 glob 可直接从该 public value 读取。
+`defaultProjectFileSelection` 是 package root 公开的深冻结默认选择；constructor 会物化同值 files branch，无须手工复制。
 
 ### 字段规则
 
 - 省略整个 `codeAreas` 时，constructor 建立默认 `project` 区域。显式 `codeAreas` 必须至少包含一个
   非空 area ID。
-- 每个显式区域必须提供 `files`。`source` 只能是 `"filesystem" | "git-worktree"`，默认 `filesystem`；filesystem
-  不解释 `.gitignore`，git-worktree 使用已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。来源不可用时 Check
-  结算为 `unavailable`，不会切换到另一来源。
-- `include` 与 `exclude` 都按 project-root-relative slash path 的 glob 匹配，exclude 优先。省略时使用公开的
-  `defaultProjectFileSelection`；显式数组是完整替换值，`include: []` 不选择路径，`exclude: []` 不排除路径。
+- 每个显式区域必须提供 `files`。共同 `{ source, include, exclude }` grammar、source failure 和数组替换见
+  [共享的 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)；本 Check 的 branch fields 省略时使用公开的
+  `defaultProjectFileSelection`。
 - 顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，默认 `non-blocking`；area 可覆盖，省略时继承顶层值。
-- `findingWaivers` 省略时为 `[]`。每项必须是 `{ identity: { metric: "code-lines", path }, reason }`；`path` 必须已经是
+- `findingWaivers` 省略时为 `[]`，并采用[共同 waiver authoring 与 audit](../guides/finding-waivers.md#identity-与-audit)。每项必须是
+  `{ identity: { metric: "code-lines", path }, reason }`；`path` 必须已经是
   normalized project-root-relative slash path：非空、不以 `/` 开头、不含 `\\`、Windows drive prefix、空 segment、`.` 或 `..`。
   `reason` 必须非空，同一 `{ metric, path }` 不得重复。它不接受 callback 或 glob：metric 和 path 是该 Check 承诺的稳定
   identity，实际行数与上限仍会随策略变化。
@@ -98,8 +127,7 @@ const sourceAndTests = fileMetrics({
 });
 ```
 
-本例只覆盖各区域显式给出的字段；省略的文件字段、finding policy 和代码行字段继续使用 package 默认值。`tests` area
-通过公开的深冻结 `defaultProjectFileSelection` 保留 common exclusions，再追加项目的 fixture 规则。
+省略字段沿用默认值；`tests` 保留默认排除项并追加 fixture 规则。
 
 ### 单个区域的有效上限
 
@@ -117,8 +145,8 @@ SCC CSV 的 `Complexity` 字段是 file-metrics 使用的 decision-token measure
 
 1. Check 先按文件 `source` 分组；每种不同来源只枚举一次候选文件，再为每个 area 应用自己的 `include` / `exclude`，
    并保存 path 到全部实际 area IDs 的 membership。
-2. Check 对全部路径稳定排序、去重，只把这个 exact-path union 交给 SCC 一次。
-3. 每条 SCC measurement 必须声明属于该 union 的 source path；任一越界 measurement 会拒绝整批结果。
+2. Check 对全部路径稳定排序、去重，并把这个 union 作为一次 logical SCC scan。adapter 按私有的 Windows UTF-16 argv 上界传输：安全的小输入仍由一个 process 承载；较大输入按原顺序分成一个或多个非空 exact-path batches。分批不会让 SCC 重新发现路径，也不形成新的 options、Records 或公开结果。
+3. 每个 process batch 都必须先完成 CSV 与该 batch 的 exact-scope 验收；全部 batch 成功后 adapter 才拒绝重复 measurement path、稳定排序并交回统一结果。任一 process、CSV、scope 或汇合失败都会拒绝整个 logical scan，不发布已完成 batch 的部分 measurement。
 4. 对属于多个区域的文件，Check 分别计算各区域的有效代码行上限，并使用其中最小的严格上限：
 
    ```text
@@ -141,11 +169,12 @@ const customFileMetrics = fileMetrics({
 custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只选择 executable；owning adapter 固定执行以下协议：
 
 - availability probe：`--version`
-- measurement：`--by-file --format csv <approved exact paths...>`
-- process timeout：由 adapter 固定，不属于项目策略
+- measurement：每个私有 batch 都执行 `--no-config --by-file --format csv <approved exact paths...>`；全部 batch 仍是一份 logical measurement
+- process timeout 与 stdout/stderr output budget：由 adapter 固定并覆盖完整 logical scan，不属于项目策略
 
 需要 prefix arguments 的通用 runtime（例如 `node path/to/tool.js`）不是受支持的直接 command；项目应提供一个已授权的
-专用 wrapper executable。当前 adapter 只接受 SCC `3.7.0` 的 version output 与对应 CSV header contract。
+专用 wrapper executable。当前 adapter 只接受 SCC `4.0.0` 的 version output 与对应 CSV header contract。
+`--no-config` 隔离 `SCC_CONFIG_PATH` 与项目中的 ambient SCC config；adapter 不读取 consumer SCC 参数或 config。
 
 ### 安装兼容 SCC
 
@@ -153,12 +182,12 @@ custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只
 
 ```toml
 [tools]
-go = "1.25"
-"go:github.com/boyter/scc/v3" = { version = "v3.7.0", depends = ["go"] }
+go = "1.26.4"
+"go:github.com/boyter/scc/v4" = { version = "v4.0.0", depends = ["go"] }
 ```
 
 运行 `mise install` 后，用 `scc --version` 确认当前 project runtime 能解析到该命令。若项目使用其它安装方式，只要
-`scanner.executable` 指向已授权、直接接受上述协议并产生 SCC 3.7.0-compatible output 的 executable 即可。
+`scanner.executable` 指向已授权、直接接受上述协议并产生精确 SCC 4.0.0 version output 和受支持 CSV header 的 executable 即可。
 
 ## 效果与结果
 
@@ -183,14 +212,15 @@ non-blocking 或 waived finding Records。
 
 精确命中一项 finding 的 waiver 会保留原 finding Record，并写入 `waiver.reason`、将 `blocking` 设为 `false`，同时附加
 `finding-waived` info message。未命中或命中多项的 waiver 不会隐藏 finding；各自产生一条 `kind: "finding-waiver-audit"`
-Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` status，并附 warning。这样 stale 或过宽配置可见，
-而不是悄悄失效或覆盖多个 finding。audit Record ID 使用 `/finding-waiver-audit/<identity.path>`，该 leading-slash domain
+Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` status，并附 warning。
+audit Record ID 使用 `/finding-waiver-audit/<identity.path>`，该 leading-slash domain
 与正常 finding 的 normalized relative path ID 不相交。
 
-`failed` 的 `blocking-findings` message 与携带 non-blocking Records 的 `passed` 的 `non-blocking-findings` message 都会引导
-调用方检查本 Check 的 Records。由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；没有 finding
-且没有 waiver audit 时，`passed` 与 `not-applicable` 不合成人为提示。若已配置 waiver，即使 exact-path union 为空，Check
-仍会对已知空 finding 集合产生 `unused` audit Record 和 warning，同时保持 `not-applicable / no-eligible-input` outcome。
+`fileMetrics` 的 detail messages 按稳定 path 顺序，包含项目相对 path、code lines、effective limit 和 areas；完整 finding 集合从
+本 Check 的 Records 读取。通用的 terminal Finding 呈现与 Run progress 预览边界见
+[呈现 Check Finding](../guides/presenting-findings.md)。
+由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；没有 finding 且没有 waiver audit 时，`passed` 与
+`not-applicable` 不合成人为提示。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseFileMetricsData(value)` 验证 final data。两者返回
 `FileMetricsFinalData`，Record 与不可用原因可分别用 `FileMetricsRecordData` 和
@@ -215,14 +245,6 @@ Record，带 identity、reason、matchCount 和 `"unused" | "overmatched"` statu
 execution 只启动本机已授权的 SCC executable，输入仅包含各区域批准的 exact paths 去重并集。该 Check 不发起网络请求，
 也不把 raw SCC stdout/stderr 直接发布为稳定 Check 或 Record data。
 
-## 最小用法
-
-```ts
-import { defineConfig, fileMetrics, run } from "@zxyycom/vibe-check";
-
-const result = await run(defineConfig({ checks: [fileMetrics()] }));
-```
-
 ## 适用边界
 
 该 Check 只评估文件级代码行策略。函数级 NLOC、cyclomatic complexity 与 parameter count 由

package/docs/checks/function-metrics.md

@@ -1,61 +1,87 @@
 # `functionMetrics`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-`functionMetrics(options?)` 构造一个普通 Check。它使用 Lizard 测量函数 NLOC、cyclomatic complexity 与参数数量，
-把超过 area limits 的结果保存为 supplemental Records，并让全局默认与 area override 共同决定 finding 是否阻断
-Check。阻断只改变最终 outcome；一次 invocation 仍扫描完整 exact scope 并保留后续 findings。
+`functionMetrics` 是普通 Check，评估每个函数的 NLOC、cyclomatic complexity（CCN）、最大 nesting depth 与 parameter count。
+它使用随包 TypeScript analyzer 分析所选的受支持源文件。
+
+## 构造器项目声明
+
+`functionMetrics` 有三类 overload：`functionMetrics(options?: FunctionMetricsOptions<"function-metrics">)`
+保留默认 literal；`functionMetrics<Id>(options: FunctionMetricsOptions<Id> & { checkId: Id })` 保留 custom literal；
+已宽化为 `FunctionMetricsOptions` 的变量返回 `string` identity。默认 `checkId` 是 `function-metrics`，默认 `displayName` 是 `Function metrics`；`codeAreas`、
+`findingPolicy` 与 `findingWaivers` 仍是本 Check 的领域 options。
+
+例如，按关系等待生成步骤后执行一个独立的函数指标实例：
 
 ```ts
-import { functionMetrics } from "@zxyycom/vibe-check";
+const generatedFunctionMetrics = functionMetrics({
+  checkId: "generated-function-metrics",
+  dependsOn: ["generate-sources"],
+  codeAreas: { generated: { files: { include: ["generated/**/*.ts"] } } }
+});
+```
+
+返回值仍是原生 typed Check。项目声明字段不会进入 `.options` 或执行时的 `context.options`；
+完整字段集合、投影和校验边界见[API 机制](../api-mechanics.md#随包-check-的构造器项目声明)。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, functionMetrics, run } from "@zxyycom/vibe-check";
 
-const check = functionMetrics();
+const check = functionMetrics({ findingPolicy: "blocking" });
+const result = await run(defineConfig({
+  checks: [check],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`Function metrics did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
 ```
 
-执行这个 Check 时，project runtime 需要让默认 `lizard` command 可用，或在 `scanner.executable` 中选择项目已授权且
-兼容 Lizard 1.23 version output 与 CSV contract 的 executable。
+示例显式使用 `findingPolicy: "blocking"`，让未豁免的普通 Finding 导致失败；默认 `non-blocking` 只警告，不因 Finding 退出非零。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。多个有效 Check 的调用级结论可读取默认严格 `aggregate`；需要不同领域解释时，提供同步 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation) 函数。`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
-顶层 `findingPolicy`、`codeAreas` 与 `scanner` 都可省略；显式 `codeAreas[areaId]` 只要求提供 `files` branch。
-`functionMetrics()` 按下表物化完整、冻结的 resolved options，调用方无需复制默认数组：
+`FunctionMetricsOptions` 接受 `codeAreas`、`findingPolicy` 与 `findingWaivers`；未知字段使 constructor 同步抛出 `TypeError`。
+
+无参调用建立冻结的 `project` area：`files` 使用 `defaultProjectFileSelection` 的 source/exclude，include 由内置 analyzer
+支持的大小写不敏感 suffix 生成；finding policy 为 `non-blocking`，无 waiver。
 
-| Resolved field | 无参默认值 |
+| `limits` 字段 | 默认值 |
 | --- | --- |
-| `codeAreas.project.files.source` | `"filesystem"` |
-| `codeAreas.project.files.include` | 从同一 Check-local Lizard 1.23.0 extension registry 生成；每个官方支持 extension 对应一个大小写不敏感 glob |
-| `codeAreas.project.files.exclude` | detached copy of `defaultProjectFileSelection.exclude` |
-| `codeAreas.project.findingPolicy` | `"non-blocking"` |
-| `codeAreas.project.limits.codeLines` | `{ maximum: 60, lowComplexityAllowance: { maximum: 180, cyclomaticComplexityBelow: 6 } }` |
-| `codeAreas.project.limits.cyclomaticComplexity` | `{ maximum: 12 }` |
-| `codeAreas.project.limits.parameters` | `{ maximum: 6 }` |
-| `scanner` | `{ executable: "lizard" }` |
-
-需要核对当前完整 glob array 时，读取 `functionMetrics().options.codeAreas.project.files.include`；它与 runtime eligibility
-predicate 来自同一 extension registry。source/exclude 沿用公开深冻结基线，include 精准匹配 Lizard 能力。
-
-顶层 `findingPolicy` 只为各 area 提供默认值；每个 resolved area 保存自己的有效 `findingPolicy`。所有 maximum 都是
-包含等于值的上限：measurement 必须严格大于 limit 才产生 finding。complexity 小于
-`cyclomaticComplexityBelow` 时，function NLOC 使用 allowance maximum；所有 limit 都必须是正安全整数，allowance
-maximum 不得小于普通 code-line maximum。
-
-constructor 按字段补默认值。`source` 只能是 `"filesystem" | "git-worktree"`，默认 `filesystem`；filesystem 不解释
-`.gitignore`，git-worktree 使用已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。来源不可用时 Check 结算为
-`unavailable`，不会切换到另一来源。`include` 与 `exclude` 都按 project-root-relative slash path 的 glob 匹配，exclude
-优先。省略 source/exclude 时沿用公开 baseline，省略 include 时使用上述 Lizard-specific globs；显式数组完整替换对应
-默认值，`include: []` 不选择路径，`exclude: []` 不排除路径。显式组合完整 `defaultProjectFileSelection` 会明确选择
-`**/*`，不受支持的路径因而形成 input-rejection Records。nested limit 字段和 area `findingPolicy` 仍可分别省略并继承
-各自默认值。
-
-### 区域与阻断政策
-
-顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，省略时为 `"non-blocking"`。显式 `codeAreas` 必须非空，
-每个非空 area ID 必须声明 `files: {}`；file fields、limits 和 area `findingPolicy` 都可省略并由 constructor 补齐。
+| `codeLines.maximum` | `60` |
+| `codeLines.lowComplexityAllowance` | `{ cyclomaticComplexityBelow: 6, maximum: 180 }`，CCN 严格低于阈值时使用 |
+| `cyclomaticComplexity.maximum` | `12` |
+| `nestingDepth.maximum` | `7` |
+| `parameters.maximum` | `6` |
+
+嵌套字段可分别省略；所有 limit 值必须是正安全整数，allowance maximum 不得小于普通 NLOC maximum。
+指标严格超过有效上限才形成 Finding。nesting depth 计算控制结构、ternary `?`、每个 condition 的首个 `&&` 或 `||`；
+后续 logical operator 和 `else if` 不额外增深，因此不是纯大括号深度。
+
+每次 analysis 还受独立的输入资源上限约束：单个 source file 最大 `8 MiB`，本次 invocation 的 accepted
+source aggregate 最大 `64 MiB`。这两个上限不改变上述 metric limits；超限结算为
+`unavailable / resource-limit-exceeded`，不会发布 partial analysis。
+
+### 区域与 finding policy
+
+显式 area map 非空，每个非空 ID 必须声明 `files`；其 grammar、source failure 与数组替换见
+[共享的 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。area policy 省略时继承顶层值。
+路径按 source/include/exclude 收集后稳定去重，不重复分析或发布同一 metric Finding；重叠区域取最严格有效 limit，
+任一 matching area 为 `blocking` 时 Finding 就是 blocking。
 
 ```ts
-import { defaultProjectFileSelection, functionMetrics } from "@zxyycom/vibe-check";
+import { functionMetrics } from "@zxyycom/vibe-check";
 
 const metrics = functionMetrics({
   findingPolicy: "non-blocking",
@@ -65,158 +91,88 @@ const metrics = functionMetrics({
       findingPolicy: "blocking",
       limits: {
         cyclomaticComplexity: { maximum: 10 },
+        nestingDepth: { maximum: 6 },
         parameters: { maximum: 5 }
       }
-    },
-    tooling: {
-      files: {
-        ...defaultProjectFileSelection,
-        include: ["scripts/**/*.ts"],
-        exclude: [...defaultProjectFileSelection.exclude, "scripts/**/*.test.ts"]
-      }
     }
   }
 });
 ```
 
-本例中 source finding 会阻断，tooling finding 只形成 evidence。Check 不会在首个 blocking finding 后停止；它仍处理
-其它函数与 area，然后以完整计数结算。
-
-同一路径匹配多个 area 时，area authoring order 不参与结算：
-
-1. Record 的 `codeAreas` 保存该路径匹配的全部 area IDs，并按文本稳定排序。
-2. 每项 metric 分别计算所有 matching areas 的适用 maximum，并以其中最小值作为 effective limit。
-3. 任一 matching area 的 effective `findingPolicy` 为 `"blocking"` 时，该路径上的 finding 就是 blocking；这一判断不取决于
-   哪个 area 提供了最小 limit。
-
-## 定制 Lizard executable
+### 精确豁免一个函数指标
 
-public scanner policy 只选择直接接受 Lizard arguments 的 executable：
+`findingWaivers` 只匹配 normal metric findings，不匹配 input rejection。共同 authoring、matching 与 audit 见
+[对账 Finding waiver](../guides/finding-waivers.md)；本 Check 的 identity 是 `functionName`、`metric`、`path` 与
+`startLine`，其中 path 是 normalized project-root-relative slash path，`startLine` 是正安全整数。恰好匹配的 waiver
+保留原 finding Record、附上 reason 并不再 blocking；本 Check 仍为未匹配或过宽 authoring 发布 audit，且不应用 waiver。
 
 ```ts
 const metrics = functionMetrics({
-  scanner: { executable: "/opt/tools/lizard" }
+  findingWaivers: [
+    {
+      identity: {
+        functionName: "legacyParser",
+        metric: "cyclomatic-complexity",
+        path: "src/legacy/parser.ts",
+        startLine: 24
+      },
+      reason: "在重构窗口结束前保留该函数。"
+    }
+  ]
 });
 ```
 
-owning adapter 固定执行 `--version` probe，并以 approved exact paths 和 `--csv` 扫描。显式 executable 表示项目授权执行
-该命令；需要 wrapper 时由项目提供直接接受这套协议的 executable wrapper。不兼容命令会 fail closed 为 unavailable，
-而不会产生成功空结果。
-
-### 安装兼容 Lizard
-
-项目可以用自己的工具管理方式提供 `lizard`。本仓库验证的项目拥有安装方式是在 `mise.toml` 固定 uv 与 Lizard：
-
-```toml
-[tools]
-uv = "0.11.28"
-"pipx:lizard" = { version = "1.23.0", depends = ["uv"] }
-```
-
-运行 `mise install` 后，用 `lizard --version` 确认当前 project runtime 能解析到该命令。若项目使用其它安装方式，只要
-`scanner.executable` 指向已授权、直接接受上述协议并产生 Lizard 1.23-compatible output 的 executable 即可。
-
 ## 工作原理
 
-1. constructor 关闭 input shape，补齐 files、limits、finding policy 与 scanner defaults，再冻结 resolved options。
-2. execution 按文件来源分组，每种不同来源只枚举一次候选文件，再按各 area 的 `include` / `exclude` 形成完整 selected
-   paths，并以 Lizard extension registry 分成 accepted/rejected。每个 rejected path 只产生一条 Record，并保留全部 matching
-   area IDs；accepted paths 形成稳定去重的 exact-input 并集。
-3. accepted 并集非空时，Lizard adapter 对它执行一次 measurement；parser output 必须完整，且所有 source paths 必须属于
-   本次 exact set，否则整批结果结算为 unavailable，不发布 partial Records。
-4. 可信 measurements 恢复全部 matching areas，按上一节的 overlap 规则计算 effective limit 与 blocking，再完整形成 Records
-   和 final counts，不因首个 finding 短路。
+Check 用内置 reader registry 将 selected paths 分为 accepted/rejected；suffix 大小写不敏感。
+Markdown、JSON、YAML、无扩展名等不支持路径不进入 analyzer，每项先发布 non-blocking input-rejected Record。
+accepted paths 经有界读取后整批分析，只使用本次 exact inputs，不重新发现文件；取消会停止分析。
+空 selection、全 rejected 与分析失败的区别见[不可用原因](#not-applicable-与-unavailable)。
 
 ## 效果与结果
 
-每个超过 effective limit 的 metric 产生一个 metric Record，data 包含：
+正常 final data 恰为 `{ findingCount, blockingFindingCount }`：前者包括全部 metric Finding 与 input rejection，
+不含 waiver audit；后者只计仍 actionable 的 blocking Finding。后者大于零为 `failed`，否则为 `passed`。
 
-```ts
-{
-  blocking: boolean,
-  codeAreas: readonly string[],
-  functionName: string,
-  limit: number,
-  metric: "cyclomatic-complexity" | "function-code-density" | "parameter-count",
-  path: string,
-  startLine: number,
-  value: number
-}
-```
+metric Record 保留 `blocking`、`functionName`、`metric`、`value`、`limit`、`path`、`startLine` 与全部 matching `codeAreas`。
+metric 是 `function-code-density`、`cyclomatic-complexity`、`nesting-depth` 或 `parameter-count`。
+只有 CCN Record 另带完整 source-order `complexityContributors: Array<{ token, line }>`，说明各 reader condition token 的贡献；
+它不独立形成 Finding、limit 或 waiver identity。CCN detail message 最多展示八项，余数仍在 Record 中。
 
-Record metric 与 measurement 的对应关系如下：
+input-rejected Record 的 ID 为 `/input-rejected/<path>`，data 包含 `blocking: false`、`kind: "input-rejected"`、
+`path`、全部 `codeAreas` 与 `reason: "unsupported-file-type"`。metric details 后展示 rejection details，并附 `input-rejected` 数量 warning；
+终端呈现和 progress 预览边界见[呈现 Check Finding](../guides/presenting-findings.md)。
 
-| `metric` | `value` 的含义 | effective limit 来源 |
-| --- | --- | --- |
-| `cyclomatic-complexity` | Lizard CCN | matching areas 的 `cyclomaticComplexity.maximum` 最小值 |
-| `function-code-density` | function NLOC；该 ID 不表示比例 | matching areas 按各自 allowance 条件计算后的 code-line maximum 最小值 |
-| `parameter-count` | function parameter count | matching areas 的 `parameters.maximum` 最小值 |
+Applied waiver 为原 Record 加 `waiver.reason`、将 `blocking` 设为 `false`，并附 `finding-waived` info。
+Unused/overmatched authoring 不应用 waiver，另发 `kind: "finding-waiver-audit"` Record，包含 identity、reason、matchCount、status，
+ID 为 `/finding-waiver-audit/sha256:<canonical-identity-digest>`，并附 warning。
 
-每个 rejected selected path 另产生一条 ID 为 `/input-rejected/<path>` 的 Record：
-
-```ts
-{
-  blocking: false,
-  codeAreas: readonly string[],
-  kind: "input-rejected",
-  path: string,
-  reason: "unsupported-file-type"
-}
-```
-
-`codeAreas` 是该 path 被选中的全部 area IDs，经去重和稳定排序。即使 area policy 为 blocking，这个 Finding 也固定
-non-blocking；它不包含函数或伪造 measurement。
-
-正常 final data 是 `{ findingCount, blockingFindingCount }`。`findingCount` 包含 metric 与 input-rejection Records，
-`blockingFindingCount` 只统计 effective blocking metric findings。后者大于零时 outcome 为 `failed`；只有 non-blocking
-findings 时 outcome 为 `passed`，Records 仍完整保留。
-
-`failed` 的 `blocking-findings` message 与携带 non-blocking metric Records 的 `passed` 的 `non-blocking-findings` message
-都会引导调用方检查本 Check 的 Records；有 rejected input 时另附一条 `input-rejected` warning，只汇总数量，不省略逐路径
-Record。由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；若 rejection Records 已发布，它们与
-对应 warning 仍保留。零 finding 的 `passed` 与 `not-applicable` 不合成人为提示。
-
-用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseFunctionMetricsData(value)` 验证 final data。两者返回
-`FunctionMetricsFinalData`，Record 与不可用原因可分别用 `FunctionMetricsRecordData` 和
-`FunctionMetricsUnavailableReasonCode` 标注；authoring / resolved options types 是 `FunctionMetricsOptions` 与
-`ResolvedFunctionMetricsOptions`。parser 只适用于 `passed` / `failed` data，不匹配时抛出 `TypeError`。
+用返回 Check 的 `check.parseData(value)` 或 `parseFunctionMetricsData(value)` 验证 passed/failed 的 final data，返回
+`FunctionMetricsFinalData`；字段或计数不变量不匹配时抛出 `TypeError`。
+公开类型包括 `FunctionMetricsOptions`、`ResolvedFunctionMetricsOptions`、`FunctionMetricsFindingIdentity`、
+`FunctionMetricsFindingMetric`、`FunctionMetricsFindingWaiver`、`FunctionMetricsRecordData` 与
+`FunctionMetricsUnavailableReasonCode`。
 
 ## `not-applicable` 与 `unavailable`
 
-所有 area 的 selected path 去重并集为空时结算为 `not-applicable / no-eligible-input`。selected 非空但全部被 extension
-registry 拒绝时，不启动 Lizard，直接以带 input-rejection Records、warning 和 final counts 的 `passed` 结算。其它无法形成
-可信 final data 的边界结算为 `unavailable`：
+selected union 为空时为 `not-applicable / no-eligible-input`；非空但全 rejected 时为带 Records、warning 与 final data 的 `passed`。
+两种情况下 configured waiver 均产生 unused audit。以下条件在完整 metric Finding 集合形成前结算为 `unavailable`：
 
-| `reason.code` | 触发边界 | 调用方检查项 |
-| --- | --- | --- |
-| `invalid-options` | constructor 之后被普通 object composition 替换的完整 options 未通过 preflight 或 execution 防御校验 | 对照本页 resolved options，补齐或删除字段 |
-| `source-unavailable` | 所配置的 filesystem 或 git-worktree 来源无法形成候选快照 | 检查 project root、目录读取权限或 Git worktree 状态 |
-| `external-dependency-unavailable` | Lizard executable 不存在、version probe 失败或没有可识别的 version output | 检查 `scanner.executable` 与该命令的 `--version` 行为 |
-| `external-execution-failed` | Lizard scan 无法启动、被 signal 终止或返回非零状态 | 直接运行配置的 executable，检查 exact-path 与 `--csv` 调用 |
-| `external-result-invalid` | CSV、measurement、exact-scope 或 function metric 完整性校验失败 | 检查 wrapper 是否返回 Lizard 1.23-compatible CSV，且没有扩大输入 |
-| `cancelled` | invocation signal 在可观察的工作边界终止本 Check | 检查调用方取消原因；不要把该结果解释为 clean scan |
+| reason code | 含义与恢复操作 |
+| --- | --- |
+| `invalid-options` | 完整 resolved options 被普通 object composition 破坏；重新通过 `functionMetrics(options)` 构造 Check。 |
+| `source-unavailable` | 无法形成 filesystem/git-worktree 候选快照或安全读取 source；检查 project root、权限和 selected files。 |
+| `cancelled` | invocation signal 在可观察工作边界取消；检查调用方取消原因，必要时重试。 |
+| `resource-limit-exceeded` | 单文件超过 `8 MiB` 或 accepted aggregate 超过 `64 MiB`；缩小 selection 或减小 source input。 |
+| `analysis-failed` | 内置 analyzer 无法形成完整可信结果；检查选中的 source 并在修正后重试。 |
 
-constructor 自身会同步拒绝 unknown、malformed 或 incomplete input，并抛出 `TypeError`；表中的 `invalid-options` 用于
-constructor 返回后又被替换的 resolved options。通用 preflight 语法见
-[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+`unavailable` 带对应 `reason.code` 的 error message，无 final data，不伪造 waiver audit；已发布的 input-rejected Records 与 warning 保留。
 
 ## I/O 与安全边界
 
-execution 只把各 area files 中 Lizard 1.23.0 官方 reader 支持的 extension exact paths 交给本机 Lizard；匹配大小写不敏感，
-支持的 extension table 同时生成默认 globs 与 runtime predicate。未被该 table 识别的 Markdown、JSON 等 selected files
-产生拒绝 Finding，但不交给 Lizard，避免其 C-like fallback 误解析非代码文本；scanner 不接收 project root 重新发现输入。
-该 Check 的网络 request 数为零。Lizard 收到 accepted exact path 后是否产生函数 row 属于 backend measurement semantics，
-不能由本 Check 推断为 input rejection。
-
-## 最小用法
-
-```ts
-import { defineConfig, functionMetrics, run } from "@zxyycom/vibe-check";
-const result = await run(defineConfig({ checks: [functionMetrics()] }));
-```
+Check 只读取其 `codeAreas[id].files` 选出的 project-local exact inputs，并将 accepted paths 交给内置 analyzer。
+分析在本地完成，不执行外部 command、不发起网络请求，也不修改 source files。
 
 ## 适用边界
 
-该 Check 适用于函数 NLOC、cyclomatic complexity 与 parameter-count policy；文件级 code-line policy 由
-[`fileMetrics`](file-metrics.md) 评估，重复片段由
-[`duplicateDetection`](duplicate-detection.md) 报告。
+文件级 code-line policy 由 [`fileMetrics`](file-metrics.md) 评估，重复片段由 [`duplicateDetection`](duplicate-detection.md) 报告。