@zxyycom/vibe-check 0.0.1 → 0.0.2

package/docs/checks/function-metrics.md

@@ -1,61 +1,68 @@
 # `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 分析所选的受支持源文件。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
 
 ```ts
-import { functionMetrics } from "@zxyycom/vibe-check";
+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，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`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 +72,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` 最小值 |
-
-每个 rejected selected path 另产生一条 ID 为 `/input-rejected/<path>` 的 Record：
-
-```ts
-{
-  blocking: false,
-  codeAreas: readonly string[],
-  kind: "input-rejected",
-  path: string,
-  reason: "unsupported-file-type"
-}
-```
+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。
 
-`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) 报告。

package/docs/checks/json-schema-validation.md

@@ -1,12 +1,39 @@
 # `jsonSchemaValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `jsonSchemaValidation` 的 options、terminal effects 与安全边界。该 Check 使用显式 schema registry 与
-instance bindings 验证选定的 JSON instances。`jsonSchemaValidation(options?)` 补齐默认值并返回可直接放入 Project
-Definition `checks` 的普通 Check。
+`jsonSchemaValidation(options?)` 构造普通 Check，使用显式 schema registry 与 instance bindings 验证 JSON instances。
+先声明 schema 与 binding；无参调用不发现 schema，并结算为 `not-applicable / no-bindings`。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, jsonSchemaValidation, run } from "@zxyycom/vibe-check";
+
+const configured = {
+  schemas: [{ id: "urn:example:config", path: "schema/config.json" }],
+  bindings: [
+    { id: "config", instancePath: "config.json", schemaId: "urn:example:config" }
+  ]
+};
+const schemaCheck = jsonSchemaValidation(configured);
+const result = await run(defineConfig({
+  checks: [schemaCheck],
+  outputs: { machinePublication: { enabled: false } }
+}));
+const outcome = result.kind === "completed"
+  ? result.snapshot.checks.find(({ checkId }) => checkId === schemaCheck.checkId)?.outcome
+  : undefined;
+if (result.kind !== "completed" || outcome?.status !== "passed") {
+  console.error(`JSON Schema validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -21,17 +48,11 @@ Definition `checks` 的普通 Check。
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`defaultProjectFileSelection` 是 package root 公开的同值深冻结
-基线；完整默认 glob 可直接从该 public value 读取。六个顶层 authoring fields 都可省略；`files` 内的三个字段也可分别省略。显式 `schemas`、`bindings` 与
-`referenceResolution.sources` 数组是完整替换值。`schemaIdentity` 与
-`referenceResolution` 的显式 discriminated branch 必须自身完整。无参调用不会发现 schema；由于 `bindings: []`，它结算为
-`not-applicable / no-bindings`。constructor 返回后若通过普通对象组合替换 `check.options`，replacement 才必须保留完整
-resolved shape。
-
-- `files` 完整定义本 Check 可读取的 local paths；source 可选 `filesystem` 或 `git-worktree`，selected path 必须命中
-  `include` 且不能命中 `exclude`。filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略
-  规则排除的未跟踪文件。schema 与 instance 的读取 scope 是 selected set；来源不可用时 Check 结算为
-  `unavailable`，不会切换到另一来源。
+无参调用物化上述完整 options；`files` 使用 package root 公开的深冻结 `defaultProjectFileSelection` 基线。
+六个顶层字段及 `files` 子字段都可省略；显式 `schemas`、`bindings`、`referenceResolution.sources` 数组完整替换默认值。
+`schemaIdentity` 与 `referenceResolution` 的显式 discriminated branch 必须完整；constructor 后替换 `check.options` 也须保留完整 resolved shape。
+
+- `files` 遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)，selected set 是 schema 与 instance 的本地读取 scope；来源不可用时不切换来源。
 - `maximumBytes` 是每个 schema 或 instance document 的 raw byte 上限，必须是正安全整数。
 - `schemas` 每项为 `{ id, path }`；schema `id` 是 1–256 字符且没有 credentials、query 或 fragment 的绝对
   `https:` / `urn:` identity，`path` 是 1–512 字符的 normalized project-relative 小写 `.json` path。schema ID 与 path
@@ -82,11 +103,12 @@ fragment 的精确 HTTPS origin；`pathPrefix` 最长 256 字符，从 `/` 开
 
 ## 工作原理
 
-constructor 先关闭 authoring shape、补齐并冻结 resolved options。Run 的全局 preflight barrier 验证完整 options 后，zero
-bindings 结算为 `not-applicable`；其它调用从 `files`
-selection 建立可读 path set，加载 registered schemas，按 identity policy 编译，再验证每个 binding。selected set
-之外的声明 path 形成 `out-of-scope` domain issue，读取 scope 保持为 selected set。schema document、compile 与
-instance issues 形成 Records。
+constructor 补齐并冻结 closed options；获 Scheduler admission 后先 preflight，再建立 selected path set、加载 registry、
+按 identity policy 编译并验证 bindings。selected set 外的声明路径形成 `out-of-scope` issue，不扩大读取范围。
+schema document、compile 与 instance issues 均形成 Records。
+
+local schema 与 instance document 复用 [JSON Validation 工作原理](json-validation.md#工作原理)定义的 strict-document
+boundary；本指南只增加 schema identity、reference resolution、binding 与 engine settlement，不建立另一套 JSON 解析规则。
 
 ## 效果与结果
 
@@ -167,21 +189,6 @@ binding 数量为零时结算为 `not-applicable / no-bindings`。`unavailable.r
 remote scope；每次 response 最多读取 1,048,576 bytes，单次请求 timeout 为 5 秒。request 不携带 credentials 或 custom
 headers，也不跟随 redirect。remote reference authorization 保持 local file selection 不变。
 
-## 最小用法
-
-```ts
-import { defineConfig, jsonSchemaValidation, run } from "@zxyycom/vibe-check";
-
-const configured = {
-  schemas: [{ id: "urn:example:config", path: "schema/config.json" }],
-  bindings: [
-    { id: "config", instancePath: "config.json", schemaId: "urn:example:config" }
-  ]
-};
-const schemaCheck = jsonSchemaValidation(configured);
-const result = await run(defineConfig({ checks: [schemaCheck] }));
-```
-
 ## 适用边界
 
 该 Check 适用于显式 schema registry 与 bindings。JSON Schema `format` 使用 2020-12 annotation 语义，不加载 format

package/docs/checks/json-validation.md

@@ -1,12 +1,33 @@
 # `jsonValidation`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `jsonValidation` 的 options、terminal effects 与安全边界。该 Check 严格验证自己选择且以小写
-`.json` 结尾的文档，并报告 syntax error、duplicate key 与 incomplete document。`jsonValidation(options?)` 补齐默认值并
-返回可直接放入 Project Definition `checks` 的普通 Check。
+`jsonValidation(options?)` 构造普通 Check，严格验证所选小写 `.json` 文档的完整性，报告 syntax error、duplicate key
+与 incomplete document。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, jsonValidation, run } from "@zxyycom/vibe-check";
+
+const check = jsonValidation();
+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(`JSON validation did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -21,16 +42,12 @@
 }
 ```
 
-上面的代码块是无参调用物化后的完整 resolved options；`exclude` 表示 constructor detached-copy 了 package root 公开
-`defaultProjectFileSelection.exclude` 的全部条目，不是调用方必须复制的输入。authoring options 的 `files` 与
-`maximumBytes` 都可以省略；`files.source`、`files.include` 与 `files.exclude` 也可分别省略。source 可选 `filesystem` 或
-`git-worktree`，selected path 必须命中
-`include` 且不能命中 `exclude`。只有其中 case-sensitive `path.endsWith(".json")` 的 paths 成为输入。
-filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略规则排除的未跟踪文件。两种来源都使用
-本页 `files` branch 的 `include` / `exclude` glob；来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
-`maximumBytes` 是每个 raw JSON document 的 byte 上限，必须是正安全整数。显式 `include` / `exclude` 数组是完整替换值；
-例如显式 `include: ["**/*"]` 会选择其它类型，Check 将为每个不受支持的 path 发布拒绝 Finding，而不会静默过滤。
-constructor 返回后若通过普通对象组合替换 `check.options`，该 replacement 才必须提供完整 resolved shape。
+无参调用物化上述完整 options，其中 `exclude` 是公开 `defaultProjectFileSelection.exclude` 的独立副本。
+`files`、其子字段和 `maximumBytes` 都可省略；`maximumBytes` 必须是正安全整数。
+
+文件来源、glob 与数组替换遵循[共享 files 选择语义](../guides/collecting-project-files.md#共享的-files-选择语义)。
+本 Check 只读取 case-sensitive `path.endsWith(".json")` 的 selected paths；宽泛 include 选中的其它路径发布拒绝 Finding，
+不静默过滤。constructor 后替换 `check.options` 时，必须提供完整 resolved shape。
 
 ### 定制 authoring options
 
@@ -46,9 +63,12 @@ const configJsonValidation = jsonValidation({
 
 ## 工作原理
 
-constructor 先关闭 authoring shape、补齐并冻结 resolved options。Run 的全局 preflight barrier 再验证该完整 options；
-execution 收集 selected paths，按小写 `.json` suffix 完整分成 accepted/rejected。每个 rejected path 先产生 supplemental
-Record，accepted path 才通过 strict-document boundary 读取和解析；无效文档产生另一种 supplemental Record。
+constructor 补齐并冻结 closed options，获 Scheduler admission 后先 preflight，再按本页 suffix 规则完整分类输入。
+每个 rejected path 先发布 Record；accepted path 才读取、解析，无效文档另发 Record。
+
+strict-document boundary 先按 byte length 应用 `maximumBytes`，再依次区分 BOM、fatal UTF-8、strict JSON grammar 与 decoded
+duplicate key；每个文档只返回最先成立的封闭 reason。合法文档只向 owning Check 交付不含 prototype 的深冻结私有值，
+不会保留 source、AST、key 或 parser detail；读取或边界执行失败结算为 unavailable，而不是伪装成 invalid document。
 
 ## 效果与结果
 
@@ -120,13 +140,6 @@ Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 只使用以
 I/O scope 是 `files` 选中且通过小写 `.json` eligibility 的本地文件；rejected path 只形成事实，不读取内容。external
 command 和 network request 数均为零。
 
-## 最小用法
-
-```ts
-import { defineConfig, jsonValidation, run } from "@zxyycom/vibe-check";
-const result = await run(defineConfig({ checks: [jsonValidation()] }));
-```
-
 ## 适用边界
 
 该 Check 适用于 JSON document integrity；需要按 schema 评估字段与结构时使用

package/docs/checks/maintenance-reminders.md

@@ -1,11 +1,42 @@
 # `maintenanceReminders`
 
-返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
-
 ## 用途
 
-本页说明 `maintenanceReminders` 的输入、terminal effects 与安全边界。`maintenanceReminders(entries)` 创建一个固定
-ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核维护事项。
+`maintenanceReminders(entries)` 创建固定 ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核。
+
+## 最小用法
+
+示例保留终端进度，不写 machine files。
+
+```ts
+import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
+const check = maintenanceReminders([
+  {
+    id: "docs",
+    baseCommit: "0123456789abcdef0123456789abcdef01234567",
+    limits: { commits: 40 },
+    message: "Review docs.",
+    mode: "enforcing"
+  }
+]);
+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(`Maintenance reminders did not pass: ${result.kind} / ${outcome?.status ?? "no outcome"}`);
+  process.exitCode = 1;
+}
+```
+
+将占位 commit ID 换成项目 first-parent history 中的真实复核 commit；不存在的基线产生条目 `unavailable`。
+示例使用 `enforcing`，会因到期或不可测量失败；默认 `advisory` 只提醒。
+
+本例只接受 `completed` Run 中的 `passed` Check，否则退出非零。若需接受 `not-applicable` 或聚合多个 Check，
+显式配置并读取 [`checkAggregation`](../api-mechanics.md#runcontrols-与-check-aggregation)；`run(...)` 返回本身不表示通过。
 
 ## 参数与默认配置
 
@@ -30,8 +61,8 @@ ReadonlyArray<{
 - `message` 是到期或不可测量时展示的非空人读正文。
 - `mode` 省略时为 `advisory`；`enforcing` 使到期或不可测量的条目令所属 Check 失败。
 
-constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 的 preflight 在任何 Check
-execution 开始前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
+constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 获 Scheduler admission 后，其 task-local
+preflight 在自身 execution 前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
 `unavailable / invalid-options` 结算。
 
 ## 工作原理
@@ -87,12 +118,11 @@ type FinalData = Readonly<{ entries: readonly EntryAssessment[] }>;
 | `unavailable` | 附加 warning，不贡献失败。 | 附加 error，并令所属 Check 失败。 |
 
 `due` message code 是 `maintenance-reminder-due`，`unavailable` message code 是
-`maintenance-reminder-unavailable`。任一 `enforcing` entry 为 `due` 或 `unavailable` 时 Check outcome 为 `failed`；否则为
-`passed`。`due` message 正文是 `<id>: <message>`；`unavailable` 还在末尾追加 ` (<reason>)`。该 Check 不发布
-supplemental Records；条目也不会成为独立 Check、aggregation target 或 progress row。
+`maintenance-reminder-unavailable`。有条目贡献失败则 Check 为 `failed`，否则为 `passed`。
+`due` 正文是 `<id>: <message>`；`unavailable` 追加 ` (<reason>)`。不发布 supplemental Records；条目不成为独立
+Check、aggregation target、progress row 或 machine row。
 
-启用 machine publication 时，entries 只作为一项普通 `maintenance-reminders` Check 的 final data；entry 不形成独立
-machine row，terminal messages 也不进入 machine files。
+启用 machine publication 时只发布所属 Check 的 final data，terminal messages 不进入 machine files。
 
 用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMaintenanceRemindersData(value)` 验证 final data。parser
 验证每个 discriminated assessment、commit ID、唯一 reminder ID、计数、`exceeded` 与 reason 不变量，并返回
@@ -134,24 +164,6 @@ Git/历史测量的普通失败会保留完整 final data，并把受影响条
 I/O boundary 是本机 Git 对 committed first-parent history 的 read-only 查询。workspace、staging area 与 network
 request 数为零，baseline 更新由维护者提交。
 
-## 最小用法
-
-```ts
-import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
-const check = maintenanceReminders([
-  {
-    id: "docs",
-    baseCommit: "0123456789abcdef0123456789abcdef01234567",
-    limits: { commits: 40 },
-    message: "Review docs."
-  }
-]);
-const result = await run(defineConfig({ checks: [check] }));
-```
-
-示例 commit ID 只是 shape 占位值，必须替换为当前项目 first-parent history 中的真实复核 commit。若直接使用不存在的
-占位值，条目会得到 `assessment: "unavailable"`；这不是一次成功的维护基线配置。
-
 ## 适用边界
 
 该 Check 适用于按 commit count 或 changed-line count 提醒维护复核。是否把 `enforcing` failure 转为调用级阻断，