@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,190 @@
+# `jsonSchemaValidation`
+
+返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
+
+## 用途
+
+本页说明 `jsonSchemaValidation` 的 options、terminal effects 与安全边界。该 Check 使用显式 schema registry 与
+instance bindings 验证选定的 JSON instances。`jsonSchemaValidation(options?)` 补齐默认值并返回可直接放入 Project
+Definition `checks` 的普通 Check。
+
+## 参数与默认配置
+
+```ts
+{
+  files: defaultProjectFileSelection,
+  maximumBytes: 1_048_576,
+  schemaIdentity: { mode: "require-match" },
+  referenceResolution: { mode: "offline" },
+  schemas: [],
+  bindings: []
+}
+```
+
+上面的代码块是无参调用物化后的完整 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`，不会切换到另一来源。
+- `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
+  分别唯一。
+- `bindings` 每项为 `{ id, instancePath, schemaId }`；binding `id` 匹配 `[A-Za-z0-9][A-Za-z0-9_.-]{0,127}`，
+  `instancePath` 使用同一小写 `.json` path 规则，`schemaId` 必须引用已声明 schema。binding ID 与
+  `(instancePath, schemaId)` 分别唯一。
+- `schemaIdentity.mode` 为 `require-match`、`configuration-authoritative` 或 `document-authoritative`，决定 root `$id`
+  与 engine identity 的关系。
+- `referenceResolution` 默认 `{ mode: "offline" }`。`allowlisted` branch 可包含 package-fixed
+  `{ kind: "bundled", catalog: "json-schema-2020-12" }` 或显式
+  `{ kind: "https", id, origin, pathPrefix }` sources。
+
+### `schemaIdentity` 根身份规则
+
+`schemaIdentity` 是整个 Check 共用的 policy，不按 schema 分别选择：
+
+| `mode` | root `$id` 与 engine identity |
+| --- | --- |
+| `require-match`（默认） | root `$id` 必须等于 `schemas[].id`，该 configured ID 同时作为 engine identity。 |
+| `configuration-authoritative` | configured ID 是 engine identity；object schema 的 invocation-local compile copy 把 root `$id` 设为该 ID，已读取文档与发布 facts 不被改写；boolean schema 直接使用 configured identity。 |
+| `document-authoritative` | root `$id` 必须是安全 identity，并成为 engine identity；configured ID 继续作为 binding 与 Record 使用的 public label。 |
+
+### `referenceResolution` 引用解析规则
+
+默认 `offline` 仍允许 package-fixed JSON Schema 2020-12 catalog，但不发起网络请求。只有以下显式 branch 才允许读取
+额外 HTTPS schema：
+
+```ts
+{
+  mode: "allowlisted",
+  sources: [
+    { kind: "bundled", catalog: "json-schema-2020-12" },
+    {
+      kind: "https",
+      id: "urn:example:schema-source",
+      origin: "https://schemas.example.test",
+      pathPrefix: "/catalog/"
+    }
+  ]
+}
+```
+
+`sources` 必须非空，最多包含一个 bundled catalog；HTTPS source 的 `id` 与 `(origin, pathPrefix)` 分别唯一。HTTPS source
+`id` 使用与 schema ID 相同的 1–256 字符安全 identity；`origin` 是最长 200 字符且不含 path、credentials、query 或
+fragment 的精确 HTTPS origin；`pathPrefix` 最长 256 字符，从 `/` 开始，非 root prefix 以 `/` 结束，并排除 `\\`、`//`、
+`.` / `..` path segments、query 与 fragment。它不接受 headers、redirect、environment registry 或 callback loader。
+
+## 工作原理
+
+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。
+
+## 效果与结果
+
+`issueCount === 0` 时 outcome 为 `passed`；`issueCount > 0` 时 outcome 为 `failed`。正常 final data 恰为：
+
+```ts
+{
+  schemaCount: number,
+  bindingCount: number,
+  validBindingCount: number,
+  invalidBindingCount: number,
+  blockedBindingCount: number,
+  issueCount: number,
+  reportedIssueCount: number,
+  issuesTruncated: boolean
+}
+```
+
+`validBindingCount + invalidBindingCount + blockedBindingCount = bindingCount`。Check 验证全部可处理 bindings，但只发布
+前 100 条 issue Records；`issueCount` 保留真实总数，`reportedIssueCount` 是已发布数量，`issuesTruncated` 表示是否省略
+后续 Records。
+
+| Record `kind` | Record data 的领域字段 |
+| --- | --- |
+| `schema-document` | `schemaId`、`path`、document `reason` |
+| `schema-compile` | `schemaId`、`path`、closed compile `reason` |
+| `instance-document` | `bindingId`、`schemaId`、`path`、document `reason` |
+| `keyword-violation` | `bindingId`、`schemaId`、`path`、sanitized `pointer` 与 known `keyword` / `"other"` |
+
+document `reason` 是 `too-large | bom | invalid-utf8 | invalid-json | duplicate-key | out-of-scope`。compile issue、未授权或
+不受支持的 reference 都是可信 domain issue；compile `reason` 使用以下 closed set：
+
+```text
+duplicate-engine-id
+invalid-document-id
+invalid-schema
+missing-schema-id
+schema-id-mismatch
+unapproved-reference
+unsupported-reference
+remote-document-invalid
+remote-schema-id-mismatch
+```
+
+这些 issue 会让正常 outcome 为 `failed`，不同于 engine 或 transport `unavailable`。Records 不包含 source/response
+bytes、raw reference、credentials、engine message 或 stack。
+
+`failed` outcome 携带 `schema-validation-issues` error message；当 Records 因 100 条上限被截断时，message 会直接说明。
+由本 Check 结算的 `unavailable` 使用对应 `reason.code` 提供可操作 error message；`passed` 与 `not-applicable` 不合成人为
+提示。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseJsonSchemaValidationData(value)` 验证 final data。两者返回
+`JsonSchemaValidationFinalData`；Records 与原因可用 `JsonSchemaValidationRecordData`、
+`JsonSchemaValidationRecordReason`、`JsonSchemaDocumentReason` 和 `JsonSchemaValidationUnavailableCode` 标注，authoring /
+resolved options types 是 `JsonSchemaValidationOptions` 与 `ResolvedJsonSchemaValidationOptions`。parser 验证字段、计数等式、
+100 条 reported issue 上限与 truncation 不变量，不匹配时抛出 `TypeError`。
+
+## `not-applicable` 与 `unavailable`
+
+binding 数量为零时结算为 `not-applicable / no-bindings`。`unavailable.reason.code` 只使用以下值：
+
+| `reason.code` | 触发边界 | 调用方检查项 |
+| --- | --- | --- |
+| `invalid-options` | constructor 返回后形成的 replacement options 不是完整 closed resolved shape | 重新调用 `jsonSchemaValidation(options)`，或检查所有 branches、ID、path、唯一性与 binding 引用 |
+| `scan-input-unavailable` | configured file source 无法形成 selected set | 检查 project root、目录权限或 Git worktree 状态 |
+| `document-unavailable` | 某个 selected local schema 或 instance 无法完成受限读取 | 检查文件是否仍存在、是否可读，以及运行期间是否被替换 |
+| `reference-transport-unavailable` | 已授权 HTTPS reference 的 transport 无法完成 | 检查 allowlist、网络与远端可用性；不要把它解释为 schema violation |
+| `engine-unavailable` | schema engine 或内部 settlement 无法形成可信完整结果 | 检查 package/runtime 状态，并保留已接受的 Records 供诊断 |
+| `execution-cancelled` | invocation signal 在可观察工作边界取消本 Check | 检查调用方取消原因，不把结果解释为 clean validation |
+
+任一 `unavailable` 分支都不提供 final data；此前已经接受的 issue Records 继续保留。
+
+通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## I/O 与安全边界
+
+默认 `offline` mode 的 network request 数为零。`allowlisted` HTTPS source 以精确 origin 与 path prefix 定义
+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
+assertion plugin；`$async`、`$dynamicRef` 与 `$recursiveRef` 在 schema 位置形成 compile issue。JSON instance 中同名的普通
+property 不受该限制。需要独立检查 JSON document integrity 时，可以另外运行
+[`jsonValidation`](json-validation.md)；它不是本 Check 的隐式 prerequisite。

package/docs/checks/json-validation.md

@@ -0,0 +1,133 @@
+# `jsonValidation`
+
+返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
+
+## 用途
+
+本页说明 `jsonValidation` 的 options、terminal effects 与安全边界。该 Check 严格验证自己选择且以小写
+`.json` 结尾的文档，并报告 syntax error、duplicate key 与 incomplete document。`jsonValidation(options?)` 补齐默认值并
+返回可直接放入 Project Definition `checks` 的普通 Check。
+
+## 参数与默认配置
+
+```ts
+{
+  files: {
+    source: "filesystem",
+    include: ["**/*.json"],
+    exclude: defaultProjectFileSelection.exclude
+  },
+  maximumBytes: 1_048_576
+}
+```
+
+上面的代码块是无参调用物化后的完整 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。
+
+### 定制 authoring options
+
+下面只把输入限制到 `config/**`；constructor 保留默认 source、exclude 与 `maximumBytes`：
+
+```ts
+import { jsonValidation } from "@zxyycom/vibe-check";
+
+const configJsonValidation = jsonValidation({
+  files: { include: ["config/**/*.json"] }
+});
+```
+
+## 工作原理
+
+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。
+
+## 效果与结果
+
+`invalidFileCount === 0` 时 outcome 为 `passed`；`invalidFileCount > 0` 时 outcome 为 `failed`。正常 final data 恰为：
+
+```ts
+{
+  scannedFileCount: number,
+  validFileCount: number,
+  invalidFileCount: number,
+  issueCount: number,
+  rejectedInputCount: number
+}
+```
+
+其中 `scannedFileCount = validFileCount + invalidFileCount`，
+`issueCount = invalidFileCount + rejectedInputCount`。只有 `invalidFileCount > 0` 使 Check failed；仅有 rejected input 时
+outcome 是带 warning 的 `passed`。每个 invalid file 最多形成一条 Record；Record ID 是 project-root-relative path，data
+恰为：
+
+```ts
+{
+  path: string,
+  reason: "too-large" | "bom" | "invalid-utf8" | "invalid-json" | "duplicate-key"
+}
+```
+
+`reason` 表示 strict-document boundary 观察到的第一项文档问题；Record 不包含 JSON 内容、key、pointer、parser message
+或 stack。
+
+每个 rejected selected path 产生一条 ID 为 `/input-rejected/<path>` 的 Record：
+
+```ts
+{
+  blocking: false,
+  kind: "input-rejected",
+  path: string,
+  reason: "unsupported-file-type"
+}
+```
+
+`failed` outcome 携带 `invalid-json-documents` error message，并引导调用方按 path / reason 检查 Records。由本 Check 结算的
+`unavailable` 使用对应 `reason.code` 提供可操作 error message；存在 rejected input 时另附一条汇总数量的
+`input-rejected` warning，逐路径事实仍只在 Records 中。无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseJsonValidationData(value)` 验证 final data。两者返回
+`JsonValidationFinalData`；Record 与原因可分别用 `JsonValidationRecordData`、`JsonValidationRecordReason` 和
+`JsonValidationUnavailableCode` 标注，authoring / resolved options types 是 `JsonValidationOptions` 与
+`ResolvedJsonValidationOptions`。parser 验证字段、非负安全整数以及计数等式，不匹配时抛出 `TypeError`。
+
+## `not-applicable` 与 `unavailable`
+
+selected path 数量为零时结算为 `not-applicable / no-eligible-input`。selected 非空但全部 rejected 时，以带 final data、
+Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 只使用以下值：
+
+| `reason.code` | 触发边界 | 调用方检查项 |
+| --- | --- | --- |
+| `invalid-options` | constructor 返回后形成的 replacement options 不是完整 closed resolved shape | 重新调用 `jsonValidation(options)`，或恢复完整 `files` 与 `maximumBytes` |
+| `scan-input-unavailable` | 所选 filesystem 或 git-worktree 无法形成候选集合 | 检查 project root、目录权限或 Git worktree 状态 |
+| `document-unavailable` | 某个已选 JSON 文件无法完成受限读取 | 检查文件是否仍存在、是否可读，以及运行期间是否被替换 |
+| `execution-cancelled` | invocation signal 在可观察工作边界取消本 Check | 检查调用方取消原因，不把结果解释为 clean validation |
+
+后续文件导致 `unavailable` 时，分类阶段的 rejected-input Records 与先前已接受的 invalid-file Records 均保留，但本 Check
+不提供 final data；对应 rejection warning 也随 terminal error message 一起保留。通用 preflight 语法见
+[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## I/O 与安全边界
+
+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 评估字段与结构时使用
+[`jsonSchemaValidation`](json-schema-validation.md)。

package/docs/checks/maintenance-reminders.md

@@ -0,0 +1,158 @@
+# `maintenanceReminders`
+
+返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
+
+## 用途
+
+本页说明 `maintenanceReminders` 的输入、terminal effects 与安全边界。`maintenanceReminders(entries)` 创建一个固定
+ID 为 `maintenance-reminders` 的 Check，用 Git first-parent history 提醒定期复核维护事项。
+
+## 参数与默认配置
+
+构造函数接收以下 `entries`；它不接受 Git executable override：
+
+```ts
+ReadonlyArray<{
+  id: string,
+  baseCommit: string,
+  limits: {
+    commits?: number,
+    changedLines?: number
+  },
+  message: string,
+  mode?: "advisory" | "enforcing"
+}>
+```
+
+- `id` 在本次构造中唯一，并使用小写短横线命名，例如 `documentation-review`。
+- `baseCommit` 是最近一次真实复核对应的完整 40 或 64 位十六进制 commit ID。Product 不会自动推进它。
+- `limits` 至少提供一个字段；`commits` 与 `changedLines` 都必须是正安全整数，实际值**严格超过**上限时才到期。
+- `message` 是到期或不可测量时展示的非空人读正文。
+- `mode` 省略时为 `advisory`；`enforcing` 使到期或不可测量的条目令所属 Check 失败。
+
+constructor 把输入固定为完整 options `{ entries, git: { executable: "git" } }`。所属 Check 的 preflight 在任何 Check
+execution 开始前验证 unknown、sparse、duplicate 或 malformed entries；失败时当前 Check 以
+`unavailable / invalid-options` 结算。
+
+## 工作原理
+
+measurement source 是从 `baseCommit` 到 `HEAD` 的 committed first-parent history 与 Git `numstat`。commit count 不包含
+基线自身；changed lines 是每个后续 commit 相对其 first parent 的 additions + deletions，binary 行数按零计。workspace 与
+staging area 不参与。维护者完成真实复核后，把 `baseCommit` 推进到新的复核基线。
+
+## 效果与结果
+
+该 Check 正常完成时返回 `{ entries }`，并按作者顺序保存以下 discriminated entry assessments。package root 导出的
+`MaintenanceReminderAssessment` 与 `MaintenanceRemindersFinalData` 对应以下 shape：
+
+```ts
+type EntryAssessment =
+  | Readonly<{
+      id: string;
+      mode: "advisory" | "enforcing";
+      assessment: "clear" | "due";
+      baseCommit: string;
+      headCommit: string;
+      commitCount: number;
+      changedLines: number;
+      exceeded: readonly ("commits" | "changed-lines")[];
+    }>
+  | Readonly<{
+      id: string;
+      mode: "advisory" | "enforcing";
+      assessment: "unavailable";
+      baseCommit: string;
+      headCommit: string | null;
+      commitCount: null;
+      changedLines: null;
+      exceeded: readonly [];
+      reason:
+        | "head-unavailable"
+        | "head-invalid"
+        | "first-parent-history-unavailable"
+        | "first-parent-history-invalid"
+        | "base-commit-unavailable"
+        | "base-not-first-parent-ancestor"
+        | "numstat-unavailable"
+        | "numstat-invalid";
+    }>;
+
+type FinalData = Readonly<{ entries: readonly EntryAssessment[] }>;
+```
+
+| 条目评估 | `advisory`（默认） | `enforcing` |
+| --- | --- | --- |
+| `clear` | 无 message，不贡献失败。 | 无 message，不贡献失败。 |
+| `due` | 附加 warning，不贡献失败。 | 附加 error，并令所属 Check 失败。 |
+| `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。
+
+启用 machine publication 时，entries 只作为一项普通 `maintenance-reminders` Check 的 final data；entry 不形成独立
+machine row，terminal messages 也不进入 machine files。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMaintenanceRemindersData(value)` 验证 final data。parser
+验证每个 discriminated assessment、commit ID、唯一 reminder ID、计数、`exceeded` 与 reason 不变量，并返回
+`MaintenanceRemindersFinalData`；不匹配时抛出 `TypeError`。输入与不可用分支还可分别使用 `MaintenanceReminder`、
+`MaintenanceReminderOptions`、`MaintenanceReminderUnavailableReason` 与 `MaintenanceRemindersUnavailableCode` 标注。
+
+## `not-applicable` 与 `unavailable`
+
+该 Check 没有 `not-applicable` 分支；空 entries 返回 `passed` 与 `{ entries: [] }`，不产生 messages 或 Records。
+
+Git/历史测量的普通失败会保留完整 final data，并把受影响条目标记为 `assessment: "unavailable"`；后续条目仍继续评估：
+
+| entry `reason` | 含义与处理方式 |
+| --- | --- |
+| `head-unavailable` | 无法执行或读取 `HEAD`；检查 Git command 与 repository 状态。 |
+| `head-invalid` | `HEAD` output 不是完整 commit ID；检查 Git wrapper 或 repository object。 |
+| `first-parent-history-unavailable` | 无法读取 `HEAD` 的 first-parent history；检查 Git command 与 history。 |
+| `first-parent-history-invalid` | history 为空、包含非法 ID 或没有从 `HEAD` 开始；检查 Git wrapper 或 repository object。 |
+| `base-commit-unavailable` | 本 entry 的 `baseCommit` 无法解析；换成 repository 中存在的完整 commit ID。 |
+| `base-not-first-parent-ancestor` | 基线不在 `HEAD` 的 first-parent 链上；选择该链中的真实复核 commit。 |
+| `numstat-unavailable` | 无法读取某个 commit 的 `numstat`；检查 Git command 与 repository object。 |
+| `numstat-invalid` | `numstat` 无法安全解析或累计；检查 Git wrapper output。 |
+
+只有以下 whole-Check 边界结算为 `unavailable` 且不提供 final data：
+
+| `reason.code` | 触发边界 |
+| --- | --- |
+| `invalid-options` | constructor 接收的 entries，或之后通过普通对象组合形成的完整 options，未通过 closed policy 校验。 |
+| `execution-cancelled` | invocation signal 在可观察工作边界取消本 Check。 |
+| `maintenance-reminders-internal-failure` | Product 无法形成完整、有序的评估数组。 |
+
+每个 whole-Check `unavailable` 都携带与 `reason.code` 相同 code 的 error message，并指出应恢复 options、检查取消原因或
+检查 package/runtime integrity。entry-level `unavailable` 仍按上一节保留 final data 与项目编写的提醒正文。
+
+通用 preflight 语法见 [options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## I/O 与安全边界
+
+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 转为调用级阻断，
+由 `RunControls.checkAggregation` policy 决定。

package/docs/checks/markdown-link-validation.md

@@ -0,0 +1,192 @@
+# `markdownLinkValidation`
+
+返回 [README 的随包 Check 概览](../../README.md#随包提供的-check)。
+
+## 用途
+
+本页说明 `markdownLinkValidation` 的 options、terminal effects 与安全边界。该 Check 离线验证 selected Markdown
+sources 中的本机链接、图片目标与标题锚点。`markdownLinkValidation(options?)` 补齐默认值并返回可直接放入 Project
+Definition `checks` 的普通 Check。
+
+## 参数与默认配置
+
+```ts
+{
+  files: {
+    source: "filesystem",
+    include: ["**/*.[mM][dD]", "**/*.[mM][aA][rR][kK][dD][oO][wW][nN]"],
+    exclude: defaultProjectFileSelection.exclude
+  },
+  findingPolicy: "non-blocking",
+  requireExistingTargets: true,
+  validateSameDocumentAnchors: true,
+  validateCrossDocumentAnchors: true,
+  rootExternalTargetMode: "report",
+  requireNonEmptyDirectories: false,
+  limits: {
+    maxMarkdownBytes: 1_048_576,
+    maxOccurrences: 10_000,
+    maxTargetReads: 1_000
+  }
+}
+```
+
+上面的代码块是无参调用物化后的完整 resolved options；`exclude` 表示 constructor detached-copy 了 package root 公开
+`defaultProjectFileSelection.exclude` 的全部条目，不是调用方必须复制的输入。所有顶层 authoring fields 都可省略，
+`files` 与 `limits` 内的字段也可分别省略。显式 `include` / `exclude` 数组是完整替换值；显式宽泛 include 选中的非 Markdown
+path 会产生拒绝 Finding，而不是被静默过滤。
+
+- `files` 定义 Markdown source selection；source 可选 `filesystem` 或 `git-worktree`，selected path 必须命中
+  `include` 且不能命中 `exclude`。filesystem 不解释 `.gitignore`；git-worktree 使用已跟踪文件和未被 Git 标准忽略
+  规则排除的未跟踪文件。其中 extension 大小写不敏感的 `.md` / `.markdown` 成为 sources，direct targets 仅用于
+  resolution；来源不可用时 Check 结算为 `unavailable`，不会切换到另一来源。
+- `findingPolicy` 为 `blocking | non-blocking`，默认 `non-blocking`。它只结算本 Check 的 normal local-reference
+  findings：`blocking` 使 finding outcome 为 `failed`，`non-blocking` 保留相同的 Records、计数与 final data，但以
+  `passed` outcome 和 warning message 提示；它不会改写 Project Run、aggregation 或 Gate outcome。
+- `requireExistingTargets` 控制缺失 direct local target 是否是 finding。
+- `validateSameDocumentAnchors` / `validateCrossDocumentAnchors` 分别控制当前文档与直接 Markdown target 的 heading
+  lookup。
+- `rootExternalTargetMode` 为 `ignore | report | validate`；只有显式 `validate` 才授权 bounded root-external target I/O。
+- `requireNonEmptyDirectories` 启用时最多读取 direct directory 的一个 entry，不递归遍历。
+- `limits` 限制单文档 bytes、全部 semantic occurrences 与 direct target reads；constructor 会补齐该 branch 中省略的
+  fields。`maxMarkdownBytes` 不得超过 `16_777_216`，`maxOccurrences` 不得超过 `100_000`，
+  `maxTargetReads` 不得超过 `10_000`。
+
+### 定制 authoring options
+
+下面只扫描 `docs/**`、排除 `docs/fixtures/**`、忽略 project root 外目标，并保留其它 defaults：
+
+```ts
+import { defaultProjectFileSelection, markdownLinkValidation } from "@zxyycom/vibe-check";
+
+const documentationLinks = markdownLinkValidation({
+  files: {
+    ...defaultProjectFileSelection,
+    exclude: [...defaultProjectFileSelection.exclude, "docs/fixtures/**"],
+    include: ["docs/**/*.md", "docs/**/*.markdown"]
+  },
+  rootExternalTargetMode: "ignore"
+});
+```
+
+## 工作原理
+
+Check 验证 options，收集 Markdown source paths，每份 source decode / parse 一次，再处理 supported inline、
+reference 与 autolink occurrences。完整 selected paths 先按 `.md` / `.markdown` suffix 分为 accepted/rejected，每个
+rejected path 产生 supplemental Record，只有 accepted path 成为 source。target file、directory 与 GitHub-priority heading
+anchor 按上面 policy 做 bounded validation；每个 link finding 产生另一种 supplemental Record。direct target 可以参与当前
+occurrence validation，source discovery 始终由 `files` selection 决定。
+
+受支持 occurrence 包含 inline link/image、已定义的 full/collapsed/shortcut reference、explicit autolink 和选定的 GFM
+autolink literal。YAML front matter、code/fenced code、HTML attribute、普通 prose URL 与 undefined reference 不进入本
+Check 的 occurrence 集合。HTTP(S)、`mailto:` 与其它非本地 target 只分类后停止，不产生 remote reachability 结论。
+
+## 效果与结果
+
+没有 normal link finding 时 outcome 为 `passed`；有 normal link finding 时，`findingPolicy: "blocking"` 为 `failed`，
+`findingPolicy: "non-blocking"` 为 `passed`。input rejection 固定 non-blocking，不受该 policy 影响。两种 finding policy 都
+保留相同的 final data 与每 finding 一条 Record；blocking link finding 附带 `invalid-local-links` error message，
+non-blocking link finding 附带同 code 的 warning message。正常 final data 恰为：
+
+```ts
+{
+  sourceFileCount: number,
+  occurrenceCount: number,
+  targetReadCount: number,
+  findingCount: number,
+  rejectedInputCount: number
+}
+```
+
+`occurrenceCount` 包含所有 parser-semantic occurrences，包括没有进入 local target validation 的项；
+`targetReadCount` 统计进入 direct endpoint validation 的 occurrence；`findingCount - rejectedInputCount` 是 normal link
+finding 数量并且不超过 `occurrenceCount`。每个 normal link finding 恰好形成一条 Record，data 恰为：
+
+```ts
+{
+  occurrenceKind: "link" | "image",
+  range: {
+    start: { line: number, column: number },
+    end: { line: number, column: number }
+  },
+  reason:
+    | "missing-target"
+    | "target-outside-project-root"
+    | "empty-directory"
+    | "anchor-on-directory"
+    | "anchor-target-not-markdown"
+    | "missing-anchor"
+    | "unsupported-target-type",
+  sourcePath: string,
+  target:
+    | { kind: "same-document" | "project-file" | "project-directory" | "project-path", path: string, fragment: string | null }
+    | { kind: "outside-project-root" }
+}
+```
+
+`range` 使用 one-based、end-exclusive 的 decoded UTF-16 line/column。`outside-project-root` descriptor 不携带 target
+path 或 fragment。
+
+每个 rejected selected path 产生一条 ID 为 `/input-rejected/<path>` 的 Record：
+
+```ts
+{
+  blocking: false,
+  kind: "input-rejected",
+  path: string,
+  reason: "unsupported-file-type"
+}
+```
+
+blocking finding 的 `failed` outcome 携带 `invalid-local-links` error message；non-blocking finding 的 `passed` outcome
+携带同 code 的 warning message；两者都引导调用方检查 Records 的 source range、target 与 reason。存在 rejected input 时
+另附一条 `input-rejected` warning，只汇总数量而不省略逐路径 Record。由本 Check 结算的 `unavailable` 使用对应
+`reason.code` 提供可操作 error message；无 Finding 的 `passed` 与 `not-applicable` 不合成人为提示。
+
+用返回 Check 的 `check.parseData(value)` 或 package root 的 `parseMarkdownLinkValidationData(value)` 验证 final data。两者返回
+`MarkdownLinkValidationFinalData`；Records 与原因可用 `MarkdownLinkValidationRecordData`、
+`MarkdownLinkFindingReason` 和 `MarkdownLinkValidationUnavailableReason` 标注，authoring / resolved options types 是
+`MarkdownLinkValidationOptions` 与 `ResolvedMarkdownLinkValidationOptions`。parser 验证字段与计数上界，不匹配时抛出
+`TypeError`。
+
+## `not-applicable` 与 `unavailable`
+
+selected path 数量为零时结算为 `not-applicable / no-eligible-input`。selected 非空但全部 rejected 时，不解析 source，直接以
+带 final data、Records 与 warning 的 `passed` 结算。`unavailable.reason.code` 使用以下受控值：
+
+| `reason.code` | 触发边界与调用方检查项 |
+| --- | --- |
+| `invalid-options` | constructor 返回后形成的 replacement options 不是完整 closed resolved shape；重新调用 `markdownLinkValidation(options)` 或恢复完整字段。 |
+| `project-root-unavailable` | project root 无法 canonicalize；检查路径存在性与访问权限。 |
+| `source-unavailable` | source collection、读取、decode 或 containment 失败；检查 source 与 file-selection 来源。 |
+| `source-too-large` | 某个 selected Markdown source 超过 `maxMarkdownBytes`。 |
+| `markdown-parse-failed` | selected source 无法形成完整 parser facts。 |
+| `invalid-local-destination` | local destination 无法按受支持的 path/URI grammar 安全解析。 |
+| `target-unavailable` | target containment probe、I/O、decode、parse 或 directory read 失败；Markdown anchor target 超过 `maxMarkdownBytes` 也属于此分支。 |
+| `occurrence-limit-exceeded` | semantic occurrence 总数超过 `maxOccurrences`。 |
+| `target-read-limit-exceeded` | direct endpoint validation work 超过 `maxTargetReads`。 |
+| `cancelled` | invocation signal 取消本 Check；不要把结果解释为 clean validation。 |
+
+这些边界不发布 partial link-finding Records，也不提供 final data；若 selected classification 已完成，已发布的
+rejected-input Records 与对应 warning 仍保留。通用 preflight 语法见
+[options preflight 与 execution](../api-mechanics.md#options-preflight-与-execution)。
+
+## I/O 与安全边界
+
+source I/O scope 只包含通过 `.md` / `.markdown` eligibility 的 accepted paths；rejected path 不读取内容。resolver I/O scope
+是本地 filesystem，HTTP、DNS、TLS 与 redirect request 数为零。默认 `report` mode 对 root-external
+target 形成 finding，显式 `validate` mode 授权 bounded read。published facts 排除 raw external absolute path、target
+bytes 与 remote credentials。
+
+## 最小用法
+
+```ts
+import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
+const result = await run(defineConfig({ checks: [markdownLinkValidation()] }));
+```
+
+## 适用边界
+
+该 Check 只评估本机 target 与 heading-anchor integrity，不评估 remote URL reachability 或 HTML attribute links。项目需要
+这些能力时，应另外提供明确拥有网络或 HTML parsing policy 的 Check；当前 `markdownLinkValidation` 不会隐式扩展到这些
+输入。