npm - @zxyycom/vibe-check - Versions diffs - 0.0.1 → 0.0.2 - Mend

@zxyycom/vibe-check 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (950) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Vibe Check
-Vibe Check 是面向 Bun 项目的 TypeScript 质量检查库。你可以直接使用随包提供的代码、JSON、Schema、Markdown 和维护检查，也可以把项目自己的规则写成 Check，然后在项目脚本、测试或 CI 中获得结构化结果。
+Vibe Check 是通用 TypeScript 质量门禁工具，提供可组合 Check、类型安全 API 和结构化结果。你可以直接使用随包提供的代码、JSON、Schema、Markdown 和维护检查，也可以把项目自己的规则写成 Check，然后在项目脚本、测试或 CI 中运行它们。
 所有公开能力都从 `@zxyycom/vibe-check` package root 导入。Vibe Check 不要求额外的配置文件，也不提供 CLI：检查内容、组合方式和运行时机都由你的 TypeScript 代码决定。
@@ -10,16 +10,31 @@ Vibe Check 是面向 Bun 项目的 TypeScript 质量检查库。你可以直接
 npm install @zxyycom/vibe-check
 ```
-npm 负责安装 package；应用代码和质量脚本使用 **Bun `>=1.3.14`** 执行。安装完成后，可以用 `bun run <file>` 运行下面的示例。
+npm 负责安装 package；应用代码和质量脚本的最低运行要求是 **Node `>=24.18`**。安装完成后，可以用 `node <file>` 运行下面的示例。
+升级前查看随包的[变更日志](./docs/changelog.md)，确认对应版本的变化与必要调整。
+## 随包提供的 Check
+如果项目需要的是常见质量检查，可以先从以下函数开始，而不必自己实现 `execution`。除 `maintenanceReminders(entries)` 与 `secretDetection({ files })` 有必填输入外，其余函数都可以无参调用；每份指南都包含最小用法、options、默认值、结果和安全边界。
+| 你想检查什么 | 使用的导出 | 额外环境准备 |
+| --- | --- | --- |
+| 重复代码 | [`duplicateDetection(options?)`](./docs/checks/duplicate-detection.md) | 无需另装分析器。 |
+| 文件代码行指标 | [`fileMetrics(options?)`](./docs/checks/file-metrics.md) | 环境中有兼容精确 SCC 4.0.0 输出契约的 `scc` command。 |
+| 函数规模、复杂度、最大嵌套和参数数量 | [`functionMetrics(options?)`](./docs/checks/function-metrics.md) | 无需另装分析器。 |
+| JSON 语法和输入范围 | [`jsonValidation(options?)`](./docs/checks/json-validation.md) | 无。 |
+| JSON 与 Schema 的匹配关系 | [`jsonSchemaValidation(options?)`](./docs/checks/json-schema-validation.md) | 使用远程 Schema 时，需显式允许对应 HTTPS source 并具备网络访问条件。 |
+| 本地 Markdown 链接与锚点 | [`markdownLinkValidation(options?)`](./docs/checks/markdown-link-validation.md) | 无。 |
+| 基于 Git 历史的维护提醒 | [`maintenanceReminders(entries)`](./docs/checks/maintenance-reminders.md) | 项目根目录是 Git repository，且环境可以执行 `git`。 |
+| 高置信 PEM private key | [`secretDetection({ files })`](./docs/checks/secret-detection.md) | 无需另装分析器。 |
+`duplicateDetection`、`fileMetrics`、`functionMetrics` 和 `markdownLinkValidation` 默认把普通 Finding 作为 non-blocking 警告保留下来；需要让 Finding 直接使 Check 失败时，在对应 options 中设置 `findingPolicy: "blocking"`。文件选择、阈值、外部工具和具体结果字段以各 Check 指南为准。
 ## 自定义 Check 快速开始
 下面的 `quality.ts` 展示一条完整的最小路径：定义 bundle 大小规则、运行它，并确认 Check 通过。为使示例能够独立运行，`actualBytes` 使用固定输入；接入项目时，把这部分替换为项目真实的测量逻辑即可。
-- `defineCheck(...)` 定义一项检查，以及通过或失败时要返回的数据。
-- `defineConfig(...)` 把一项或多项 Check 组成可重复运行的 Project Definition。
-- `run(...)` 执行 Definition，并返回本次运行的结果。
 示例保留默认的进度输出，但关闭 machine publication，因此第一次运行不会写入 `run.json` 或 `records.ndjson`：
 ```ts
