@zxyycom/vibe-check 0.0.1 → 0.0.2

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@zxyycom/vibe-check",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "description": "通用 TypeScript 质量门禁工具，提供可组合 Check、类型安全 API 和结构化结果。",
+  "keywords": [
+    "quality-gate",
+    "project-validation",
+    "code-quality",
+    "ci",
+    "typescript",
+    "nodejs"
+  ],
   "type": "module",
-  "license": "MIT",
+  "license": "MIT AND Apache-2.0 AND BSD-2-Clause",
   "engines": {
-    "bun": ">=1.3.14"
+    "node": ">=24.18"
   },
   "repository": {
     "type": "git",
@@ -26,17 +35,20 @@
     "README.md",
     "docs",
     "dist",
+    "licenses",
     "types",
-    "src",
-    "third-party-licenses"
+    "src"
   ],
   "dependencies": {
     "@humanwhocodes/momoa": "3.3.12",
+    "@secretlint/core": "13.0.5",
+    "@secretlint/secretlint-rule-privatekey": "13.0.5",
     "ajv": "8.20.0",
     "csv-parse": "7.0.1",
     "execa": "9.6.1",
     "github-slugger": "2.0.0",
-    "jscpd": "^5.0.11",
+    "immutable": "5.1.9",
+    "jscpd": "^5.1.1",
     "mdast-util-from-markdown": "2.0.3",
     "mdast-util-frontmatter": "2.0.1",
     "mdast-util-gfm": "3.1.0",

package/src/cache/cache-json-by-key.ts

@@ -0,0 +1,304 @@
+/** 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,
+  type CanonicalJsonObject
+} from "../data-boundary/canonical-data.ts";
+import { hasExactPlainRecordKeys, snapshotClosedRecord } from "../data-boundary/closed-values.ts";
+
+const CACHE_API_VERSION = "caller-keyed-json-v1";
+const CACHE_ENVELOPE_KEYS = ["cacheFormatVersion", "identityDigest", "payload"] as const;
+
+/**
+ * `cacheJsonByKey` 的 caller-owned identity、payload parser 与 computation。
+ *
+ * `key` 必须覆盖所有会改变 computation 结果的输入、实现、options、toolchain 与声明的外部状态；
+ * 不能放入 secret 或低熵敏感值。`directory` 是调用方信任、可自行删除的本地状态空间。
+ */
+type NonThenable<T extends object> = T & Readonly<{ readonly then?: undefined }>;
+
+/** Caller-keyed JSON cache 的 options。 */
+export interface CacheJsonByKeyOptions<T extends object> {
+  /** cache miss、读取失败或 payload 无效时执行的 sync/async computation。 */
+  readonly compute: () => unknown;
+  /** 调用方信任、可自行清理的 absolute local directory。 */
+  readonly directory: string;
+  /** 覆盖所有影响 computation 结果的完整 semantic key；不得包含 secret 或低熵敏感值。 */
+  readonly key: string;
+  /** 调用方为这一类缓存选择的非空 identity namespace。 */
+  readonly namespace: string;
+  /** 同步验证 cached/computed canonical JSON object，并返回调用方的 typed value。 */
+  readonly parse: (value: unknown) => NonThenable<T>;
+  /** 调用方控制、在 payload 或 computation contract 改变时更新的非空版本。 */
+  readonly version: string;
+}
+
+/** `cacheJsonByKey` 返回的闭合 cache observation 与本次 parser value。 */
+export type CacheJsonByKeyResult<T extends object> =
+  | Readonly<{
+      /** 已读取并通过 parser 验证现有 payload。 */
+      readonly read: "hit";
+      /** 本次 value 来自 cache，不调用 `compute`。 */
+      readonly source: "cache";
+      /** `parse` 返回的调用方 typed value。 */
+      readonly value: T;
+      /** cache hit 不尝试重新写入。 */
+      readonly write: "not-attempted";
+    }>
+  | Readonly<{
+      /** 没有 entry、读取失败，或已有 payload 未通过 identity/parser 验证。 */
+      readonly read: "failed" | "invalid" | "miss";
+      /** 本次 value 来自成功的 `compute` 与 `parse`。 */
+      readonly source: "computed";
+      /** `parse` 返回的调用方 typed value。 */
+      readonly value: T;
+      /** 新 payload 已存储，或存储失败但 typed value 仍可使用。 */
+      readonly write: "failed" | "stored";
+    }>;
+
+/**
+ * 按 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<T extends object>(
+  authoredOptions: CacheJsonByKeyOptions<T>
+): Promise<CacheJsonByKeyResult<T>> {
+  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"
+  });
+}
+
+type ParsedOptions<T extends object> = Readonly<{
+  readonly compute: () => unknown;
+  readonly directory: string;
+  readonly key: string;
+  readonly namespace: string;
+  readonly parse: (value: unknown) => T;
+  readonly version: string;
+}>;
+
+function parseOptions<T extends object>(value: CacheJsonByKeyOptions<T>): ParsedOptions<T> {
+  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: ParsedOptions<T> = {
+    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: ParsedOptions<object>): string {
+  return createHash("sha256")
+    .update(
+      canonicalJsonBytes({
+        cacheApiVersion: CACHE_API_VERSION,
+        key: options.key,
+        namespace: options.namespace,
+        payloadVersion: options.version
+      })
+    )
+    .digest("hex");
+}
+
+type CacheRead<T extends object> =
+  | Readonly<{ readonly hit: true; readonly value: T }>
+  | Readonly<{ readonly hit: false; readonly read: "failed" | "invalid" | "miss" }>;
+
+async function readCacheEntry<T extends object>(
+  input: Readonly<{
+    readonly identityDigest: string;
+    readonly parse: (value: unknown) => T;
+    readonly targetPath: string;
+  }>
+): Promise<CacheRead<T>> {
+  let source: string;
+  try {
+    source = await fs.readFile(input.targetPath, "utf8");
+  } catch (error: unknown) {
+    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: unknown,
+  identityDigest: string
+): Readonly<{ readonly payload: CanonicalJsonObject }> | undefined {
+  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<T extends object>(
+  parse: (value: unknown) => T,
+  payload: CanonicalJsonObject,
+  subject: string
+): T {
+  const value = parse(payload);
+  if (isThenable(value))
+    throw new TypeError(`cacheJsonByKey parse must synchronously return ${subject}`);
+  return value;
+}
+
+function isThenable(value: unknown): boolean {
+  return (
+    ((typeof value === "object" && value !== null) || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+async function publishCacheEntry<T extends object>(
+  input: Readonly<{
+    readonly directory: string;
+    readonly identityDigest: string;
+    readonly parse: (value: unknown) => T;
+    readonly payload: CanonicalJsonObject;
+    readonly targetPath: string;
+  }>
+): Promise<boolean> {
+  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: unknown) {
+    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: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && (error as { code?: unknown }).code === "EEXIST"
+  );
+}
+
+function isMissingPath(error: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && (error as { code?: unknown }).code === "ENOENT"
+  );
+}

package/src/check/check.ts

@@ -53,6 +53,25 @@ export interface CheckResultMessages {
 /** 已结算 Check 在人读 progress 中的可见性。 */
 export type CheckVisibility = "always" | "attention";
 
+/** Check Task 在 admission 到 settlement 期间持有的静态 named resource units。 */
+export type CheckResourceClaims = Readonly<Record<string, number>>;
+
+/** 多 flag Check 启用条件使用的集合 predicate。 */
+export type CheckFlagEnablementMode = "all" | "any" | "none" | "not-all";
+
+/** executable Check 的声明式多 flag 启用条件。 */
+export interface CheckFlagEnablement {
+  /** 非空 flag token 集合；Definition 会去重并稳定排序。 */
+  readonly flags: readonly [string, ...string[]];
+  /** 对声明 token 与本次 Run flags 执行的 presence predicate。 */
+  readonly mode: CheckFlagEnablementMode;
+  /**
+   * 条件命中时是否启动本 Check 的传递 `dependsOn` prerequisite；省略时保持只选择直接命中 Check 的兼容行为。
+   * `observes` 不参与此选择，且 dependency 自己的 flag 条件不会阻止本次已启动的 prerequisite。
+   */
+  readonly propagateDependsOn?: true;
+}
+
 /**
  * Check callback 的 terminal result。
  *
@@ -139,18 +158,18 @@ interface CheckRecordReporter {
   report(identity: RecordIdentityInput, data: object): void;
 }
 
-/** 读取已声明 dependency final data 时的失败原因。 */
+/** 读取已声明 direct relation final data 时的失败原因。 */
 export type DependencyReadError = Readonly<
   | {
-      /** 当前 Check 未声明所请求的 dependency ID。 */
+      /** 当前 Check 未声明所请求的 direct relation ID。 */
       readonly code: "dependency-not-declared";
-      /** 被拒绝的 dependency ID。 */
+      /** 被拒绝的 direct relation ID。 */
       readonly checkId: string;
     }
   | {
       /** 已声明 upstream 没有可读取的 final data。 */
       readonly code: "upstream-data-unavailable";
-      /** 没有 final data 的 direct dependency ID。 */
+      /** 没有 final data 的 direct relation ID。 */
       readonly checkId: string;
       /** 阻止 readback 的 upstream terminal status。 */
       readonly status: "not-applicable" | "unavailable";
@@ -160,9 +179,9 @@ export type DependencyReadError = Readonly<
 /** {@link CheckDependencies.get} 的受控 readback 结果。 */
 export type DependencyReadResult = Readonly<
   | {
-      /** 成功读取 direct dependency final data。 */
+      /** 成功读取 direct relation final data。 */
       readonly ok: true;
-      /** 被读取的 direct dependency ID。 */
+      /** 被读取的 direct relation ID。 */
       readonly checkId: string;
       /** upstream 已结算为 `passed` 或 `failed` 的 status。 */
       readonly status: "passed" | "failed";
@@ -170,22 +189,39 @@ export type DependencyReadResult = Readonly<
       readonly data: CanonicalJsonObject;
     }
   | {
-      /** dependency data 不可读取。 */
+      /** direct relation data 不可读取。 */
       readonly ok: false;
       /** 失败的授权或 upstream-data reason。 */
       readonly error: DependencyReadError;
     }
 >;
 
-/** 当前 Check 的已规范化直接 dependencies 的 data reader。 */
+/** 当前 Check 的一个已规范化直接 relation 及其完整终态事实。 */
+export type DependencyObservation = Readonly<{
+  /** 已规范化、稳定排序的 direct relation ID。 */
+  readonly checkId: string;
+  /** Core 已结算并冻结的四态 outcome。 */
+  readonly outcome: CheckOutcome;
+}>;
+
+/** 当前 Check 的已规范化直接 relation outcomes 的 data reader。 */
 export interface CheckDependencies {
   /**
-   * 读取一个直接 dependency 的 canonical final data。
+   * 读取一个直接 relation 的 canonical final data。
    *
-   * @returns 已声明且为 `passed`/`failed` 的 dependency 返回其 data；未声明或没有 final data 时返回
-   * `ok: false`，不会授权 transitive dependency。
+   * @returns 已声明的 `dependsOn` 或 `observes` relation 且为 `passed`/`failed` 的 Check 返回其 data；
+   * 未声明或没有 final data 时返回 `ok: false`，不会授权 transitive Check。
    */
   get(checkId: string): DependencyReadResult;
+
+  /**
+   * 枚举当前 Check 的全部已规范化 direct relation outcomes。
+   *
+   * @returns 按有效 direct relation ID 稳定排序、深度冻结的 `{ checkId, outcome }` observations；只含当前
+   * Check 显式或继承得到的 `dependsOn` / `observes` relation，不暴露 scheduler 历史、transitive 或未声明
+   * Check。
+   */
+  list(): readonly DependencyObservation[];
 }
 
 /** callback 可读取的、由 Product 规范化的项目上下文。 */
@@ -202,8 +238,12 @@ export interface CheckProjectContext {
  * @typeParam Options - 此 Check preflight 后传给 execution 的 options shape。
  */
 export interface CheckExecutionContext<Options extends object> {
-  /** 读取当前 Check 的已声明 direct dependencies。 */
+  /** 当前 Check 的 absolute invocation artifact directory；caller 未授予时为 `null`。 */
+  readonly artifactDirectory: string | null;
+  /** 读取当前 Check 的已声明 direct relations。 */
   readonly dependencies: CheckDependencies;
+  /** 同一次 invocation 内由 Product 统一提供的 identity。 */
+  readonly invocationId: string;
   /** 深度只读、canonical 的 invocation-local prepared Check options。 */
   readonly options: DeepReadonly<Options>;
   /** 已规范化的项目根与 flags。 */
@@ -288,6 +328,8 @@ interface CheckBase<AuthoredOptions extends object, PreparedOptions extends obje
   readonly displayName: string;
   /** Check-owned declarative options；默认 Check 的嵌套 branch 以普通对象组合替换。 */
   readonly options?: AuthoredOptions;
+  /** 仅当多 flag presence predicate 匹配时启用 executable Check；省略时始终启用。 */
+  readonly enabledByFlags?: CheckFlagEnablement;
   /** 可执行节点的 callback；省略时此节点只承载递归 children。 */
   execution?(
     this: void,
@@ -295,12 +337,18 @@ interface CheckBase<AuthoredOptions extends object, PreparedOptions extends obje
   ): CheckResult | Promise<CheckResult>;
   /** 继承 scheduling context 的 child Checks，不会单独形成 container result。 */
   readonly checks?: readonly Check[];
-  /** 直接 prerequisite Check IDs，或对父 dependency collection 的显式 edit。 */
+  /** 必须全部 `passed` 才能开始当前 Check author work 的直接 prerequisite Check IDs。 */
   readonly dependsOn?: InheritableCheckCollection<string>;
+  /** 等待任意 terminal outcome 并授权当前 Check readback 的直接 observation Check IDs。 */
+  readonly observes?: InheritableCheckCollection<string>;
   /** 此 Check 及其 descendants 的最大并行预算。 */
   readonly maxParallel?: number;
+  /** 同一 ready admission 层级中的静态优先级；省略时继承并最终规范化为 `0`。 */
+  readonly admissionPriority?: number;
   /** 共享资源名称，或对父 mutex collection 的显式 edit。 */
   readonly mutex?: InheritableCheckCollection<string>;
+  /** 静态 named resource claims；省略时继承，显式 mapping 完整替换。 */
+  readonly resourceClaims?: CheckResourceClaims;
   /** 已结算 Check 的人读可见性；可执行节点默认 `always`。 */
   readonly visibility?: CheckVisibility;
 }
@@ -327,9 +375,9 @@ type CheckPreflightField<AuthoredOptions extends object, PreparedOptions extends
  *
  * @typeParam AuthoredOptions - Definition 中的 declarative options shape。
  * @typeParam PreparedOptions - preflight 后 callback 接收的 invocation-local options shape。
- * @remarks Definition 只闭合 authored JSON options；preflight 在同一 Run 的所有 execution 前作为全局
- * barrier 执行。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以省略。它不进入
- * declarative fingerprint 或 machine output。
+ * @remarks Definition 只闭合 authored JSON options；每个 admitted Check 先在自身 Task lifecycle 内执行
+ * preflight，随后才执行 callback。`PreparedOptions` 与 `AuthoredOptions` 不同时必须提供 preflight；同形时可以
+ * 省略。它不进入 declarative fingerprint 或 machine output。
  */
 export type Check<
   AuthoredOptions extends object = object,
@@ -346,7 +394,7 @@ export type EmptyCheckOptions = Readonly<Record<never, never>>;
 type NonThenableData = Readonly<{ readonly then?: CanonicalJsonValue }>;
 
 /**
- * 将 canonical dependency data 还原为 provider final-data shape 的同步 parser。
+ * 将 canonical direct-relation data 还原为 provider final-data shape 的同步 parser。
  *
  * @typeParam FinalData - provider 在 `passed`/`failed` result 中声明的 final-data shape。
  * @remarks Product 不调用此 parser；provider 负责不受信任或跨版本 data 的业务验证。
@@ -434,6 +482,8 @@ export type TypedCheckWithoutOptions<
  * @remarks 此函数负责 authoring inference；{@link run} 负责 Project Definition validation。
  * @example 定义带 options、Records 与 messages 的自定义 Check
  * ```ts
+ * import { defineCheck, defineConfig, run } from "@zxyycom/vibe-check";
+ *
  * function hasValidLicensePolicyOptions(options: object): boolean {
  *   const denied: unknown = Reflect.get(options, "denied");
  *   return (

package/src/check/finding-presentation.ts

@@ -0,0 +1,67 @@
+import type { CheckMessage, CheckResult } from "./check.ts";
+
+/**
+ * 将 Check-owned Finding 投影为有界 terminal messages 所需的超限上下文。
+ * 完整 Finding facts 与深入查看位置继续由调用方拥有。
+ */
+export interface FindingOverflowContext<Finding> {
+  readonly omittedFindings: readonly Finding[];
+  readonly omittedCount: number;
+  readonly presentedCount: number;
+  readonly totalCount: number;
+}
+
+/**
+ * 将调用方已经稳定排序的 Finding 投影为有界 Check messages。
+ *
+ * `limit`、安全字段和超限后的深入查看说明都由 producing Check 决定。Product 不读取 Finding
+ * shape，也不猜测完整明细位于 Records、artifact、transcript 或其它位置。
+ */
+export function presentCheckFindings<Finding>(input: {
+  readonly findings: readonly Finding[];
+  readonly limit: number;
+  readonly message: (finding: Finding, index: number) => CheckMessage;
+  readonly omittedMessage: (context: FindingOverflowContext<Finding>) => CheckMessage;
+}): readonly CheckMessage[] {
+  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<Data extends object>(
+  result: CheckResult<Data>,
+  messages: readonly CheckMessage[]
+): CheckResult<Data> {
+  if (messages.length === 0) return result;
+  return Object.freeze({
+    ...result,
+    messages: Object.freeze([...(result.messages ?? []), ...messages])
+  });
+}
+
+function assertFindingLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit < 0) {
+    throw new TypeError("Finding presentation limit must be a non-negative safe integer");
+  }
+}

package/src/check/inherited-collection.ts

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