@zxyycom/vibe-check 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zxyycom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Vibe Check
+
+Vibe Check 是面向 Bun 项目的 TypeScript 质量检查库。你可以直接使用随包提供的代码、JSON、Schema、Markdown 和维护检查，也可以把项目自己的规则写成 Check，然后在项目脚本、测试或 CI 中获得结构化结果。
+
+所有公开能力都从 `@zxyycom/vibe-check` package root 导入。Vibe Check 不要求额外的配置文件，也不提供 CLI：检查内容、组合方式和运行时机都由你的 TypeScript 代码决定。
+
+## 安装
+
+```sh
+npm install @zxyycom/vibe-check
+```
+
+npm 负责安装 package；应用代码和质量脚本使用 **Bun `>=1.3.14`** 执行。安装完成后，可以用 `bun run <file>` 运行下面的示例。
+
+## 自定义 Check 快速开始
+
+下面的 `quality.ts` 展示一条完整的最小路径：定义 bundle 大小规则、运行它，并确认 Check 通过。为使示例能够独立运行，`actualBytes` 使用固定输入；接入项目时，把这部分替换为项目真实的测量逻辑即可。
+
+- `defineCheck(...)` 定义一项检查，以及通过或失败时要返回的数据。
+- `defineConfig(...)` 把一项或多项 Check 组成可重复运行的 Project Definition。
+- `run(...)` 执行 Definition，并返回本次运行的结果。
+
+示例保留默认的进度输出，但关闭 machine publication，因此第一次运行不会写入 `run.json` 或 `records.ndjson`：
+
+```ts
+import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+
+const bundleSize = defineCheck({
+  checkId: "bundle-size",
+  displayName: "Bundle size",
+  execution() {
+    const actualBytes = 82_000;
+    const maximumBytes = 100_000;
+    const data = {
+      actualBytes,
+      maximumBytes
+    };
+    return actualBytes <= maximumBytes
+      ? { status: "passed", data }
+      : { status: "failed", data };
+  }
+});
+
+const definition = defineConfig({
+  checks: [bundleSize],
+  outputs: {
+    machinePublication: { enabled: false }
+  }
+});
+
+const result = await run(definition);
+if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+const outcome = result.snapshot.checks.find(
+  ({ checkId }) => checkId === bundleSize.checkId
+)?.outcome;
+if (outcome?.status !== "passed" || outcome.data.actualBytes !== 82_000) {
+  throw new Error("Bundle-size Check did not produce the expected result");
+}
+```
+
+运行它：
+
+```sh
+bun run quality.ts
+```
+
+`RunResult.kind === "completed"` 表示这次 Run 已经完整结算，不等于其中每项 Check 都通过。示例继续读取 `bundle-size` 的 `outcome.status`，并在结果不符合预期时让脚本失败。
+
+## 随包提供的 Check
+
+如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execution`。除 `maintenanceReminders(entries)` 必须接收提醒条目外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
+
+| 你想检查什么 | 使用的导出 | 运行前提 |
+| --- | --- | --- |
+| 重复代码 | [`duplicateDetection(options?)`](./docs/checks/duplicate-detection.md) | package 使用随安装依赖提供的兼容 jscpd v5。 |
+| 文件代码行指标 | [`fileMetrics(options?)`](./docs/checks/file-metrics.md) | 环境中有兼容 SCC 3.7.0 输出契约的 `scc` command。 |
+| 函数规模、复杂度和参数数量 | [`functionMetrics(options?)`](./docs/checks/function-metrics.md) | 环境中有兼容 Lizard 1.23 输出契约的 `lizard` command。 |
+| JSON 语法和输入范围 | [`jsonValidation(options?)`](./docs/checks/json-validation.md) | 只读取本地文件，不执行 command 或网络请求。 |
+| JSON 与 Schema 的匹配关系 | [`jsonSchemaValidation(options?)`](./docs/checks/json-schema-validation.md) | 默认离线；只有显式允许的 HTTPS source 才会触发网络请求。 |
+| 本地 Markdown 链接与锚点 | [`markdownLinkValidation(options?)`](./docs/checks/markdown-link-validation.md) | 只读取 policy 允许的本地路径，不执行 command 或网络请求。 |
+| 基于 Git 历史的维护提醒 | [`maintenanceReminders(entries)`](./docs/checks/maintenance-reminders.md) | 项目根目录是 Git repository，且环境可以执行 `git`。 |
+
+`duplicateDetection`、`fileMetrics`、`functionMetrics` 和 `markdownLinkValidation` 默认把普通 Finding 作为 non-blocking 警告保留下来；需要让 Finding 直接使 Check 失败时，在对应 options 中设置 `findingPolicy: "blocking"`。文件选择、阈值、外部工具和具体结果字段以各 Check 指南为准。
+
+## 自定义 Check API
+
+只使用随包 Check 时，可以跳过本节。需要表达项目自己的规则时，通常只需要定义 Check、组成 Definition、运行并读取结果；preflight、依赖调度、waiver 对账、聚合和取消等进阶能力放在[深入 API 机制](./docs/api-mechanics.md)中。
+
+### 定义 Check
+
+`defineCheck(value)` 接受一个普通 Check object，并保留 `checkId`、options 和 final data 的 TypeScript inference。常用字段如下：
+
+| 字段 | 用途 |
+| --- | --- |
+| `checkId` | 在同一 Definition 中唯一的稳定标识；用于查找 outcome、Record、message 和 duration。 |
+| `displayName` | 进度和人读结果中显示的名称。 |
+| `execution(context)` | 执行检查并返回一个 terminal outcome。省略时，当前节点只用于组织子 `checks`。 |
+| `options` | 当前 Check 的配置；Run 会把准备后的只读副本交给 `context.options`。 |
+| `checks` | 可选的子 Check 列表，用于组织一组相关规则。 |
+
+`execution` 可以同步返回，也可以返回 `Promise`。它通过 `context` 读取当前 options、project root、flags、已声明依赖的数据、取消 signal，并可用 `records.report(...)` 保存不决定终态的补充事实。
+
+| 返回状态 | 何时使用 |
+| --- | --- |
+| `passed` | 检查完成且满足规则；同时返回主要 final `data`。 |
+| `failed` | 检查完成但不满足规则；同时返回主要 final `data`。 |
+| `not-applicable` | 当前输入没有适用的工作；可以附带 reason。 |
+| `unavailable` | 无法形成可信结果；必须附带 reason。 |
+
+final `data` 和 supplemental Record 使用 object-shaped canonical JSON。Check 可以附带有序的人读 `messages`，但通用 API 不保证每个结果都有 message。
+
+### 组成 Project Definition
+
+`defineConfig({ checks, ... })` 组成可重复运行的 Project Definition，并补齐未声明的默认值。最常调整的默认项是：
+
+| 配置 | 默认值 | 效果 |
+| --- | --- | --- |
+| `outputs.progressRendering.enabled` | `true` | 在终端呈现 Check 生命周期与汇总。 |
+| `outputs.machinePublication.enabled` | `true` | 把 `run.json` 和 `records.ndjson` 写入 `artifacts/vibe-check`。 |
+| `outputs.diagnosticLogging.enabled` | `false` | 需要排障时写入 invocation-specific 日志。 |
+| `scheduler.maxParallel` | `4` | 限制最外层 Check 并行数。 |
+
+`outputs` 和 `scheduler` 都可以只覆盖需要改变的 nested field；同一份 Definition 可以安全地传给多次 `run(...)`。
+
+### 运行并读取结果
+
+`run(definition, controls?)` 执行一次独立 invocation。常用 controls 包括 `projectRoot`、`flags`、`signal` 和仅对本次运行生效的 `outputs` overrides。
+
+读取结果时分两层判断：
+
+1. 先读取 `RunResult.kind`，确认 invocation 是完整结算、配置错误、规划失败、输出失败、执行失败还是被取消。
+2. 对有 snapshot 的结果，按 `checkId` 查找 `snapshot.checks[].outcome`，再处理 `passed`、`failed`、`not-applicable` 或 `unavailable`。
+
+合法运行中，即使某项 Check 返回 `failed`，Run 仍可能是 `kind: "completed"`。如果 CI 需要因质量 Finding 退出非零状态，调用方必须像快速开始那样显式判断目标 outcome，或配置并读取 invocation-level aggregation。
+
+## 输出与进阶用法
+
+- [深入 API 机制](./docs/api-mechanics.md)说明 options preflight、依赖、组合、aggregation、finding waiver、cancellation 和 output failure 边界。
+- [机器输出契约](./docs/output.md)说明 `run.json`、`records.ndjson` 和对应 schemas；只有需要把结果交给其他工具时才需要读取它。
+- 精确 overload、泛型推断和字段 JSDoc 以安装包中的 `types/**.d.ts` 为准。
+
+## 包内结构与调试
+
+业务代码始终从 `@zxyycom/vibe-check` 导入。安装包中的 `index.mjs` 是公开 runtime entry，`types/**.d.ts` 提供 TypeScript declarations；source maps、`src/**.ts` 和可读的 `dist/esm/**.mjs` 用于堆栈定位与实现检查，不是额外的 public import path。
+
+安装包还包含机器输出文档、v4 run / Record schemas 和一组完整 artifact example，便于需要消费机器结果的工具核对实际 bytes。
+
+## 分发与兼容范围
+
+npm 只负责分发和安装 package；受支持的产品 host 是 **Bun `>=1.3.14`**。通过 npm 安装不表示 Node.js runtime 已受支持。
+
+当前 public contract 只有 `@zxyycom/vibe-check` package root 的程序化 API。CLI、`bin`、plugin API、CommonJS/browser entry 和 subpath imports 都不在支持范围内。
+
+`0.0.x` patch 之间不承诺 package-level 兼容。项目应提交 lockfile，并在升级前检查对应版本的变更。Vibe Check 使用 MIT License，完整许可文本随 package 一起安装。

package/dist/esm/check/check.mjs

@@ -0,0 +1,5 @@
+export { inherit, isInheritedCheckCollection, snapshotInheritedCheckCollection } from "./inherited-collection.mjs";
+export function defineCheck(value) {
+    return value;
+}
+//# sourceMappingURL=check.mjs.map

package/dist/esm/check/check.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.mjs","sourceRoot":"","sources":["../../../src/check/check.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,OAAO,EACP,0BAA0B,EAC1B,gCAAgC,EACjC,MAAM,2BAA2B,CAAC;AAuenC,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { CanonicalJsonObject, CanonicalJsonValue } from \"../data-boundary/canonical-json.ts\";\nimport type { InheritableCheckCollection } from \"./inherited-collection.ts\";\n\nexport {\n  inherit,\n  isInheritedCheckCollection,\n  snapshotInheritedCheckCollection\n} from \"./inherited-collection.ts\";\nexport type {\n  InheritCheckCollectionInput,\n  InheritableCheckCollection,\n  InheritedCheckCollection\n} from \"./inherited-collection.ts\";\n\n/** Check 无法给出 final data 时返回的受控 reason code。 */\nexport type CheckReason = Readonly<{\n  /** 由 owning Check 定义、供调用方诊断的稳定 code。 */\n  readonly code: string;\n}>;\n\n/** `not-applicable` Check result 的可选 reason。 */\nexport type CheckNotApplicableReason = CheckReason;\n/** author callback 明确返回 `unavailable` 时必须提供的 reason。 */\nexport type CheckDeclaredUnavailableReason = CheckReason;\n\n/** `unavailable` Check outcome 的 reason；可列出导致当前 Check 不可用的上游 Check。 */\nexport type CheckUnavailableReason = Readonly<{\n  /** 由当前 Check 或 Product 边界给出的受控原因。 */\n  readonly code: string;\n  /** 仅在上游关系有助于定位时给出的相关 Check IDs。 */\n  readonly checkIds?: readonly string[];\n}>;\n\n/** 终端 Check message 的 presentation severity。 */\nexport type CheckMessageLevel = \"info\" | \"warning\" | \"error\";\n\n/** 由 Check author 附加到 terminal result 的补充消息。 */\nexport interface CheckMessage {\n  /** 人读 presentation 使用的 severity。 */\n  readonly level: CheckMessageLevel;\n  /** owning Check namespace 内的稳定 message code。 */\n  readonly code: string;\n  /** 非空消息正文；Product 保留 author 提供的字符串。 */\n  readonly message: string;\n}\n\n/** 可附加到每个 {@link CheckResult} branch 的有序 terminal messages。 */\nexport interface CheckResultMessages {\n  /** 省略、`undefined` 或空数组都表示没有 supplemental messages。 */\n  readonly messages?: readonly CheckMessage[];\n}\n\n/** 已结算 Check 在人读 progress 中的可见性。 */\nexport type CheckVisibility = \"always\" | \"attention\";\n\n/**\n * Check callback 的 terminal result。\n *\n * @typeParam FinalData - `passed` 或 `failed` 时保留为 canonical final data 的业务对象。\n * @remarks `not-applicable` 与 `unavailable` 不携带 final data；普通 callback、Record 或取消失败由\n * Product 转换为 `unavailable`，而不是抛出为 Run 的成功结果。\n */\nexport type CheckResult<FinalData extends object = object> = Readonly<\n  (\n    | {\n        /** Check 已产生通过的 final data。 */\n        readonly status: \"passed\";\n        /** 此 Check 的主要终态事实。 */\n        readonly data: FinalData;\n      }\n    | {\n        /** Check 已产生失败的 final data。 */\n        readonly status: \"failed\";\n        /** 此 Check 的主要终态事实。 */\n        readonly data: FinalData;\n      }\n    | {\n        /** Check 在当前 invocation 中不适用。 */\n        readonly status: \"not-applicable\";\n        /** 不适用的可选受控原因。 */\n        readonly reason?: CheckNotApplicableReason;\n      }\n    | {\n        /** Check 不能提供 terminal data。 */\n        readonly status: \"unavailable\";\n        /** 不可用的受控原因。 */\n        readonly reason: CheckDeclaredUnavailableReason;\n      }\n  ) &\n    CheckResultMessages\n>;\n\n/** 已 materialize 到 Core snapshot 的 Check terminal outcome。 */\nexport type CheckOutcome = Readonly<\n  | {\n      /** 已 materialize 的通过 outcome。 */\n      readonly status: \"passed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的失败 outcome。 */\n      readonly status: \"failed\";\n      /** 已 canonicalize 的 primary final fact。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** 已 materialize 的不适用 outcome。 */\n      readonly status: \"not-applicable\";\n      /** 不适用的可选受控原因。 */\n      readonly reason?: CheckNotApplicableReason;\n    }\n  | {\n      /** 已 materialize 的不可用 outcome。 */\n      readonly status: \"unavailable\";\n      /** 包含相关 upstream Check IDs 的受控原因。 */\n      readonly reason: CheckUnavailableReason;\n    }\n>;\n\n/** 将 callback options 转为不可变观察值的递归 utility type。 */\nexport type DeepReadonly<T> = T extends string | number | boolean | null\n  ? T\n  : T extends readonly (infer Item)[]\n    ? readonly DeepReadonly<Item>[]\n    : T extends object\n      ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> }\n      : never;\n\n/** callback 写入 supplemental Record 时的 Check-local identity。 */\ninterface RecordIdentityInput {\n  /** 在当前 Check 内唯一的 Record ID。 */\n  readonly id: string;\n}\n\n/** callback 写入 supplemental Records 的 Product-owned reporter。 */\ninterface CheckRecordReporter {\n  /** 记录一个补充事实；它不决定 Check 的 terminal status。 */\n  report(identity: RecordIdentityInput, data: object): void;\n}\n\n/** 读取已声明 dependency final data 时的失败原因。 */\nexport type DependencyReadError = Readonly<\n  | {\n      /** 当前 Check 未声明所请求的 dependency ID。 */\n      readonly code: \"dependency-not-declared\";\n      /** 被拒绝的 dependency ID。 */\n      readonly checkId: string;\n    }\n  | {\n      /** 已声明 upstream 没有可读取的 final data。 */\n      readonly code: \"upstream-data-unavailable\";\n      /** 没有 final data 的 direct dependency ID。 */\n      readonly checkId: string;\n      /** 阻止 readback 的 upstream terminal status。 */\n      readonly status: \"not-applicable\" | \"unavailable\";\n    }\n>;\n\n/** {@link CheckDependencies.get} 的受控 readback 结果。 */\nexport type DependencyReadResult = Readonly<\n  | {\n      /** 成功读取 direct dependency final data。 */\n      readonly ok: true;\n      /** 被读取的 direct dependency ID。 */\n      readonly checkId: string;\n      /** upstream 已结算为 `passed` 或 `failed` 的 status。 */\n      readonly status: \"passed\" | \"failed\";\n      /** 已与原对象脱离的上游依赖终态数据。 */\n      readonly data: CanonicalJsonObject;\n    }\n  | {\n      /** dependency data 不可读取。 */\n      readonly ok: false;\n      /** 失败的授权或 upstream-data reason。 */\n      readonly error: DependencyReadError;\n    }\n>;\n\n/** 当前 Check 的已规范化直接 dependencies 的 data reader。 */\nexport interface CheckDependencies {\n  /**\n   * 读取一个直接 dependency 的 canonical final data。\n   *\n   * @returns 已声明且为 `passed`/`failed` 的 dependency 返回其 data；未声明或没有 final data 时返回\n   * `ok: false`，不会授权 transitive dependency。\n   */\n  get(checkId: string): DependencyReadResult;\n}\n\n/** callback 可读取的、由 Product 规范化的项目上下文。 */\nexport interface CheckProjectContext {\n  /** 本次 Run 使用的绝对项目根目录。 */\n  readonly root: string;\n  /** 已去重、排序的 caller-supplied flags。 */\n  readonly flags: readonly string[];\n}\n\n/**\n * Check callback 收到的 Product-owned execution context。\n *\n * @typeParam Options - 此 Check preflight 后传给 execution 的 options shape。\n */\nexport interface CheckExecutionContext<Options extends object> {\n  /** 读取当前 Check 的已声明 direct dependencies。 */\n  readonly dependencies: CheckDependencies;\n  /** 深度只读、canonical 的 invocation-local prepared Check options。 */\n  readonly options: DeepReadonly<Options>;\n  /** 已规范化的项目根与 flags。 */\n  readonly project: CheckProjectContext;\n  /** 写入 supplemental Records 的 reporter。 */\n  readonly records: CheckRecordReporter;\n  /** 本次 invocation 的 cancellation signal。 */\n  readonly signal: AbortSignal;\n}\n\n/**\n * 一个 Check 的 callback signature。\n *\n * @typeParam Options - callback 从 context 读取的 prepared options shape。\n * @returns terminal Check result 或其 Promise。\n */\nexport type CheckExecution<Options extends object = object> = (\n  this: void,\n  context: CheckExecutionContext<Options>\n) => CheckResult | Promise<CheckResult>;\n\n/**\n * 在 Check execution 前，可选地为本次 invocation 准备 options。\n *\n * @remarks `signal` 与同一次 callback execution 使用同一个 cancellation signal；实现应在可等待工作中\n * 协作退出，而不是留下悬挂 work。bivariant callback 保持具体 options Check 可进入普通递归 Check\n * collection；Product 仍只会用该 Check 自己的 authored options 调用它。精确结果见\n * {@link CheckPreflightResult}。\n */\nexport type CheckPreflight<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = {\n  bivarianceHack(\n    this: void,\n    options: DeepReadonly<AuthoredOptions>,\n    signal: AbortSignal\n  ): CheckPreflightResult<PreparedOptions> | Promise<CheckPreflightResult<PreparedOptions>>;\n}[\"bivarianceHack\"];\n\n/**\n * Check-owned preflight 的判别结果。\n *\n * `failure/block` 不允许 fallback，直接以 owning reason 结算为 unavailable；`failure/continue` 必须给出\n * fallback 并继续 execution。两种进入 execution 的值都只属于本次 invocation，Product canonicalize/freeze\n * 后传递，不会改写 Definition 中 authored options。两个 failure 分支都必须给出 reason；continue reason\n * 是 Check-owned diagnostic identity，当前不会单独 materialize 为 outcome，调用方通过 messages 与后续\n * outcome 观察结果；block 物理上不含 fallback 字段。\n */\nexport type CheckPreflightResult<PreparedOptions extends object = object> = Readonly<\n  | {\n      readonly status: \"success\";\n      readonly preparedOptions: PreparedOptions;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"block\";\n      readonly reason: CheckDeclaredUnavailableReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n  | {\n      readonly status: \"failure\";\n      readonly action: \"continue\";\n      readonly fallback: PreparedOptions;\n      readonly reason: CheckReason;\n      readonly messages?: readonly CheckMessage[];\n    }\n>;\n\n/**\n * 普通递归 Check authoring value 的共享字段。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。\n * @remarks 该值可以同时有 `execution` 和 `checks`；只有 executable node 产生 final Check fact。\n */\ninterface CheckBase<AuthoredOptions extends object, PreparedOptions extends object> {\n  /** 在 Definition 内唯一的 stable Check ID。 */\n  readonly checkId: string;\n  /** 人读 progress 与 output 使用的非空名称。 */\n  readonly displayName: string;\n  /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */\n  readonly options?: AuthoredOptions;\n  /** 可执行节点的 callback；省略时此节点只承载递归 children。 */\n  execution?(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult | Promise<CheckResult>;\n  /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */\n  readonly checks?: readonly Check[];\n  /** 直接 prerequisite Check IDs，或对父 dependency collection 的显式 edit。 */\n  readonly dependsOn?: InheritableCheckCollection<string>;\n  /** 此 Check 及其 descendants 的最大并行预算。 */\n  readonly maxParallel?: number;\n  /** 共享资源名称，或对父 mutex collection 的显式 edit。 */\n  readonly mutex?: InheritableCheckCollection<string>;\n  /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */\n  readonly visibility?: CheckVisibility;\n}\n\n/**\n * 判断两个 options shape 是否互相可赋值；互相可赋值时 execution 不需要 preparation 转换。\n */\ntype HasSameOptionsShape<AuthoredOptions extends object, PreparedOptions extends object> = [\n  AuthoredOptions\n] extends [PreparedOptions]\n  ? [PreparedOptions] extends [AuthoredOptions]\n    ? true\n    : false\n  : false;\n\n/** Prepared shape 不同时，preflight 是建立安全转换的必填边界。 */\ntype CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends object> =\n  HasSameOptionsShape<AuthoredOptions, PreparedOptions> extends true\n    ? Readonly<{ readonly preflight?: CheckPreflight<AuthoredOptions, PreparedOptions> }>\n    : Readonly<{ readonly preflight: CheckPreflight<AuthoredOptions, PreparedOptions> }>;\n\n/**\n * Project Definition 中的普通递归 Check authoring value。\n *\n * @typeParam AuthoredOptions - Definition 中的 declarative options shape。\n * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。\n * @remarks Definition 只闭合 authored JSON options；preflight 在同一 Run 的所有 execution 前作为全局\n * barrier 执行。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以省略。它不进入\n * declarative fingerprint 或 machine output。\n */\nexport type Check<\n  AuthoredOptions extends object = object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckBase<AuthoredOptions, PreparedOptions> &\n  CheckPreflightField<AuthoredOptions, PreparedOptions>;\n\nexport type EmptyCheckOptions = Readonly<Record<never, never>>;\n\n/**\n * 防止宽泛的 parser 标注擦除 `PromiseLike`。canonical `then` field 可以保存 JSON data，\n * 但不能保存使该值成为 thenable 的 callable。\n */\ntype NonThenableData = Readonly<{ readonly then?: CanonicalJsonValue }>;\n\n/**\n * 将 canonical dependency data 还原为 provider final-data shape 的同步 parser。\n *\n * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。\n * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。\n */\nexport type CheckDataParser<FinalData extends object = object> = (\n  this: void,\n  data: CanonicalJsonObject\n) => FinalData & NonThenableData;\n\ntype CheckAuthoringBase<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object\n> = Omit<CheckBase<AuthoredOptions, PreparedOptions>, \"checkId\" | \"execution\" | \"options\"> &\n  CheckPreflightField<AuthoredOptions, PreparedOptions> &\n  Readonly<{ readonly checkId: Id }>;\n\ninterface OrdinaryCheckFields<PreparedOptions extends object> {\n  execution?(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult | Promise<CheckResult>;\n  readonly parseData?: never;\n}\n\nexport type CheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  OrdinaryCheckFields<PreparedOptions> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type CheckWithoutOptions<Id extends string> = CheckAuthoringBase<\n  Id,\n  EmptyCheckOptions,\n  EmptyCheckOptions\n> &\n  OrdinaryCheckFields<EmptyCheckOptions> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\ninterface TypedCheckFields<PreparedOptions extends object, Parser extends CheckDataParser> {\n  /**\n   * 将 canonical runtime data 还原为 provider data。\n   *\n   * 启发式边界：同版本且受信任的 provider 若由测试保证 data shape，可仅将它实现为\n   * identity/type anchor。这不验证 JavaScript 或基于 cast 的 producer、历史或跨版本 artifact，\n   * 也不验证不受信任输入。\n   */\n  readonly parseData: Parser;\n\n  execution(\n    this: void,\n    context: CheckExecutionContext<PreparedOptions>\n  ): CheckResult<NoInfer<ReturnType<Parser>>> | Promise<CheckResult<NoInfer<ReturnType<Parser>>>>;\n}\n\nexport type TypedCheckWithOptions<\n  Id extends string,\n  AuthoredOptions extends object,\n  Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n> = CheckAuthoringBase<Id, AuthoredOptions, PreparedOptions> &\n  TypedCheckFields<PreparedOptions, Parser> &\n  Readonly<{\n    readonly options: AuthoredOptions;\n  }>;\n\nexport type TypedCheckWithoutOptions<\n  Id extends string,\n  Parser extends CheckDataParser\n> = CheckAuthoringBase<Id, EmptyCheckOptions, EmptyCheckOptions> &\n  TypedCheckFields<EmptyCheckOptions, Parser> &\n  Readonly<{\n    readonly options?: never;\n  }>;\n\n/**\n * 定义一个 Check，同时保留 literal `checkId`、options 与 typed-provider parser 的 inference。\n *\n * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。\n * @example 定义带 options、Records 与 messages 的自定义 Check\n * ```ts\n * function hasValidLicensePolicyOptions(options: object): boolean {\n *   const denied: unknown = Reflect.get(options, \"denied\");\n *   return (\n *     Object.keys(options).length === 1 &&\n *     Object.hasOwn(options, \"denied\") &&\n *     Array.isArray(denied) &&\n *     denied.every((license) => typeof license === \"string\")\n *   );\n * }\n *\n * const licensePolicy = defineCheck({\n *   checkId: \"license-policy\",\n *   displayName: \"License policy\",\n *   options: { denied: [\"GPL-3.0-only\"] },\n *   preflight(options) {\n *     return hasValidLicensePolicyOptions(options)\n *       ? { status: \"success\", preparedOptions: options }\n *       : { status: \"failure\", action: \"block\", reason: { code: \"invalid-options\" } };\n *   },\n *   visibility: \"attention\",\n *   execution({ options, records, signal }) {\n *     if (signal.aborted) return { status: \"unavailable\", reason: { code: \"cancelled\" } };\n *\n *     const deniedCount = options.denied.length;\n *     if (deniedCount > 0) {\n *       records.report({ id: \"denied-license\" }, { count: deniedCount });\n *       return {\n *         status: \"failed\",\n *         data: { deniedCount },\n *         messages: [{ level: \"warning\", code: \"denied-license\", message: \"Denied licenses found.\" }]\n *       };\n *     }\n *     return { status: \"passed\", data: { deniedCount: 0 } };\n *   }\n * });\n * ```\n */\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: CheckWithOptions<Id, AuthoredOptions, PreparedOptions>\n): CheckWithOptions<Id, AuthoredOptions, PreparedOptions>;\nexport function defineCheck<const Id extends string>(\n  value: CheckWithoutOptions<Id>\n): CheckWithoutOptions<Id>;\nexport function defineCheck<\n  const Id extends string,\n  AuthoredOptions extends object,\n  const Parser extends CheckDataParser,\n  PreparedOptions extends object = AuthoredOptions\n>(\n  value: TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>\n): TypedCheckWithOptions<Id, AuthoredOptions, Parser, PreparedOptions>;\nexport function defineCheck<const Id extends string, const Parser extends CheckDataParser>(\n  value: TypedCheckWithoutOptions<Id, Parser>\n): TypedCheckWithoutOptions<Id, Parser>;\nexport function defineCheck(value: Check): Check {\n  return value;\n}\n"]}

