@zxyycom/vibe-check 0.0.1

package/docs/checks/duplicate-detection.md

@@ -0,0 +1,195 @@
+# `duplicateDetection`
+
+返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
+
+## 用途
+
+本页是 package consumer 配置和读取 `duplicateDetection` 的主指南。`duplicateDetection(options?)` 使用带默认值的
+policy 构造一个普通 `duplicate-detection` Check。该 Check 用 jscpd 比较自己批准的项目文件，把满足行数与 token
+policy 的重复片段报告为 supplemental Records，并分别报告 finding 总数与 blocking finding 数量。
+
+默认 package command 使用随 `@zxyycom/vibe-check` 安装的 jscpd v5；项目无需选择版本、提供 executable 或复制默认 options：
+
+```ts
+import { duplicateDetection } from "@zxyycom/vibe-check";
+
+const check = duplicateDetection();
+```
+
+## 参数与默认配置
+
+顶层 `cache`、`codeAreas`、`findingPolicy` 与 `scanner` 都可省略；显式 `codeAreas[areaId]` 只要求提供
+`files` branch。无参调用物化成以下完整 Check options，调用方无需复制：
+
+```ts
+{
+  cache: { directory: ".cache/vibe-check", enabled: true },
+  codeAreas: {
+    project: {
+      files: defaultProjectFileSelection,
+      findingPolicy: "non-blocking",
+      minimumLines: 4,
+      minimumTokens: 100
+    }
+  },
+  scanner: {
+    command: { kind: "package" }
+  }
+}
+```
+
+这里的 `defaultProjectFileSelection` 是从 package root 公开的深冻结完整基线；constructor 会把同值 files branch 物化到
+自己的 resolved options，调用方无需复制该对象；完整默认 glob 可直接从该 public value 读取。
+
+- 省略整个 `codeAreas` 时建立默认 `project` area。显式 map 必须至少包含一个非空 area id。
+- 每个显式 area 必须提供 `files` branch。`source` 只能是 `"filesystem" | "git-worktree"`，默认 `filesystem`。
+  `filesystem` 枚举普通文件且不解释 `.gitignore`；`git-worktree` 使用已跟踪文件和未被 Git 标准忽略规则排除的
+  未跟踪文件。来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
+- `include` 与 `exclude` 都按 project-root-relative slash path 的 glob 匹配，exclude 优先。两者可分别省略并使用公开的
+  `defaultProjectFileSelection`；显式数组是完整替换值，`include: []` 不选择路径，`exclude: []` 不排除路径。
+- 顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，默认 `non-blocking`；area 可覆盖，省略时继承顶层值。
+- `minimumLines` 与 `minimumTokens` 可省略并分别使用 `4` 和 `100`，显式值必须是正安全整数。
+- `cache.directory` 省略时为 `.cache/vibe-check`，相对路径从 project root 解析；`cache.enabled` 省略时为 `true`。
+- `scanner.command` 省略时为 `{ kind: "package" }`。
+- 未知字段、空 area map、缺失 area `files`、非法阈值或非法 scanner policy 会由 constructor 同步抛出
+  `TypeError`。
+
+## 定制区域 policy
+
+调用方只声明要改变的 policy，不需要读取默认 Check。下面两个 area 各自拥有文件范围和阈值；省略的 file fields、
+finding policy 与阈值由 constructor 补齐。只有追加默认数组时才组合公开的 files 基线：
+
+```ts
+import { defaultProjectFileSelection, duplicateDetection } from "@zxyycom/vibe-check";
+
+const sourceAndScriptsDuplicateDetection = duplicateDetection({
+  codeAreas: {
+    source: {
+      files: { include: ["src/**/*.ts"] },
+      minimumTokens: 20
+    },
+    scripts: {
+      files: {
+        ...defaultProjectFileSelection,
+        include: ["scripts/**/*.ts"],
+        exclude: [...defaultProjectFileSelection.exclude, "scripts/**/*.test.ts"]
+      },
+      minimumLines: 10,
+      minimumTokens: 100
+    }
+  }
+});
+```
+
+每个 `codeAreas[id]` 都是该区域文件范围、有效 finding policy 与行数/token 下限的单一事实源。上例的
+`scripts.exclude` 显式保留 common defaults 并追加测试文件；若只写 `["scripts/**/*.test.ts"]`，它会完整替换默认排除数组。
+
+## 定制 jscpd executable
+
+只有项目确实授权另一个可执行文件时才设置 custom command：
+
+```ts
+import { duplicateDetection } from "@zxyycom/vibe-check";
+
+const customDuplicateDetection = duplicateDetection({
+  scanner: {
+    command: {
+      kind: "custom",
+      executable: "/absolute/path/to/jscpd"
+    }
+  }
+});
+```
+
+`executable` 必须是已授权、可执行且**直接接受 jscpd CLI 参数**的 command。public scanner policy 只选择 command；
+owning adapter 负责 version probe、exact-path config、JSON report 与 jscpd 的自动 worker policy。实际版本用于区分 cache
+provenance，不要求 custom command 等于 package 当前安装的版本。
+
+需要靠前置参数才能转发到 jscpd 的通用 runtime（例如 `node path/to/jscpd.js`）不是受支持的 custom command；应直接
+提供 jscpd executable 或一个已授权的专用 wrapper executable。
+
+默认 package command 使用安装包声明并由 package manager 解析的兼容 jscpd v5。package 或 custom command 的实际版本都会
+隔离 cache；command、config 或 report 不兼容时，Check fail closed 为 `unavailable`，不会把无法完成的扫描伪装成零
+finding。
+
+## 工作原理
+
+Check 先按文件 `source` 分组；每种不同来源只枚举一次候选文件，再为各 `codeAreas[id].files` 应用自己的
+`include` / `exclude`，最后把全部路径去重成一个批准的精确范围。一个路径可同时属于多个 area；全部 exact paths 仍
+一次性交给 jscpd，因此同 area、跨 area 与重叠 area 文件都会互相比较：
+
+1. jscpd 使用所有实际输入 area 中最低的 line 阈值和最低的 token 阈值取得完整候选。
+2. 每个 raw fragment 的 location path 必须属于本次完整 exact scope；任一路径越界都会拒绝整批 measurement。
+3. Check 按 location path 恢复它匹配的全部 areas。fragment 的 line count 和 token count 必须分别达到所有涉及 area
+   对应阈值中的最大值，才形成 finding。
+
+例如 `source` 使用 line `3` / token `20`，`scripts` 使用 line `10` / token `100` 时，scanner 使用 line `3` /
+token `20` 取得候选；跨这两个 area 的 8-line / 120-token fragment 和 12-line / 80-token fragment 都会被过滤，只有
+同时达到 line `10` 与 token `100` 的 fragment 会保留。
+
+cache 只保存通过 exact-input 校验的 scanner fragments；无论是否命中 cache，当前 area annotation 与最终 policy filtering
+都走同一路径。只有 package/custom command identity、实际 jscpd 版本、当前 commit、完整 exact-input fingerprint 和实际
+影响 scanner 结果的配置均匹配时才会复用；package command identity 不含 consumer 安装目录，custom command identity 使用
+项目显式提供的 executable。
+
+## 效果与结果
+
+每个可信 finding 都形成 Record，不因 policy 或先前 finding 而省略。若 fragment 涉及多个 areas，只要任一 effective
+`findingPolicy` 为 `blocking`，该 Record 的 `blocking` 就为 `true`。正常 final data 恰为
+`{ findingCount, blockingFindingCount }`；前者等于 Records 数量，后者等于其中 `blocking: true` 的数量。
+`blockingFindingCount > 0` 时 outcome 为 `failed`，否则为 `passed`，所以 passed outcome 可以携带 non-blocking Records。
+
+每个 Record data 使用以下字段：
+
+```ts
+{
+  blocking: boolean,
+  metric: "duplicate-tokens",
+  tokenCount: number,
+  lineCount: number,
+  codeAreas: string[],
+  locations: Array<{ path: string; startLine: number; endLine: number }>
+}
+```
+
+`failed` 的 `blocking-findings` message 与携带 non-blocking Records 的 `passed` 的 `non-blocking-findings` message 都会引导
+调用方检查本 Check 的 Records。由本 Check 结算的 `unavailable` 会使用对应 `reason.code` 提供 error message；零 finding
+的 `passed` 与 `not-applicable` 不合成人为提示。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseDuplicateDetectionData(value)` 验证 final data。两者返回
+`DuplicateDetectionFinalData`，Record 与不可用原因可分别用 `DuplicateDetectionRecordData` 和
+`DuplicateDetectionUnavailableReasonCode` 标注；authoring / resolved options types 是 `DuplicateDetectionOptions` 与
+`ResolvedDuplicateDetectionOptions`。parser 只适用于 `passed` / `failed` data，shape 或计数不变量不匹配时抛出
+`TypeError`。
+
+## `not-applicable` 与 `unavailable`
+
+- 少于两个合格 exact inputs：`not-applicable / no-eligible-input`。
+- constructor 后形成的 resolved options 不符合完整 shape：`unavailable / invalid-options`。
+- 所配置的 filesystem 或 git-worktree 来源无法形成候选快照：`unavailable / source-unavailable`。
+- package/custom command 缺失、version probe 失败或无法形成可识别版本 provenance：
+  `unavailable / external-dependency-unavailable`。
+- 已启动 jscpd 但进程执行失败：`unavailable / external-execution-failed`。
+- cache 写入失败：`unavailable / cache-write-failed`。
+- report、fragment 或 exact-input membership 无法形成可信完整结果：`unavailable / external-result-invalid`。
+
+通用 preflight 机制见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## I/O 与安全边界
+
+execution 启动一次本机 jscpd 调用；输入只包含各 `codeAreas[id].files` 批准的 exact paths 去重并集。显式配置
+`scanner.command.kind: "custom"` 表示项目授权执行其中的 executable；所有传入参数由 owning adapter 生成。该 Check
+不发起网络请求。
+
+## 最小用法
+
+```ts
+import { defineConfig, duplicateDetection, run } from "@zxyycom/vibe-check";
+
+const result = await run(defineConfig({ checks: [duplicateDetection()] }));
+```
+
+## 适用边界
+
+该 Check 负责报告重复片段及其数量；consumer 根据代码语义和架构目标决定是否以及如何重构。它不会自动改写源码，
+也不会把 token 数量单独解释为重构优先级。

package/docs/checks/file-metrics.md

@@ -0,0 +1,229 @@
+# `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 输入之外。
+
+无参调用使用完整默认策略：
+
+```ts
+import { fileMetrics } from "@zxyycom/vibe-check";
+
+const check = fileMetrics();
+```
+
+执行这个 Check 时，project runtime 需要让默认 `scc` command 可用，或在 `scanner.executable` 中选择项目已授权且
+兼容 SCC 3.7.0 version output 与 CSV contract 的 executable。
+
+## 参数与默认配置
+
+顶层 `codeAreas`、`findingPolicy`、`findingWaivers` 与 `scanner` 都可省略。每个 `codeAreas[areaId]` 同时拥有文件选择和代码行
+策略，因此不同区域可以选择不同文件并使用不同上限。无参调用物化以下完整、冻结的 Check options：
+
+```ts
+{
+  codeAreas: {
+    project: {
+      files: defaultProjectFileSelection,
+      findingPolicy: "non-blocking",
+      codeLines: {
+        maximum: 360,
+        lowDecisionTokenAllowance: {
+          maximumCodeLines: 600,
+          maximumDecisionTokens: 12
+        }
+      }
+    }
+  },
+  findingWaivers: [],
+  scanner: { executable: "scc" }
+}
+```
+
+这里的 `defaultProjectFileSelection` 是从 package root 公开的深冻结完整基线；constructor 会把同值 files branch 物化到
+自己的 resolved options，调用方无需复制该对象；完整默认 glob 可直接从该 public value 读取。
+
+### 字段规则
+
+- 省略整个 `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: []` 不排除路径。
+- 顶层 `findingPolicy` 只能是 `"blocking" | "non-blocking"`，默认 `non-blocking`；area 可覆盖，省略时继承顶层值。
+- `findingWaivers` 省略时为 `[]`。每项必须是 `{ 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，实际行数与上限仍会随策略变化。
+- 省略 `codeLines` 时使用完整默认代码行策略；`maximum` 与 allowance 内的字段也可分别省略。
+- `maximum` 与 `maximumCodeLines` 必须是正安全整数，`maximumDecisionTokens` 必须是非负安全整数；
+  allowance 的 `maximumCodeLines` 必须严格大于同一区域的普通 `maximum`。
+- `scanner.executable` 必须是非空字符串。省略 `scanner` 或 `scanner.executable` 时直接执行 `scc`。
+- 未知字段、空区域 map、缺失 `files` 或非法字段值会让 constructor 同步抛出 `TypeError`。
+
+### 为不同文件配置策略
+
+```ts
+import { defaultProjectFileSelection, fileMetrics } from "@zxyycom/vibe-check";
+
+const sourceAndTests = fileMetrics({
+  codeAreas: {
+    source: {
+      files: { include: ["src/**/*.ts"] },
+      codeLines: { maximum: 300 }
+    },
+    tests: {
+      files: {
+        ...defaultProjectFileSelection,
+        exclude: [...defaultProjectFileSelection.exclude, "**/fixtures/**"],
+        include: ["test/**/*.ts", "src/**/*.test.ts"]
+      },
+      codeLines: {
+        maximum: 600,
+        lowDecisionTokenAllowance: {
+          maximumCodeLines: 800,
+          maximumDecisionTokens: 20
+        }
+      }
+    }
+  }
+});
+```
+
+本例只覆盖各区域显式给出的字段；省略的文件字段、finding policy 和代码行字段继续使用 package 默认值。`tests` area
+通过公开的深冻结 `defaultProjectFileSelection` 保留 common exclusions，再追加项目的 fixture 规则。
+
+### 单个区域的有效上限
+
+SCC CSV 的 `Complexity` 字段是 file-metrics 使用的 decision-token measurement。Check 按下表为每个文件、
+每个匹配区域计算一次有效代码行上限：
+
+| SCC decision-token measurement             | 区域的有效代码行上限                         |
+| ------------------------------------------ | -------------------------------------------- |
+| 非 `null` 且不大于 `maximumDecisionTokens` | `lowDecisionTokenAllowance.maximumCodeLines` |
+| `null` 或大于 `maximumDecisionTokens`      | `codeLines.maximum`                          |
+
+只有实际 `codeLines` **严格大于**有效上限时，该区域策略才判定文件超限。
+
+## 工作原理
+
+1. Check 先按文件 `source` 分组；每种不同来源只枚举一次候选文件，再为每个 area 应用自己的 `include` / `exclude`，
+   并保存 path 到全部实际 area IDs 的 membership。
+2. Check 对全部路径稳定排序、去重，只把这个 exact-path union 交给 SCC 一次。
+3. 每条 SCC measurement 必须声明属于该 union 的 source path；任一越界 measurement 会拒绝整批结果。
+4. 对属于多个区域的文件，Check 分别计算各区域的有效代码行上限，并使用其中最小的严格上限：
+
+   ```text
+   file limit = min(effective maximum of every matching area)
+   ```
+
+5. 一个超限路径最多发布一条 Record，因此区域重叠不会重复扫描、重复记录或重复计数。Record 保留稳定排序的
+   全部匹配 area IDs；任一 matching area 的 effective finding policy 为 blocking 时，该 Record blocking。
+
+## 定制 SCC executable
+
+只有项目明确授权另一个可执行文件时才配置 `scanner.executable`：
+
+```ts
+const customFileMetrics = fileMetrics({
+  scanner: { executable: "/absolute/path/to/scc" }
+});
+```
+
+custom executable 必须直接接受 SCC CLI 参数。public scanner policy 只选择 executable；owning adapter 固定执行以下协议：
+
+- availability probe：`--version`
+- measurement：`--by-file --format csv <approved exact paths...>`
+- process timeout：由 adapter 固定，不属于项目策略
+
+需要 prefix arguments 的通用 runtime（例如 `node path/to/tool.js`）不是受支持的直接 command；项目应提供一个已授权的
+专用 wrapper executable。当前 adapter 只接受 SCC `3.7.0` 的 version output 与对应 CSV header contract。
+
+### 安装兼容 SCC
+
+项目可以用自己的工具管理方式提供 `scc`。本仓库验证的项目拥有安装方式是在 `mise.toml` 固定 Go 与 SCC：
+
+```toml
+[tools]
+go = "1.25"
+"go:github.com/boyter/scc/v3" = { version = "v3.7.0", depends = ["go"] }
+```
+
+运行 `mise install` 后，用 `scc --version` 确认当前 project runtime 能解析到该命令。若项目使用其它安装方式，只要
+`scanner.executable` 指向已授权、直接接受上述协议并产生 SCC 3.7.0-compatible output 的 executable 即可。
+
+## 效果与结果
+
+每个可信 finding 都形成 Record，不因 policy 或先前 finding 而省略。正常 final data 恰为
+`{ findingCount, blockingFindingCount }`；前者等于 SCC 形成的 finding 数量，后者只计没有被 applied waiver 覆盖的
+`blocking: true` finding。`blockingFindingCount > 0` 时 outcome 为 `failed`，否则为 `passed`，所以 passed outcome 可以携带
+non-blocking 或 waived finding Records。
+
+每个超限路径发布一条 supplemental Record。Record ID 是 path，data shape 为：
+
+```ts
+{
+  blocking: boolean;
+  codeAreas: string[]; // 稳定排序的全部匹配 area IDs
+  codeLines: number;
+  limit: number;       // 全部匹配区域中的最严格有效上限
+  metric: "code-lines";
+  path: string;
+  waiver?: { reason: string };
+}
+```
+
+精确命中一项 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
+与正常 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。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseFileMetricsData(value)` 验证 final data。两者返回
+`FileMetricsFinalData`，Record 与不可用原因可分别用 `FileMetricsRecordData` 和
+`FileMetricsUnavailableReasonCode` 标注；authoring / resolved options types 是 `FileMetricsOptions` 与
+`ResolvedFileMetricsOptions`。parser 只适用于 `passed` / `failed` data，不匹配时抛出 `TypeError`。
+
+## `not-applicable` 与 `unavailable`
+
+| 阶段或条件                                                       | Check 结果                                      |
+| ---------------------------------------------------------------- | ----------------------------------------------- |
+| 全部区域的 exact-path union 为空                                 | `not-applicable / no-eligible-input`；已配置 waiver 仍产生 unused audit |
+| resolved options 不符合完整 closed shape                         | `unavailable / invalid-options`                 |
+| 所配置的 filesystem 或 git-worktree 来源无法形成候选集合         | `unavailable / source-unavailable`              |
+| SCC command 缺失、version probe 失败或版本不匹配                 | `unavailable / external-dependency-unavailable` |
+| SCC measurement process 执行失败                                 | `unavailable / external-execution-failed`       |
+| CSV、measurement scope 或 Record conversion 不能形成可信完整结果 | `unavailable / external-result-invalid`         |
+
+合法的 SCC CSV header 后没有 measurement rows 是可信空 measurement，不等同于 command、执行或解析失败。
+
+## I/O 与安全边界
+
+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 由
+[`functionMetrics`](function-metrics.md) 评估；`fileMetrics` 不格式化、拆分或修改源文件。