@@ -61,94 +76,52 @@ if (outcome?.status !== "passed" || outcome.data.actualBytes !== 82_000) {
 运行它：
 ```sh
-bun run quality.ts
+node 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
+`defineConfig(...)` 定义可复用的 Checks、options、依赖、scheduler 和默认 outputs；`run(definition, controls?)` 的第二个参数只设置本次根目录、flags、取消、产物与日志目标、output overrides 和显式 aggregation。Controls 不能替换 Check 或 scheduler；字段位置和覆盖规则见 [API 机制](./docs/api-mechanics.md#参数应该放在哪里)。
-`defineCheck(value)` 接受一个普通 Check object，并保留 `checkId`、options 和 final data 的 TypeScript inference。常用字段如下：
+默认最多并行运行四个 Check，显示进度并把 machine files 写入 `artifacts/vibe-check`；diagnostic logging 默认关闭。上例显式关闭 machine publication。配置方法见[输出指南](./docs/guides/run-outputs.md)与[调度指南](./docs/guides/scheduling.md)。
-| 字段 | 用途 |
-| --- | --- |
-| `checkId` | 在同一 Definition 中唯一的稳定标识；用于查找 outcome、Record、message 和 duration。 |
-| `displayName` | 进度和人读结果中显示的名称。 |
-| `execution(context)` | 执行检查并返回一个 terminal outcome。省略时，当前节点只用于组织子 `checks`。 |
-| `options` | 当前 Check 的配置；Run 会把准备后的只读副本交给 `context.options`。 |
-| `checks` | 可选的子 Check 列表，用于组织一组相关规则。 |
+先判断 `RunResult.kind`；对有 snapshot 的结果，再按 `checkId` 读取 `snapshot.checks[].outcome` 的 `passed`、`failed`、`not-applicable` 或 `unavailable`。`completed` 不代表质量通过：CI 应显式判断目标 outcomes，或配置并读取 [`checkAggregation`](./docs/api-mechanics.md#runcontrols-与-check-aggregation)，再决定退出码。
-`execution` 可以同步返回，也可以返回 `Promise`。它通过 `context` 读取当前 options、project root、flags、已声明依赖的数据、取消 signal，并可用 `records.report(...)` 保存不决定终态的补充事实。
+## 按任务继续阅读
-| 返回状态 | 何时使用 |
-| --- | --- |
-| `passed` | 检查完成且满足规则；同时返回主要 final `data`。 |
-| `failed` | 检查完成但不满足规则；同时返回主要 final `data`。 |
-| `not-applicable` | 当前输入没有适用的工作；可以附带 reason。 |
-| `unavailable` | 无法形成可信结果；必须附带 reason。 |
+只读当前任务需要的专题；精确 overload、泛型推断和字段 JSDoc 以安装包中的 `types/**.d.ts` 为准。
-final `data` 和 supplemental Record 使用 object-shaped canonical JSON。Check 可以附带有序的人读 `messages`，但通用 API 不保证每个结果都有 message。
+- [API 机制](./docs/api-mechanics.md)：Run 生命周期、组合继承、结果与 aggregation。
+- [选择回调位置](./docs/guides/callbacks.md)：确定执行前、检查中、显示时或结束后的接入点。
+- [自定义 Check](./docs/guides/extending-check-lifecycle.md)：options 准备、callback context、Records 与协作取消。
+- [Check 依赖与类型化数据](./docs/guides/check-dependencies.md)：`dependsOn` / `observes`、读取授权与 provider parser。
+- [Run 输出与诊断](./docs/guides/run-outputs.md)：输出配置、progress、日志与失败处理。
+- [调度 Check](./docs/guides/scheduling.md)：并发资源、准入策略与终态观察。
+- [机器输出契约](./docs/output.md)：供其他工具读取 `run.json`、`records.ndjson` 与 schemas。
-### 组成 Project Definition
+以下可选工具由项目代码或自定义 Check 显式调用：
-`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。
+| 按一份完整 selection 收集项目文件 path | `collectProjectFiles(...)` 在普通项目代码或 custom Check 内返回冻结的 relative path 快照 | [收集项目文件](./docs/guides/collecting-project-files.md) |
+| 按完整语义 key 复用本地 JSON 计算 | `cacheJsonByKey(...)` 在普通项目代码或 Check 内返回一次调用的缓存结果 | [缓存计算结果](./docs/guides/cache-results.md) |
+| 对账完整 Finding 集合与 waiver audit | `reconcileFindingWaivers(...)` 在 Finding 形成后返回 disposition 与 audit | [对账 Finding waiver](./docs/guides/finding-waivers.md) |
+| 生成有限的 Finding 人读摘要 | `presentCheckFindings(...)` 返回 `CheckMessage[]`，由 producing Check 附到自己的 terminal result | [呈现 Check Finding](./docs/guides/presenting-findings.md) |
+| 在不执行 Check 的前提下分析静态 admission 分支 | `createAdmissionGraph(...)` 独立创建 immutable simulation，不需要 `run(...)` 或 custom policy | [模拟 AdmissionGraph](./docs/guides/simulating-admission.md) |
+| 为重复 Run 准备基于本地时长 history 的选择策略 | `createLearnedCriticalPathStrategy(...)` 的返回值接入 `scheduler.admissionPolicy` 的 custom strategy | [learned critical-path strategy](./docs/guides/learned-scheduling.md) |
-读取结果时分两层判断：
-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` 为准。
+各随包 Check 的 `parse…Data` 导出用于解析该 Check 的 final data；完整签名与类型见相应 Check 指南及 installed declarations。
 ## 包内结构与调试
 业务代码始终从 `@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 一起安装。
+`0.0.x` patch 之间不承诺 package-level 兼容。项目应提交 lockfile，并在升级前检查对应版本的变更。
+随包法律材料包括根 `LICENSE` 中的 Vibe Check MIT 文本，以及 `licenses/` 中的分析器翻译归属说明、第三方许可原文与来源记录。npm 依赖作为独立包安装，其许可声明及随附法律材料由各依赖包提供。

package/dist/esm/cache/cache-json-by-key.mjs ADDED Viewed

@@ -0,0 +1,189 @@
+/** caller-keyed canonical JSON cache 的公开存储边界。 */
+import { createHash, randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { canonicalizeJsonObject, canonicalJsonBytes } from "../data-boundary/canonical-data.mjs";
+import { hasExactPlainRecordKeys, snapshotClosedRecord } from "../data-boundary/closed-values.mjs";
+const CACHE_API_VERSION = "caller-keyed-json-v1";
+const CACHE_ENVELOPE_KEYS = ["cacheFormatVersion", "identityDigest", "payload"];
+/**
+ * 按 caller 提供的完整 semantic key 复用本地 canonical JSON object。
+ *
+ * cache hit 不会跳过或重放 Check settlement、Records、messages、duration 或 side effects。读取或写入失败
+ * 只通过返回的 observation 可见；只要 `compute` 与 `parse` 成功，就仍返回本次 computation 的 value。
+ * 不提供依赖发现、默认目录、lock/single-flight、TTL/LRU、cleanup、remote cache 或 tamper protection。
+ */
+export async function cacheJsonByKey(authoredOptions) {
+    const options = parseOptions(authoredOptions);
+    const identityDigest = cacheIdentityDigest(options);
+    const targetPath = join(options.directory, `${identityDigest}.json`);
+    const cached = await readCacheEntry({ identityDigest, parse: options.parse, targetPath });
+    if (cached.hit) {
+        return Object.freeze({
+            read: "hit",
+            source: "cache",
+            value: cached.value,
+            write: "not-attempted"
+        });
+    }
+    const payload = canonicalizeJsonObject(await options.compute());
+    if (payload === undefined) {
+        throw new TypeError("cacheJsonByKey compute must return a canonical JSON object");
+    }
+    const value = parseSynchronously(options.parse, payload, "computed value");
+    const stored = await publishCacheEntry({
+        directory: options.directory,
+        identityDigest,
+        parse: options.parse,
+        payload,
+        targetPath
+    });
+    return Object.freeze({
+        read: cached.read,
+        source: "computed",
+        value,
+        write: stored ? "stored" : "failed"
+    });
+}
+function parseOptions(value) {
+    const record = snapshotClosedRecord(value);
+    if (record === undefined ||
+        !hasExactPlainRecordKeys(record, [
+            "compute",
+            "directory",
+            "key",
+            "namespace",
+            "parse",
+            "version"
+        ])) {
+        throw new TypeError("cacheJsonByKey options must be a closed object");
+    }
+    const { compute, directory, key, namespace, parse, version } = record;
+    if (typeof compute !== "function" || typeof parse !== "function") {
+        throw new TypeError("cacheJsonByKey compute and parse must be functions");
+    }
+    if (typeof directory !== "string" ||
+        directory.length === 0 ||
+        directory.includes("\0") ||
+        !isAbsolute(directory)) {
+        throw new TypeError("cacheJsonByKey directory must be a non-empty absolute path without U+0000");
+    }
+    if (typeof namespace !== "string" || namespace.length === 0) {
+        throw new TypeError("cacheJsonByKey namespace must be a non-empty string");
+    }
+    if (typeof version !== "string" || version.length === 0) {
+        throw new TypeError("cacheJsonByKey version must be a non-empty string");
+    }
+    if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError("cacheJsonByKey key must be a non-empty string");
+    }
+    const typedOptions = {
+        compute: value.compute,
+        directory: value.directory,
+        key: value.key,
+        namespace: value.namespace,
+        parse: value.parse,
+        version: value.version
+    };
+    if (typedOptions.compute !== compute ||
+        typedOptions.directory !== directory ||
+        typedOptions.key !== key ||
+        typedOptions.namespace !== namespace ||
+        typedOptions.parse !== parse ||
+        typedOptions.version !== version) {
+        throw new TypeError("cacheJsonByKey options changed during validation");
+    }
+    return Object.freeze(typedOptions);
+}
+function cacheIdentityDigest(options) {
+    return createHash("sha256")
+        .update(canonicalJsonBytes({
+        cacheApiVersion: CACHE_API_VERSION,
+        key: options.key,
+        namespace: options.namespace,
+        payloadVersion: options.version
+    }))
+        .digest("hex");
+}
+async function readCacheEntry(input) {
+    let source;
+    try {
+        source = await fs.readFile(input.targetPath, "utf8");
+    }
+    catch (error) {
+        return isMissingPath(error)
+            ? Object.freeze({ hit: false, read: "miss" })
+            : Object.freeze({ hit: false, read: "failed" });
+    }
+    try {
+        const envelope = parseEnvelope(JSON.parse(source), input.identityDigest);
+        if (envelope === undefined)
+            return Object.freeze({ hit: false, read: "invalid" });
+        return Object.freeze({
+            hit: true,
+            value: parseSynchronously(input.parse, envelope.payload, "cached payload")
+        });
+    }
+    catch {
+        return Object.freeze({ hit: false, read: "invalid" });
+    }
+}
+function parseEnvelope(value, identityDigest) {
+    const record = snapshotClosedRecord(value);
+    if (record === undefined || !hasExactPlainRecordKeys(record, CACHE_ENVELOPE_KEYS))
+        return undefined;
+    if (record.cacheFormatVersion !== CACHE_API_VERSION || record.identityDigest !== identityDigest) {
+        return undefined;
+    }
+    const payload = canonicalizeJsonObject(record.payload);
+    return payload === undefined ? undefined : Object.freeze({ payload });
+}
+function parseSynchronously(parse, payload, subject) {
+    const value = parse(payload);
+    if (isThenable(value))
+        throw new TypeError(`cacheJsonByKey parse must synchronously return ${subject}`);
+    return value;
+}
+function isThenable(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        typeof value.then === "function");
+}
+async function publishCacheEntry(input) {
+    const temporaryPath = join(input.directory, `.vibe-check-cache-${randomUUID()}.tmp`);
+    try {
+        await fs.mkdir(input.directory, { recursive: true });
+        await fs.writeFile(temporaryPath, JSON.stringify({
+            cacheFormatVersion: CACHE_API_VERSION,
+            identityDigest: input.identityDigest,
+            payload: input.payload
+        }), { encoding: "utf8", flag: "wx" });
+    }
+    catch {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+        return false;
+    }
+    try {
+        await fs.rename(temporaryPath, input.targetPath);
+        return true;
+    }
+    catch (error) {
+        if (isConcurrentTargetConflict(error)) {
+            const concurrent = await readCacheEntry({
+                identityDigest: input.identityDigest,
+                parse: input.parse,
+                targetPath: input.targetPath
+            });
+            await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+            return concurrent.hit;
+        }
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+        return false;
+    }
+}
+function isConcurrentTargetConflict(error) {
+    return (typeof error === "object" && error !== null && error.code === "EEXIST");
+}
+function isMissingPath(error) {
+    return (typeof error === "object" && error !== null && error.code === "ENOENT");
+}
+//# sourceMappingURL=cache-json-by-key.mjs.map