package/dist/esm/check/descriptor-validation.mjs

@@ -0,0 +1,37 @@
+import { snapshotClosedRecord } from "../data-boundary/closed-values.mjs";
+/** Validates the minimal Check identity shared by Definition authoring and final facts. */
+export function validateCheckDescriptor(value) {
+    const definition = snapshotClosedRecord(value);
+    if (definition === undefined)
+        return invalid("$", "Check definition must be a closed object");
+    if (!hasExactKeys(definition, ["checkId", "displayName"])) {
+        return invalid("$", "Check definition has unsupported fields");
+    }
+    if (typeof definition.checkId !== "string" ||
+        definition.checkId.length === 0 ||
+        typeof definition.displayName !== "string") {
+        return invalid("$", "Check definition identity is invalid");
+    }
+    if (definition.displayName.length === 0) {
+        return invalid("$.displayName", "Check displayName is empty");
+    }
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze({ checkId: definition.checkId, displayName: definition.displayName })
+    });
+}
+function hasExactKeys(value, keys) {
+    return (Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)));
+}
+function invalid(path, message) {
+    const issue = Object.freeze({
+        path,
+        code: "invalid-value",
+        message
+    });
+    const issues = [
+        issue
+    ];
+    return Object.freeze({ ok: false, issues: Object.freeze(issues) });
+}
+//# sourceMappingURL=descriptor-validation.mjs.map