package/docs/checks/function-metrics.md

@@ -0,0 +1,222 @@
+# `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。
+
+```ts
+import { functionMetrics } from "@zxyycom/vibe-check";
+
+const check = functionMetrics();
+```
+
+执行这个 Check 时，project runtime 需要让默认 `lizard` command 可用，或在 `scanner.executable` 中选择项目已授权且
+兼容 Lizard 1.23 version output 与 CSV contract 的 executable。
+
+## 参数与默认配置
+
+顶层 `findingPolicy`、`codeAreas` 与 `scanner` 都可省略；显式 `codeAreas[areaId]` 只要求提供 `files` branch。
+`functionMetrics()` 按下表物化完整、冻结的 resolved options，调用方无需复制默认数组：
+
+| Resolved field | 无参默认值 |
+| --- | --- |
+| `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 补齐。
+
+```ts
+import { defaultProjectFileSelection, functionMetrics } from "@zxyycom/vibe-check";
+
+const metrics = functionMetrics({
+  findingPolicy: "non-blocking",
+  codeAreas: {
+    source: {
+      files: { include: ["src/**/*.ts"] },
+      findingPolicy: "blocking",
+      limits: {
+        cyclomaticComplexity: { maximum: 10 },
+        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：
+
+```ts
+const metrics = functionMetrics({
+  scanner: { executable: "/opt/tools/lizard" }
+});
+```
+
+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 短路。
+
+## 效果与结果
+
+每个超过 effective limit 的 metric 产生一个 metric Record，data 包含：
+
+```ts
+{
+  blocking: boolean,
+  codeAreas: readonly string[],
+  functionName: string,
+  limit: number,
+  metric: "cyclomatic-complexity" | "function-code-density" | "parameter-count",
+  path: string,
+  startLine: number,
+  value: number
+}
+```
+
+Record metric 与 measurement 的对应关系如下：
+
+| `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` 最小值 |
+
+每个 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`。
+
+## `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`：
+
+| `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 |
+
+constructor 自身会同步拒绝 unknown、malformed 或 incomplete input，并抛出 `TypeError`；表中的 `invalid-options` 用于
+constructor 返回后又被替换的 resolved options。通用 preflight 语法见
+[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## 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 适用于函数 NLOC、cyclomatic complexity 与 parameter-count policy；文件级 code-line policy 由
+[`fileMetrics`](file-metrics.md) 评估，重复片段由
+[`duplicateDetection`](duplicate-detection.md) 报告。