package/dist/esm/cache/cache-json-by-key.mjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"cache-json-by-key.mjs","sourceRoot":"","sources":["../../../src/cache/cache-json-by-key.ts"],"names":[],"mappings":"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","sourcesContent":["/** caller-keyed canonical JSON cache 的公开存储边界。 */\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { promises as fs } from \"node:fs\";\nimport { isAbsolute, join } from \"node:path\";\n\nimport {\n canonicalizeJsonObject,\n canonicalJsonBytes,\n type CanonicalJsonObject\n} from \"../data-boundary/canonical-data.ts\";\nimport { hasExactPlainRecordKeys, snapshotClosedRecord } from \"../data-boundary/closed-values.ts\";\n\nconst CACHE_API_VERSION = \"caller-keyed-json-v1\";\nconst CACHE_ENVELOPE_KEYS = [\"cacheFormatVersion\", \"identityDigest\", \"payload\"] as const;\n\n/**\n * `cacheJsonByKey` 的 caller-owned identity、payload parser 与 computation。\n *\n * `key` 必须覆盖所有会改变 computation 结果的输入、实现、options、toolchain 与声明的外部状态；\n * 不能放入 secret 或低熵敏感值。`directory` 是调用方信任、可自行删除的本地状态空间。\n */\ntype NonThenable<T extends object> = T & Readonly<{ readonly then?: undefined }>;\n\n/** Caller-keyed JSON cache 的 options。 */\nexport interface CacheJsonByKeyOptions<T extends object> {\n /** cache miss、读取失败或 payload 无效时执行的 sync/async computation。 */\n readonly compute: () => unknown;\n /** 调用方信任、可自行清理的 absolute local directory。 */\n readonly directory: string;\n /** 覆盖所有影响 computation 结果的完整 semantic key；不得包含 secret 或低熵敏感值。 */\n readonly key: string;\n /** 调用方为这一类缓存选择的非空 identity namespace。 */\n readonly namespace: string;\n /** 同步验证 cached/computed canonical JSON object，并返回调用方的 typed value。 */\n readonly parse: (value: unknown) => NonThenable<T>;\n /** 调用方控制、在 payload 或 computation contract 改变时更新的非空版本。 */\n readonly version: string;\n}\n\n/** `cacheJsonByKey` 返回的闭合 cache observation 与本次 parser value。 */\nexport type CacheJsonByKeyResult<T extends object> =\n | Readonly<{\n /** 已读取并通过 parser 验证现有 payload。 */\n readonly read: \"hit\";\n /** 本次 value 来自 cache，不调用 `compute`。 */\n readonly source: \"cache\";\n /** `parse` 返回的调用方 typed value。 */\n readonly value: T;\n /** cache hit 不尝试重新写入。 */\n readonly write: \"not-attempted\";\n }>\n | Readonly<{\n /** 没有 entry、读取失败，或已有 payload 未通过 identity/parser 验证。 */\n readonly read: \"failed\" | \"invalid\" | \"miss\";\n /** 本次 value 来自成功的 `compute` 与 `parse`。 */\n readonly source: \"computed\";\n /** `parse` 返回的调用方 typed value。 */\n readonly value: T;\n /** 新 payload 已存储，或存储失败但 typed value 仍可使用。 */\n readonly write: \"failed\" | \"stored\";\n }>;\n\n/**\n * 按 caller 提供的完整 semantic key 复用本地 canonical JSON object。\n *\n * cache hit 不会跳过或重放 Check settlement、Records、messages、duration 或 side effects。读取或写入失败\n * 只通过返回的 observation 可见；只要 `compute` 与 `parse` 成功，就仍返回本次 computation 的 value。\n * 不提供依赖发现、默认目录、lock/single-flight、TTL/LRU、cleanup、remote cache 或 tamper protection。\n */\nexport async function cacheJsonByKey<T extends object>(\n authoredOptions: CacheJsonByKeyOptions<T>\n): Promise<CacheJsonByKeyResult<T>> {\n const options = parseOptions(authoredOptions);\n const identityDigest = cacheIdentityDigest(options);\n const targetPath = join(options.directory, `${identityDigest}.json`);\n const cached = await readCacheEntry({ identityDigest, parse: options.parse, targetPath });\n if (cached.hit) {\n return Object.freeze({\n read: \"hit\",\n source: \"cache\",\n value: cached.value,\n write: \"not-attempted\"\n });\n }\n\n const payload = canonicalizeJsonObject(await options.compute());\n if (payload === undefined) {\n throw new TypeError(\"cacheJsonByKey compute must return a canonical JSON object\");\n }\n const value = parseSynchronously(options.parse, payload, \"computed value\");\n const stored = await publishCacheEntry({\n directory: options.directory,\n identityDigest,\n parse: options.parse,\n payload,\n targetPath\n });\n return Object.freeze({\n read: cached.read,\n source: \"computed\",\n value,\n write: stored ? \"stored\" : \"failed\"\n });\n}\n\ntype ParsedOptions<T extends object> = Readonly<{\n readonly compute: () => unknown;\n readonly directory: string;\n readonly key: string;\n readonly namespace: string;\n readonly parse: (value: unknown) => T;\n readonly version: string;\n}>;\n\nfunction parseOptions<T extends object>(value: CacheJsonByKeyOptions<T>): ParsedOptions<T> {\n const record = snapshotClosedRecord(value);\n if (\n record === undefined ||\n !hasExactPlainRecordKeys(record, [\n \"compute\",\n \"directory\",\n \"key\",\n \"namespace\",\n \"parse\",\n \"version\"\n ])\n ) {\n throw new TypeError(\"cacheJsonByKey options must be a closed object\");\n }\n const { compute, directory, key, namespace, parse, version } = record;\n if (typeof compute !== \"function\" || typeof parse !== \"function\") {\n throw new TypeError(\"cacheJsonByKey compute and parse must be functions\");\n }\n if (\n typeof directory !== \"string\" ||\n directory.length === 0 ||\n directory.includes(\"\\0\") ||\n !isAbsolute(directory)\n ) {\n throw new TypeError(\n \"cacheJsonByKey directory must be a non-empty absolute path without U+0000\"\n );\n }\n if (typeof namespace !== \"string\" || namespace.length === 0) {\n throw new TypeError(\"cacheJsonByKey namespace must be a non-empty string\");\n }\n if (typeof version !== \"string\" || version.length === 0) {\n throw new TypeError(\"cacheJsonByKey version must be a non-empty string\");\n }\n if (typeof key !== \"string\" || key.length === 0) {\n throw new TypeError(\"cacheJsonByKey key must be a non-empty string\");\n }\n const typedOptions: ParsedOptions<T> = {\n compute: value.compute,\n directory: value.directory,\n key: value.key,\n namespace: value.namespace,\n parse: value.parse,\n version: value.version\n };\n if (\n typedOptions.compute !== compute ||\n typedOptions.directory !== directory ||\n typedOptions.key !== key ||\n typedOptions.namespace !== namespace ||\n typedOptions.parse !== parse ||\n typedOptions.version !== version\n ) {\n throw new TypeError(\"cacheJsonByKey options changed during validation\");\n }\n return Object.freeze(typedOptions);\n}\n\nfunction cacheIdentityDigest(options: ParsedOptions<object>): string {\n return createHash(\"sha256\")\n .update(\n canonicalJsonBytes({\n cacheApiVersion: CACHE_API_VERSION,\n key: options.key,\n namespace: options.namespace,\n payloadVersion: options.version\n })\n )\n .digest(\"hex\");\n}\n\ntype CacheRead<T extends object> =\n | Readonly<{ readonly hit: true; readonly value: T }>\n | Readonly<{ readonly hit: false; readonly read: \"failed\" | \"invalid\" | \"miss\" }>;\n\nasync function readCacheEntry<T extends object>(\n input: Readonly<{\n readonly identityDigest: string;\n readonly parse: (value: unknown) => T;\n readonly targetPath: string;\n }>\n): Promise<CacheRead<T>> {\n let source: string;\n try {\n source = await fs.readFile(input.targetPath, \"utf8\");\n } catch (error: unknown) {\n return isMissingPath(error)\n ? Object.freeze({ hit: false, read: \"miss\" })\n : Object.freeze({ hit: false, read: \"failed\" });\n }\n try {\n const envelope = parseEnvelope(JSON.parse(source), input.identityDigest);\n if (envelope === undefined) return Object.freeze({ hit: false, read: \"invalid\" });\n return Object.freeze({\n hit: true,\n value: parseSynchronously(input.parse, envelope.payload, \"cached payload\")\n });\n } catch {\n return Object.freeze({ hit: false, read: \"invalid\" });\n }\n}\n\nfunction parseEnvelope(\n value: unknown,\n identityDigest: string\n): Readonly<{ readonly payload: CanonicalJsonObject }> | undefined {\n const record = snapshotClosedRecord(value);\n if (record === undefined || !hasExactPlainRecordKeys(record, CACHE_ENVELOPE_KEYS))\n return undefined;\n if (record.cacheFormatVersion !== CACHE_API_VERSION || record.identityDigest !== identityDigest) {\n return undefined;\n }\n const payload = canonicalizeJsonObject(record.payload);\n return payload === undefined ? undefined : Object.freeze({ payload });\n}\n\nfunction parseSynchronously<T extends object>(\n parse: (value: unknown) => T,\n payload: CanonicalJsonObject,\n subject: string\n): T {\n const value = parse(payload);\n if (isThenable(value))\n throw new TypeError(`cacheJsonByKey parse must synchronously return ${subject}`);\n return value;\n}\n\nfunction isThenable(value: unknown): boolean {\n return (\n ((typeof value === \"object\" && value !== null) || typeof value === \"function\") &&\n typeof (value as { then?: unknown }).then === \"function\"\n );\n}\n\nasync function publishCacheEntry<T extends object>(\n input: Readonly<{\n readonly directory: string;\n readonly identityDigest: string;\n readonly parse: (value: unknown) => T;\n readonly payload: CanonicalJsonObject;\n readonly targetPath: string;\n }>\n): Promise<boolean> {\n const temporaryPath = join(input.directory, `.vibe-check-cache-${randomUUID()}.tmp`);\n try {\n await fs.mkdir(input.directory, { recursive: true });\n await fs.writeFile(\n temporaryPath,\n JSON.stringify({\n cacheFormatVersion: CACHE_API_VERSION,\n identityDigest: input.identityDigest,\n payload: input.payload\n }),\n { encoding: \"utf8\", flag: \"wx\" }\n );\n } catch {\n await fs.rm(temporaryPath, { force: true }).catch(() => undefined);\n return false;\n }\n\n try {\n await fs.rename(temporaryPath, input.targetPath);\n return true;\n } catch (error: unknown) {\n if (isConcurrentTargetConflict(error)) {\n const concurrent = await readCacheEntry({\n identityDigest: input.identityDigest,\n parse: input.parse,\n targetPath: input.targetPath\n });\n await fs.rm(temporaryPath, { force: true }).catch(() => undefined);\n return concurrent.hit;\n }\n await fs.rm(temporaryPath, { force: true }).catch(() => undefined);\n return false;\n }\n}\n\nfunction isConcurrentTargetConflict(error: unknown): boolean {\n return (\n typeof error === \"object\" && error !== null && (error as { code?: unknown }).code === \"EEXIST\"\n );\n}\n\nfunction isMissingPath(error: unknown): boolean {\n return (\n typeof error === \"object\" && error !== null && (error as { code?: unknown }).code === \"ENOENT\"\n );\n}\n"]}

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

	@@ -1 +1 @@
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"]}
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;AAyhBnC,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/* Check Task 在 admission 到 settlement 期间持有的静态 named resource units。 /\nexport type CheckResourceClaims = Readonly<Record<string, number>>;\n\n/* 多 flag Check 启用条件使用的集合 predicate。 /\nexport type CheckFlagEnablementMode = \"all\" \| \"any\" \| \"none\" \| \"not-all\";\n\n/* executable Check 的声明式多 flag 启用条件。 /\nexport interface CheckFlagEnablement {\n /* 非空 flag token 集合；Definition 会去重并稳定排序。 /\n readonly flags: readonly [string, ...string[]];\n /* 对声明 token 与本次 Run flags 执行的 presence predicate。 /\n readonly mode: CheckFlagEnablementMode;\n /\n 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时保持只选择直接命中 Check 的兼容行为。\n * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止本次已启动的 prerequisite。\n /\n readonly propagateDependsOn?: true;\n}\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/* 读取已声明 direct relation final data 时的失败原因。 /\nexport type DependencyReadError = Readonly<\n \| {\n /* 当前 Check 未声明所请求的 direct relation ID。 /\n readonly code: \"dependency-not-declared\";\n /* 被拒绝的 direct relation ID。 /\n readonly checkId: string;\n }\n \| {\n /* 已声明 upstream 没有可读取的 final data。 /\n readonly code: \"upstream-data-unavailable\";\n /* 没有 final data 的 direct relation 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 relation final data。 /\n readonly ok: true;\n /* 被读取的 direct relation ID。 /\n readonly checkId: string;\n /* upstream 已结算为 `passed` 或 `failed` 的 status。 /\n readonly status: \"passed\" \| \"failed\";\n /* 已与原对象脱离的上游依赖终态数据。 /\n readonly data: CanonicalJsonObject;\n }\n \| {\n /* direct relation data 不可读取。 /\n readonly ok: false;\n /* 失败的授权或 upstream-data reason。 /\n readonly error: DependencyReadError;\n }\n>;\n\n/* 当前 Check 的一个已规范化直接 relation 及其完整终态事实。 /\nexport type DependencyObservation = Readonly<{\n /* 已规范化、稳定排序的 direct relation ID。 /\n readonly checkId: string;\n /* Core 已结算并冻结的四态 outcome。 /\n readonly outcome: CheckOutcome;\n}>;\n\n/* 当前 Check 的已规范化直接 relation outcomes 的 data reader。 /\nexport interface CheckDependencies {\n /\n 读取一个直接 relation 的 canonical final data。\n \n @returns 已声明的 `dependsOn` 或 `observes` relation 且为 `passed`/`failed` 的 Check 返回其 data；\n * 未声明或没有 final data 时返回 `ok: false`，不会授权 transitive Check。\n /\n get(checkId: string): DependencyReadResult;\n\n /\n 枚举当前 Check 的全部已规范化 direct relation outcomes。\n \n @returns 按有效 direct relation ID 稳定排序、深度冻结的 `{ checkId, outcome }` observations；只含当前\n * Check 显式或继承得到的 `dependsOn` / `observes` relation，不暴露 scheduler 历史、transitive 或未声明\n * Check。\n /\n list(): readonly DependencyObservation[];\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 的 absolute invocation artifact directory；caller 未授予时为 `null`。 /\n readonly artifactDirectory: string \| null;\n /* 读取当前 Check 的已声明 direct relations。 /\n readonly dependencies: CheckDependencies;\n /* 同一次 invocation 内由 Product 统一提供的 identity。 /\n readonly invocationId: string;\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 /* 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 /\n readonly enabledByFlags?: CheckFlagEnablement;\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 /* 必须全部 `passed` 才能开始当前 Check author work 的直接 prerequisite Check IDs。 /\n readonly dependsOn?: InheritableCheckCollection<string>;\n /* 等待任意 terminal outcome 并授权当前 Check readback 的直接 observation Check IDs。 /\n readonly observes?: InheritableCheckCollection<string>;\n /* 此 Check 及其 descendants 的最大并行预算。 /\n readonly maxParallel?: number;\n /* 同一 ready admission 层级中的静态优先级；省略时继承并最终规范化为 `0`。 /\n readonly admissionPriority?: number;\n /* 共享资源名称，或对父 mutex collection 的显式 edit。 /\n readonly mutex?: InheritableCheckCollection<string>;\n /* 静态 named resource claims；省略时继承，显式 mapping 完整替换。 /\n readonly resourceClaims?: CheckResourceClaims;\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；每个 admitted Check 先在自身 Task lifecycle 内执行\n * preflight，随后才执行 callback。`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 direct-relation 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 * import { defineCheck, defineConfig, run } from \"@zxyycom/vibe-check\";\n \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/finding-presentation.mjs ADDED Viewed

@@ -0,0 +1,40 @@
+/**
+ * 将调用方已经稳定排序的 Finding 投影为有界 Check messages。
+ *
+ * `limit`、安全字段和超限后的深入查看说明都由 producing Check 决定。Product 不读取 Finding
+ * shape，也不猜测完整明细位于 Records、artifact、transcript 或其它位置。
+ */
+export function presentCheckFindings(input) {
+    assertFindingLimit(input.limit);
+    if (input.findings.length === 0)
+        return Object.freeze([]);
+    const presentedFindings = input.findings.slice(0, input.limit);
+    const messages = presentedFindings.map((finding, index) => Object.freeze({ ...input.message(finding, index) }));
+    const omittedFindings = Object.freeze(input.findings.slice(input.limit));
+    if (omittedFindings.length > 0) {
+        messages.push(Object.freeze({
+            ...input.omittedMessage(Object.freeze({
+                omittedFindings,
+                omittedCount: omittedFindings.length,
+                presentedCount: presentedFindings.length,
+                totalCount: input.findings.length
+            }))
+        }));
+    }
+    return Object.freeze(messages);
+}
+/** Appends presentation-only messages without changing the owning terminal result. */
+export function appendCheckMessages(result, messages) {
+    if (messages.length === 0)
+        return result;
+    return Object.freeze({
+        ...result,
+        messages: Object.freeze([...(result.messages ?? []), ...messages])
+    });
+}
+function assertFindingLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit < 0) {
+        throw new TypeError("Finding presentation limit must be a non-negative safe integer");
+    }
+}
+//# sourceMappingURL=finding-presentation.mjs.map