package/dist/esm/check/descriptor-validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor-validation.mjs","sourceRoot":"","sources":["../../../src/check/descriptor-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAoBzE,2FAA2F;AAC3F,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,GAAG,EAAE,0CAA0C,CAAC,CAAC;IAC9F,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO,OAAO,CAAC,GAAG,EAAE,yCAAyC,CAAC,CAAC;IACjE,CAAC;IACD,IACE,OAAO,UAAU,CAAC,OAAO,KAAK,QAAQ;QACtC,UAAU,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAC/B,OAAO,UAAU,CAAC,WAAW,KAAK,QAAQ,EAC1C,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,EAAE,sCAAsC,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,UAAU,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,OAAO,CAAC,eAAe,EAAE,4BAA4B,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC;KAC3F,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,KAAwC,EAAE,IAAuB;IACrF,OAAO,CACL,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAC5F,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,OAAe;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QAC1B,IAAI;QACJ,IAAI,EAAE,eAAe;QACrB,OAAO;KACR,CAA0C,CAAC;IAC5C,MAAM,MAAM,GAAmF;QAC7F,KAAK;KACN,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC","sourcesContent":["import { snapshotClosedRecord } from \"../data-boundary/closed-values.ts\";\nimport type { CheckDescriptor } from \"./descriptor.ts\";\n\nexport interface CheckDescriptorValidationIssue {\n  readonly path: string;\n  readonly code: \"invalid-value\";\n  readonly message: string;\n}\n\nexport type CheckDescriptorValidationResult = Readonly<\n  | { readonly ok: true; readonly value: CheckDescriptor }\n  | {\n      readonly ok: false;\n      readonly issues: readonly [\n        CheckDescriptorValidationIssue,\n        ...CheckDescriptorValidationIssue[]\n      ];\n    }\n>;\n\n/** Validates the minimal Check identity shared by Definition authoring and final facts. */\nexport function validateCheckDescriptor(value: unknown): CheckDescriptorValidationResult {\n  const definition = snapshotClosedRecord(value);\n  if (definition === undefined) return invalid(\"$\", \"Check definition must be a closed object\");\n  if (!hasExactKeys(definition, [\"checkId\", \"displayName\"])) {\n    return invalid(\"$\", \"Check definition has unsupported fields\");\n  }\n  if (\n    typeof definition.checkId !== \"string\" ||\n    definition.checkId.length === 0 ||\n    typeof definition.displayName !== \"string\"\n  ) {\n    return invalid(\"$\", \"Check definition identity is invalid\");\n  }\n  if (definition.displayName.length === 0) {\n    return invalid(\"$.displayName\", \"Check displayName is empty\");\n  }\n  return Object.freeze({\n    ok: true,\n    value: Object.freeze({ checkId: definition.checkId, displayName: definition.displayName })\n  });\n}\n\nfunction hasExactKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean {\n  return (\n    Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))\n  );\n}\n\nfunction invalid(path: string, message: string): CheckDescriptorValidationResult {\n  const issue = Object.freeze({\n    path,\n    code: \"invalid-value\",\n    message\n  }) satisfies CheckDescriptorValidationIssue;\n  const issues: readonly [CheckDescriptorValidationIssue, ...CheckDescriptorValidationIssue[]] = [\n    issue\n  ];\n  return Object.freeze({ ok: false, issues: Object.freeze(issues) });\n}\n"]}