package/dist/esm/check/finding-presentation.mjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"finding-presentation.mjs","sourceRoot":"","sources":["../../../src/check/finding-presentation.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAU,KAK7C;IACC,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAE1D,MAAM,iBAAiB,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CACxD,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,CACpD,CAAC;IACF,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,QAAQ,CAAC,IAAI,CACX,MAAM,CAAC,MAAM,CAAC;YACZ,GAAG,KAAK,CAAC,cAAc,CACrB,MAAM,CAAC,MAAM,CAAC;gBACZ,eAAe;gBACf,YAAY,EAAE,eAAe,CAAC,MAAM;gBACpC,cAAc,EAAE,iBAAiB,CAAC,MAAM;gBACxC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM;aAClC,CAAC,CACH;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,mBAAmB,CACjC,MAAyB,EACzB,QAAiC;IAEjC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACzC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,MAAM;QACT,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;KACnE,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,SAAS,CAAC,gEAAgE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC","sourcesContent":["import type { CheckMessage, CheckResult } from \"./check.ts\";\n\n/**\n * 将 Check-owned Finding 投影为有界 terminal messages 所需的超限上下文。\n * 完整 Finding facts 与深入查看位置继续由调用方拥有。\n */\nexport interface FindingOverflowContext<Finding> {\n readonly omittedFindings: readonly Finding[];\n readonly omittedCount: number;\n readonly presentedCount: number;\n readonly totalCount: number;\n}\n\n/**\n * 将调用方已经稳定排序的 Finding 投影为有界 Check messages。\n *\n * `limit`、安全字段和超限后的深入查看说明都由 producing Check 决定。Product 不读取 Finding\n * shape，也不猜测完整明细位于 Records、artifact、transcript 或其它位置。\n */\nexport function presentCheckFindings<Finding>(input: {\n readonly findings: readonly Finding[];\n readonly limit: number;\n readonly message: (finding: Finding, index: number) => CheckMessage;\n readonly omittedMessage: (context: FindingOverflowContext<Finding>) => CheckMessage;\n}): readonly CheckMessage[] {\n assertFindingLimit(input.limit);\n if (input.findings.length === 0) return Object.freeze([]);\n\n const presentedFindings = input.findings.slice(0, input.limit);\n const messages = presentedFindings.map((finding, index) =>\n Object.freeze({ ...input.message(finding, index) })\n );\n const omittedFindings = Object.freeze(input.findings.slice(input.limit));\n if (omittedFindings.length > 0) {\n messages.push(\n Object.freeze({\n ...input.omittedMessage(\n Object.freeze({\n omittedFindings,\n omittedCount: omittedFindings.length,\n presentedCount: presentedFindings.length,\n totalCount: input.findings.length\n })\n )\n })\n );\n }\n return Object.freeze(messages);\n}\n\n/** Appends presentation-only messages without changing the owning terminal result. */\nexport function appendCheckMessages<Data extends object>(\n result: CheckResult<Data>,\n messages: readonly CheckMessage[]\n): CheckResult<Data> {\n if (messages.length === 0) return result;\n return Object.freeze({\n ...result,\n messages: Object.freeze([...(result.messages ?? []), ...messages])\n });\n}\n\nfunction assertFindingLimit(limit: number): void {\n if (!Number.isSafeInteger(limit) || limit < 0) {\n throw new TypeError(\"Finding presentation limit must be a non-negative safe integer\");\n }\n}\n"]}

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

@@ -1,7 +1,7 @@
 const INHERITED_CHECK_COLLECTION = Symbol("vibe-check.inherited-check-collection");
 const inheritedCollections = new WeakSet();
 /**
- * 创建可用于 `dependsOn` 或 `mutex` 的受信任继承编辑。
+ * 创建可用于 `dependsOn`、`observes` 或 `mutex` 的受信任继承编辑。
  *
  * @typeParam T - 要添加或移除的 collection item 类型。
  * @param value - 至少提供 `add` 或 `remove` 的 edit；空数组可显式表示不添加或不移除。

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

	@@ -1 +1 @@
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"]}
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`、`observes` 或 `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"]}