package/dist/esm/check/descriptor.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=descriptor.mjs.map

package/dist/esm/check/descriptor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.mjs","sourceRoot":"","sources":["../../../src/check/descriptor.ts"],"names":[],"mappings":"","sourcesContent":["/** The declaration identity retained for one executable Check. */\nexport interface CheckDescriptor {\n  readonly checkId: string;\n  readonly displayName: string;\n}\n"]}

package/dist/esm/check/inherited-collection.mjs

@@ -0,0 +1,62 @@
+const INHERITED_CHECK_COLLECTION = Symbol("vibe-check.inherited-check-collection");
+const inheritedCollections = new WeakSet();
+/**
+ * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ *
+ * @typeParam T - 要添加或移除的 collection item 类型。
+ * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。
+ * @returns 只有此函数创建的值会被 Definition validation 识别为 inherited collection。
+ */
+export function inherit(value) {
+    const result = { ...value, [INHERITED_CHECK_COLLECTION]: true };
+    Object.defineProperty(result, INHERITED_CHECK_COLLECTION, { enumerable: false });
+    inheritedCollections.add(result);
+    return result;
+}
+export function isInheritedCheckCollection(value) {
+    return typeof value === "object" && value !== null && inheritedCollections.has(value);
+}
+/** Copies the trusted marker while preserving the authoring data's closed shape. */
+export function snapshotInheritedCheckCollection(value) {
+    try {
+        if (!hasPlainObjectPrototype(value))
+            return undefined;
+        const snapshot = {};
+        let hasMarker = false;
+        for (const key of Reflect.ownKeys(value)) {
+            const entry = snapshotInheritedCollectionEntry(snapshot, key, Object.getOwnPropertyDescriptor(value, key));
+            if (entry === "invalid")
+                return undefined;
+            if (entry === "marker")
+                hasMarker = true;
+        }
+        return hasMarker ? Object.freeze(snapshot) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasPlainObjectPrototype(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function snapshotInheritedCollectionEntry(snapshot, key, descriptor) {
+    if (!isDataDescriptor(descriptor))
+        return "invalid";
+    if (key === INHERITED_CHECK_COLLECTION) {
+        return descriptor.enumerable || descriptor.value !== true ? "invalid" : "marker";
+    }
+    if (typeof key !== "string" || descriptor.enumerable !== true)
+        return "invalid";
+    Object.defineProperty(snapshot, key, {
+        configurable: true,
+        enumerable: true,
+        value: descriptor.value,
+        writable: true
+    });
+    return "data";
+}
+function isDataDescriptor(descriptor) {
+    return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined;
+}
+//# sourceMappingURL=inherited-collection.mjs.map

package/dist/esm/check/inherited-collection.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inherited-collection.mjs","sourceRoot":"","sources":["../../../src/check/inherited-collection.ts"],"names":[],"mappings":"AAAA,MAAM,0BAA0B,GAAkB,MAAM,CAAC,uCAAuC,CAAC,CAAC;AAyBlG,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAAE,CAAC;AAI3C;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAI,KAAqC;IAC9D,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,0BAA0B,CAAC,EAAE,IAAa,EAAE,CAAC;IACzE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,0BAA0B,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gCAAgC,CAC9C,KAAwC;IAExC,IAAI,CAAC;QACH,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACtD,MAAM,QAAQ,GAA4B,EAAE,CAAC;QAC7C,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,gCAAgC,CAC5C,QAAQ,EACR,GAAG,EACH,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAC5C,CAAC;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,IAAI,KAAK,KAAK,QAAQ;gBAAE,SAAS,GAAG,IAAI,CAAC;QAC3C,CAAC;QACD,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa;IAC5C,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,SAAS,gCAAgC,CACvC,QAAiC,EACjC,GAAgB,EAChB,UAA0C;IAE1C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,GAAG,KAAK,0BAA0B,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;QACnC,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA0C;IAE1C,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC;AAClG,CAAC","sourcesContent":["const INHERITED_CHECK_COLLECTION: unique symbol = Symbol(\"vibe-check.inherited-check-collection\");\n\n/** 使用 {@link inherit} 对父 Check 的 string collection 做显式增删的输入。 */\nexport type InheritCheckCollectionInput<T> = Readonly<\n  | { readonly add: readonly T[]; readonly remove?: readonly T[] }\n  | { readonly add?: readonly T[]; readonly remove: readonly T[] }\n>;\n\n/**\n * 由 {@link inherit} 创建、带有不可伪造 marker 的 collection edit。\n *\n * @remarks Definition validation 不接受看起来相同的 plain object。\n */\nexport type InheritedCheckCollection<T> = InheritCheckCollectionInput<T> &\n  Readonly<{\n    readonly [INHERITED_CHECK_COLLECTION]: true;\n  }>;\n\n/**\n * 可以直接替换父 collection 的数组，或由 {@link inherit} 表示的显式 edit。\n *\n * @typeParam T - collection item 类型。\n */\nexport type InheritableCheckCollection<T> = readonly T[] | InheritedCheckCollection<T>;\n\nconst inheritedCollections = new WeakSet();\n\ntype InheritedCollectionEntry = \"data\" | \"invalid\" | \"marker\";\n\n/**\n * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。\n *\n * @typeParam T - 要添加或移除的 collection item 类型。\n * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。\n * @returns 只有此函数创建的值会被 Definition validation 识别为 inherited collection。\n */\nexport function inherit<T>(value: InheritCheckCollectionInput<T>): InheritedCheckCollection<T> {\n  const result = { ...value, [INHERITED_CHECK_COLLECTION]: true as const };\n  Object.defineProperty(result, INHERITED_CHECK_COLLECTION, { enumerable: false });\n  inheritedCollections.add(result);\n  return result;\n}\n\nexport function isInheritedCheckCollection(\n  value: unknown\n): value is InheritedCheckCollection<unknown> {\n  return typeof value === \"object\" && value !== null && inheritedCollections.has(value);\n}\n\n/** Copies the trusted marker while preserving the authoring data's closed shape. */\nexport function snapshotInheritedCheckCollection(\n  value: InheritedCheckCollection<unknown>\n): Readonly<Record<string, unknown>> | undefined {\n  try {\n    if (!hasPlainObjectPrototype(value)) return undefined;\n    const snapshot: Record<string, unknown> = {};\n    let hasMarker = false;\n    for (const key of Reflect.ownKeys(value)) {\n      const entry = snapshotInheritedCollectionEntry(\n        snapshot,\n        key,\n        Object.getOwnPropertyDescriptor(value, key)\n      );\n      if (entry === \"invalid\") return undefined;\n      if (entry === \"marker\") hasMarker = true;\n    }\n    return hasMarker ? Object.freeze(snapshot) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction hasPlainObjectPrototype(value: object): boolean {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction snapshotInheritedCollectionEntry(\n  snapshot: Record<string, unknown>,\n  key: PropertyKey,\n  descriptor: PropertyDescriptor | undefined\n): InheritedCollectionEntry {\n  if (!isDataDescriptor(descriptor)) return \"invalid\";\n  if (key === INHERITED_CHECK_COLLECTION) {\n    return descriptor.enumerable || descriptor.value !== true ? \"invalid\" : \"marker\";\n  }\n  if (typeof key !== \"string\" || descriptor.enumerable !== true) return \"invalid\";\n  Object.defineProperty(snapshot, key, {\n    configurable: true,\n    enumerable: true,\n    value: descriptor.value,\n    writable: true\n  });\n  return \"data\";\n}\n\nfunction isDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is PropertyDescriptor {\n  return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined;\n}\n"]}

package/dist/esm/check/options-snapshot.mjs

@@ -0,0 +1,75 @@
+import { snapshotClosedArray, snapshotClosedRecord } from "../data-boundary/closed-values.mjs";
+/** Copies a closed JSON object without retaining untyped authoring input. */
+export function snapshotJsonObject(value) {
+    const snapshot = snapshotJson(value, new Set());
+    return isJsonObject(snapshot) ? snapshot : undefined;
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function snapshotJson(value, ancestors) {
+    const primitive = snapshotJsonPrimitive(value);
+    if (primitive !== undefined || value === null)
+        return primitive;
+    if (typeof value !== "object")
+        return undefined;
+    if (ancestors.has(value))
+        return undefined;
+    const items = snapshotClosedArray(value);
+    if (items !== undefined)
+        return snapshotJsonArray(value, items, ancestors);
+    const data = snapshotClosedRecord(value);
+    if (data === undefined)
+        return undefined;
+    return snapshotJsonRecord(value, data, ancestors);
+}
+function snapshotJsonPrimitive(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    return value;
+}
+function snapshotJsonArray(value, items, ancestors) {
+    ancestors.add(value);
+    try {
+        const snapshot = [];
+        for (const item of items) {
+            const parsed = snapshotJson(item, ancestors);
+            if (parsed === undefined)
+                return undefined;
+            snapshot.push(parsed);
+        }
+        return Object.freeze(snapshot);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function snapshotJsonRecord(value, data, ancestors) {
+    ancestors.add(value);
+    try {
+        // Assignment to an ordinary object treats an own `__proto__` JSON key as
+        // a prototype mutation. Define the data property so every closed JSON key
+        // remains data and the detached snapshot retains its ordinary prototype.
+        const snapshot = {};
+        for (const [key, item] of Object.entries(data)) {
+            const parsed = snapshotJson(item, ancestors);
+            if (parsed === undefined)
+                return undefined;
+            Object.defineProperty(snapshot, key, {
+                configurable: true,
+                enumerable: true,
+                value: parsed,
+                writable: true
+            });
+        }
+        return Object.freeze(snapshot);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+//# sourceMappingURL=options-snapshot.mjs.map

package/dist/esm/check/options-snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options-snapshot.mjs","sourceRoot":"","sources":["../../../src/check/options-snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import { snapshotClosedArray, snapshotClosedRecord } from \"../data-boundary/closed-values.ts\";\n\ntype JsonSnapshot = object | readonly unknown[] | string | number | boolean | null;\n\n/** Copies a closed JSON object without retaining untyped authoring input. */\nexport function snapshotJsonObject(value: unknown): object | undefined {\n  const snapshot = snapshotJson(value, new Set<object>());\n  return isJsonObject(snapshot) ? snapshot : undefined;\n}\n\nfunction isJsonObject(value: JsonSnapshot | undefined): value is object {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction snapshotJson(value: unknown, ancestors: Set<object>): JsonSnapshot | undefined {\n  const primitive = snapshotJsonPrimitive(value);\n  if (primitive !== undefined || value === null) return primitive;\n  if (typeof value !== \"object\") return undefined;\n  if (ancestors.has(value)) return undefined;\n\n  const items = snapshotClosedArray(value);\n  if (items !== undefined) return snapshotJsonArray(value, items, ancestors);\n\n  const data = snapshotClosedRecord(value);\n  if (data === undefined) return undefined;\n  return snapshotJsonRecord(value, data, ancestors);\n}\n\nfunction snapshotJsonPrimitive(value: unknown): string | number | boolean | null | undefined {\n  if (value === null) return null;\n  if (typeof value === \"string\" || typeof value === \"boolean\") return value;\n  if (typeof value !== \"number\" || !Number.isFinite(value)) return undefined;\n  return value;\n}\n\nfunction snapshotJsonArray(\n  value: object,\n  items: readonly unknown[],\n  ancestors: Set<object>\n): readonly JsonSnapshot[] | undefined {\n  ancestors.add(value);\n  try {\n    const snapshot: JsonSnapshot[] = [];\n    for (const item of items) {\n      const parsed = snapshotJson(item, ancestors);\n      if (parsed === undefined) return undefined;\n      snapshot.push(parsed);\n    }\n    return Object.freeze(snapshot);\n  } finally {\n    ancestors.delete(value);\n  }\n}\n\nfunction snapshotJsonRecord(\n  value: object,\n  data: Readonly<Record<string, unknown>>,\n  ancestors: Set<object>\n): object | undefined {\n  ancestors.add(value);\n  try {\n    // Assignment to an ordinary object treats an own `__proto__` JSON key as\n    // a prototype mutation. Define the data property so every closed JSON key\n    // remains data and the detached snapshot retains its ordinary prototype.\n    const snapshot: Record<string, unknown> = {};\n    for (const [key, item] of Object.entries(data)) {\n      const parsed = snapshotJson(item, ancestors);\n      if (parsed === undefined) return undefined;\n      Object.defineProperty(snapshot, key, {\n        configurable: true,\n        enumerable: true,\n        value: parsed,\n        writable: true\n      });\n    }\n    return Object.freeze(snapshot);\n  } finally {\n    ancestors.delete(value);\n  }\n}\n"]}