@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/package-checks/json-schema-validation/options-validation.ts

@@ -1,27 +1,16 @@
 import {
-  hasExactPlainRecordKeys,
   snapshotClosedArray,
-  snapshotClosedRecord
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
 } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
 export function validJsonSchemaValidationOptions(
   candidateOptions: unknown
 ): candidateOptions is ResolvedJsonSchemaValidationOptions {
-  const options = exactRecord(candidateOptions, [
+  const options = snapshotExactClosedRecord(candidateOptions, [
     "files",
     "maximumBytes",
     "schemaIdentity",
@@ -32,7 +21,7 @@ export function validJsonSchemaValidationOptions(
   if (
     options === undefined ||
     !validProjectFileSelection(options.files) ||
-    !positiveSafeInteger(options.maximumBytes) ||
+    !isPositiveSafeInteger(options.maximumBytes) ||
     !validJsonSchemaIdentity(options.schemaIdentity) ||
     !validJsonSchemaReferenceResolution(options.referenceResolution)
   ) {
@@ -50,7 +39,7 @@ export function validJsonSchemaValidationOptions(
 }
 
 function validJsonSchemaIdentity(candidateIdentity: unknown): boolean {
-  const identity = exactRecord(candidateIdentity, ["mode"]);
+  const identity = snapshotExactClosedRecord(candidateIdentity, ["mode"]);
   return (
     identity !== undefined &&
     (identity.mode === "require-match" ||
@@ -65,11 +54,11 @@ function validJsonSchemaReferenceResolution(candidateResolution: unknown): boole
     return false;
   }
   if (referenceResolution.mode === "offline") {
-    return exactRecord(referenceResolution, ["mode"]) !== undefined;
+    return snapshotExactClosedRecord(referenceResolution, ["mode"]) !== undefined;
   }
   if (referenceResolution.mode !== "allowlisted") return false;
 
-  const allowlisted = exactRecord(referenceResolution, ["mode", "sources"]);
+  const allowlisted = snapshotExactClosedRecord(referenceResolution, ["mode", "sources"]);
   const sources = allowlisted === undefined ? undefined : snapshotClosedArray(allowlisted.sources);
   return sources !== undefined && sources.length > 0 && validJsonSchemaReferenceSources(sources);
 }
@@ -104,11 +93,11 @@ function validatedReferenceSource(sourceCandidate: unknown) {
 }
 
 function validBundledSource(source: Readonly<Record<string, unknown>>): boolean {
-  return exactRecord(source, ["kind", "catalog"])?.catalog === "json-schema-2020-12";
+  return snapshotExactClosedRecord(source, ["kind", "catalog"])?.catalog === "json-schema-2020-12";
 }
 
 function validatedHttpsSource(source: Readonly<Record<string, unknown>>) {
-  const httpsSource = exactRecord(source, ["kind", "id", "origin", "pathPrefix"]);
+  const httpsSource = snapshotExactClosedRecord(source, ["kind", "id", "origin", "pathPrefix"]);
   if (
     httpsSource === undefined ||
     !safeAbsoluteIdentifier(httpsSource.id) ||
@@ -124,7 +113,7 @@ function validatedSchemaRegistryIds(schemas: readonly unknown[]): ReadonlySet<st
   const declaredSchemaIds = new Set<string>();
   const schemaPaths = new Set<string>();
   for (const schemaCandidate of schemas) {
-    const schemaRecord = exactRecord(schemaCandidate, ["id", "path"]);
+    const schemaRecord = snapshotExactClosedRecord(schemaCandidate, ["id", "path"]);
     if (
       schemaRecord === undefined ||
       !safeAbsoluteIdentifier(schemaRecord.id) ||
@@ -147,7 +136,11 @@ function validJsonSchemaBindings(
   const bindingIds = new Set<string>();
   const bindingTargets = new Set<string>();
   for (const bindingCandidate of bindings) {
-    const bindingRecord = exactRecord(bindingCandidate, ["id", "instancePath", "schemaId"]);
+    const bindingRecord = snapshotExactClosedRecord(bindingCandidate, [
+      "id",
+      "instancePath",
+      "schemaId"
+    ]);
     if (
       bindingRecord === undefined ||
       !safeBindingId(bindingRecord.id) ||

package/src/package-checks/json-schema-validation/options.ts

@@ -1,46 +1,72 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type {
   ProjectFileSelection,
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 
+/** 已注册 schema 的 root `$id` 与配置 identity 之间的全 Check 统一规则。 */
 export type JsonSchemaIdentityMode =
+  /** root `$id` 必须等于 `schemas[].id`，该配置 ID 也是 engine identity。 */
   | "require-match"
+  /** 配置 ID 是 engine identity；object schema 的 invocation-local compile copy 使用该 `$id`。 */
   | "configuration-authoritative"
+  /** 安全的 root `$id` 是 engine identity；配置 ID 仍是 binding 与公开事实的标签。 */
   | "document-authoritative";
 
+/** 整个 Check 共用、不能按单个 schema 混用的 root schema identity policy。 */
 export interface JsonSchemaIdentity {
+  /** root `$id` 与配置 `schemas[].id` 的关系。 */
   readonly mode: JsonSchemaIdentityMode;
 }
 
+/** allowlisted 引用解析可读取的单一 Schema 来源及其固定边界。 */
 export type JsonSchemaReferenceSource =
+  /** Package 固定的 JSON Schema catalog；它不授权网络请求。 */
   | Readonly<{ readonly kind: "bundled"; readonly catalog: "json-schema-2020-12" }>
   | Readonly<{
+      /** 只允许本 source 明确限定的 HTTPS reference scope。 */
       readonly kind: "https";
+      /** 调用方为本 source 选择的安全稳定 identity，不是请求 URL。 */
       readonly id: string;
+      /** 精确 HTTPS origin；不含 path、credentials、query 或 fragment。 */
       readonly origin: string;
+      /** 已授权 URL path 的边界；从 `/` 开始，非 root prefix 必须以 `/` 结束。 */
       readonly pathPrefix: string;
     }>;
 
+/** 本次 Check 解析 local、bundled 与 allowlisted Schema 引用的封闭策略。 */
 export type JsonSchemaReferenceResolution =
+  /** 只使用 local schemas 和允许的 bundled catalog，不读取额外 HTTPS schema。 */
   | Readonly<{ readonly mode: "offline" }>
   | Readonly<{
+      /** 只从 `sources` 的精确 scope 读取额外 schema；没有 implicit registry、headers 或 redirects。 */
       readonly mode: "allowlisted";
+      /** 完整替换的明确 source 集合；每项决定自身可读取的 reference scope。 */
       readonly sources: readonly JsonSchemaReferenceSource[];
     }>;
 
+/** 调用方注册的一份 local schema resource；注册表不自动发现 schema。 */
 export interface RegisteredJsonSchema {
+  /** binding 与公开 facts 使用的安全 schema identity。 */
   readonly id: string;
+  /** 已由 `files` selection 批准的 normalized project-relative `.json` path。 */
   readonly path: string;
 }
 
+/** 调用方将一个已批准 local JSON instance 明确绑定到已注册 schema 的关系。 */
 export interface JsonSchemaInstanceBinding {
+  /** 本次 Check 内唯一、用于公开 facts 的 binding identity。 */
   readonly id: string;
+  /** 已由 `files` selection 批准的 normalized project-relative `.json` instance path。 */
   readonly instancePath: string;
+  /** 必须引用 `schemas` 中已注册 schema 的 identity。 */
   readonly schemaId: string;
 }
 
 /** `jsonSchemaValidation(options?)` 接受的可省略 authoring policy。 */
-export interface JsonSchemaValidationOptions {
+export interface JsonSchemaValidationOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** schema/instance declarations 必须属于的 repository-file selection。 */
   readonly files?: ProjectFileSelectionOptions;
   /** 每个 local schema/instance document 允许的最大 raw byte 数；省略时为 1 MiB。 */

package/src/package-checks/json-schema-validation/reference-resolver.ts

@@ -68,9 +68,13 @@ export class ControlledReferenceResolver {
       throw new ReferenceResolutionFailure("unapproved-reference");
     if (this.#resolverInput.signal.aborted) throw new ReferenceTransportFailure();
     const controller = new AbortController();
-    const abortForCaller = (): void => controller.abort();
+    const abortForCaller = (): void => {
+      controller.abort();
+    };
     this.#resolverInput.signal.addEventListener("abort", abortForCaller, { once: true });
-    const timeout = setTimeout(() => controller.abort(), REMOTE_TIMEOUT_MS);
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, REMOTE_TIMEOUT_MS);
     try {
       return await this.loadWithController(referenceUri, controller);
     } catch (error) {

package/src/package-checks/json-schema-validation/schema-policy.ts

@@ -108,8 +108,11 @@ function inspectDirectSchemaPolicy(
 ): SchemaCompileReason | undefined {
   if (Object.hasOwn(schemaObject, "$async")) return "invalid-schema";
   if (hasUnsupportedReferenceKeyword(schemaObject)) return "unsupported-reference";
-  if (Object.hasOwn(schemaObject, "$id") && !permittedNestedIdentifier(schemaObject.$id)) {
-    return "unsupported-reference";
+  if (Object.hasOwn(schemaObject, "$id")) {
+    const identifier = schemaObject.$id;
+    if (identifier === undefined || !permittedNestedIdentifier(identifier)) {
+      return "unsupported-reference";
+    }
   }
   return hasInvalidReferenceValue(schemaObject) ? "unsupported-reference" : undefined;
 }
@@ -123,9 +126,11 @@ function hasUnsupportedReferenceKeyword(
 function hasInvalidReferenceValue(
   schemaObject: Readonly<Record<string, StrictJsonValue>>
 ): boolean {
-  return ["$ref", "$schema"].some(
-    (key) => Object.hasOwn(schemaObject, key) && !permittedReference(schemaObject[key])
-  );
+  return ["$ref", "$schema"].some((key) => {
+    if (!Object.hasOwn(schemaObject, key)) return false;
+    const reference = schemaObject[key];
+    return reference === undefined || !permittedReference(reference);
+  });
 }
 
 function inspectNestedSchemaPolicies(

package/src/package-checks/json-validation/default-check.ts

@@ -1,4 +1,8 @@
 import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
 import { JSON_VALIDATION_CHECK_DEFINITION, executeJsonValidation } from "./json-validation.ts";
 import { parseJsonValidationData } from "./final-data.ts";
 import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./options.ts";
@@ -13,21 +17,38 @@ import { validJsonValidationOptions } from "./options-validation.ts";
  * @throws {TypeError} input 含未知字段、非法文件选择或非法 byte limit 时抛出。
  */
 export function jsonValidation(
-  options: JsonValidationOptions = {}
+  options?: JsonValidationOptions<"json-validation">
 ): TypedCheckWithOptions<
   "json-validation",
   ResolvedJsonValidationOptions,
   typeof parseJsonValidationData
-> {
-  const resolvedOptions = resolveJsonValidationOptions(options);
+>;
+export function jsonValidation<const Id extends string>(
+  options: JsonValidationOptions<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<Id, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export function jsonValidation(
+  options: JsonValidationOptions
+): TypedCheckWithOptions<string, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export function jsonValidation(
+  options: JsonValidationOptions = {}
+): TypedCheckWithOptions<string, ResolvedJsonValidationOptions, typeof parseJsonValidationData> {
+  const input = resolvePackageCheckAuthoringInput(
+    options,
+    ["files", "maximumBytes"],
+    JSON_VALIDATION_CHECK_DEFINITION
+  );
+  if (input === undefined) {
+    throw new TypeError("jsonValidation options must match the documented closed policy");
+  }
+  const resolvedOptions = resolveJsonValidationOptions(input.domainOptions);
   if (resolvedOptions === undefined) {
     throw new TypeError("jsonValidation options must match the documented closed policy");
   }
   return defineCheck({
-    ...JSON_VALIDATION_CHECK_DEFINITION,
-    execution: executeJsonValidation,
+    ...input.definition,
+    execute: executeJsonValidation,
     parseData: parseJsonValidationData,
-    preflight: (preparedOptions) =>
+    prepare: (preparedOptions) =>
       validJsonValidationOptions(preparedOptions)
         ? { status: "success", preparedOptions }
         : {

package/src/package-checks/json-validation/final-data.ts

@@ -6,10 +6,15 @@ import {
 
 /** `json-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface JsonValidationFinalData {
+  /** 已完成 JSON parse 判定的文件数，恒等于 validFileCount 与 invalidFileCount 之和。 */
   readonly scannedFileCount: number;
+  /** 被 bounded strict-document boundary 接受为有效 JSON 的文件数。 */
   readonly validFileCount: number;
+  /** 形成 `too-large`、encoding、syntax 或 duplicate-key document issue 的文件数。 */
   readonly invalidFileCount: number;
+  /** 全部 invalid file 与 rejected input 的合计问题数。 */
   readonly issueCount: number;
+  /** files policy 已选中、但因不是 lower-case `.json` path 而被拒绝的输入数。 */
   readonly rejectedInputCount: number;
 }
 

package/src/package-checks/json-validation/options-validation.ts

@@ -1,27 +1,13 @@
-import {
-  hasExactPlainRecordKeys,
-  snapshotClosedRecord
-} from "../../data-boundary/closed-values.ts";
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import type { ResolvedJsonValidationOptions } from "./options.ts";
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
 export function validJsonValidationOptions(value: unknown): value is ResolvedJsonValidationOptions {
-  const options = exactRecord(value, ["files", "maximumBytes"]);
+  const options = snapshotExactClosedRecord(value, ["files", "maximumBytes"]);
   return (
     options !== undefined &&
     validProjectFileSelection(options.files) &&
-    positiveSafeInteger(options.maximumBytes)
+    isPositiveSafeInteger(options.maximumBytes)
   );
 }

package/src/package-checks/json-validation/options.ts

@@ -1,10 +1,13 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type {
   ProjectFileSelection,
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 
 /** `jsonValidation(options?)` 接受的可省略 authoring policy。 */
-export interface JsonValidationOptions {
+export interface JsonValidationOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** 参与本 Check 的 repository-file selection；省略字段使用 package defaults。 */
   readonly files?: ProjectFileSelectionOptions;
   /** 单个 JSON document 允许的最大 raw byte 数；省略时为 1 MiB。 */

package/src/package-checks/local-cache-options.ts

@@ -0,0 +1,40 @@
+import { isAbsolute } from "node:path";
+
+import {
+  hasExactPlainRecordKeys,
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../data-boundary/closed-values.ts";
+
+/** Shared closed grammar for an explicitly owned, deletable local cache directory. */
+export type LocalCacheOptions =
+  | Readonly<{ readonly enabled: false }>
+  | Readonly<{ readonly enabled: true; readonly directory: string }>;
+
+export function resolveOptionalLocalCacheOptions(value: unknown): LocalCacheOptions | undefined {
+  if (value === undefined) return Object.freeze({ enabled: false as const });
+  const cache = snapshotClosedRecord(value);
+  if (cache === undefined) return undefined;
+  if (hasExactPlainRecordKeys(cache, ["enabled"]) && cache.enabled === false)
+    return Object.freeze({ enabled: false as const });
+  if (
+    hasExactPlainRecordKeys(cache, ["enabled", "directory"]) &&
+    cache.enabled === true &&
+    typeof cache.directory === "string"
+  )
+    return Object.freeze({ enabled: true as const, directory: cache.directory });
+  return undefined;
+}
+
+export function validLocalCacheOptions(value: unknown): value is LocalCacheOptions {
+  const disabled = snapshotExactClosedRecord(value, ["enabled"]);
+  if (disabled?.enabled === false) return true;
+  const enabled = snapshotExactClosedRecord(value, ["enabled", "directory"]);
+  return (
+    enabled?.enabled === true &&
+    typeof enabled.directory === "string" &&
+    enabled.directory.length > 0 &&
+    !enabled.directory.includes("\0") &&
+    isAbsolute(enabled.directory)
+  );
+}

package/src/package-checks/maintenance-reminders/final-data.ts

@@ -43,25 +43,42 @@ export function isMaintenanceCommitId(value: unknown): value is string {
 }
 
 export type MeasuredMaintenanceReminderAssessment = Readonly<{
+  /** 未超过任何阈值时为 clear；至少严格超过一个阈值时为 due。 */
   readonly assessment: "clear" | "due";
+  /** reminder 配置锁定的完整基线 commit ID。 */
   readonly baseCommit: string;
+  /** first-parent 区间内 numstat additions 与 deletions 的总和。 */
   readonly changedLines: number;
+  /** 从 HEAD 沿 first-parent 到 baseCommit 的 commit 数。 */
   readonly commitCount: number;
+  /** 实际值严格超过配置上限的维度；clear assessment 时为空。 */
   readonly exceeded: readonly ("commits" | "changed-lines")[];
+  /** 测量时 HEAD 的完整 commit ID。 */
   readonly headCommit: string;
+  /** Definition 中该 reminder 的稳定局部 ID。 */
   readonly id: string;
+  /** due 或 unavailable 是否阻断 Check 的配置模式。 */
   readonly mode: MaintenanceReminderMode;
 }>;
 
 export type UnavailableMaintenanceReminderAssessment = Readonly<{
+  /** 表示该 reminder 未能形成计数测量。 */
   readonly assessment: "unavailable";
+  /** reminder 配置锁定的完整基线 commit ID。 */
   readonly baseCommit: string;
+  /** unavailable assessment 不发布 partial changed-line count。 */
   readonly changedLines: null;
+  /** unavailable assessment 不发布 partial commit count。 */
   readonly commitCount: null;
+  /** unavailable assessment 不判定任何阈值已超过。 */
   readonly exceeded: readonly [];
+  /** 已成功解析时的完整 HEAD commit ID；解析 HEAD 失败时为 null。 */
   readonly headCommit: string | null;
+  /** Definition 中该 reminder 的稳定局部 ID。 */
   readonly id: string;
+  /** due 或 unavailable 是否阻断 Check 的配置模式。 */
   readonly mode: MaintenanceReminderMode;
+  /** 未能测量的稳定机器可读原因。 */
   readonly reason: MaintenanceReminderUnavailableReason;
 }>;
 
@@ -72,6 +89,7 @@ export type MaintenanceReminderAssessment =
 
 /** `maintenance-reminders` 在 passed/failed outcome 中发布的主数据。 */
 export interface MaintenanceRemindersFinalData {
+  /** 每个已配置 reminder 的唯一 assessment，按 Definition 顺序发布。 */
   readonly entries: readonly MaintenanceReminderAssessment[];
 }
 

package/src/package-checks/maintenance-reminders/maintenance-reminders.ts

@@ -4,6 +4,11 @@ import {
   type CheckResult,
   type TypedCheckWithOptions
 } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckAuthoringOptions,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
 import {
   MAINTENANCE_REMINDER_UNAVAILABLE_REASON,
   parseMaintenanceRemindersData,
@@ -59,6 +64,14 @@ export interface MaintenanceReminderOptions {
   }>;
 }
 
+/** `maintenanceReminders` 的对象式构造输入，组合提醒政策与项目 Check 声明。 */
+export interface MaintenanceRemindersInput<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
+  /** 保留作者声明顺序的提醒政策条目。 */
+  readonly entries: readonly MaintenanceReminder[];
+}
+
 /** `maintenance-reminders` whole-Check unavailable outcome 的稳定 reason code。 */
 export type MaintenanceRemindersUnavailableCode =
   (typeof WHOLE_CHECK_UNAVAILABLE_CODE)[keyof typeof WHOLE_CHECK_UNAVAILABLE_CODE];
@@ -93,9 +106,9 @@ export type ReminderMeasurement =
   | Readonly<{ readonly kind: "succeeded"; readonly value: ReminderEvaluation }>;
 
 /**
- * 创建一个固定 ID 的普通 Check，并在其局部最终数据中评估多条维护提醒。
+ * 创建一个维护提醒普通 Check，并在其局部最终数据中评估多条维护提醒。
  *
- * @remarks 构造函数只接收项目无法可靠推断的提醒政策；它补齐 Git 可执行文件、身份、可见性和直接执行逻辑。返回值仍是普通 Check，可按现有原生对象组合规则替换完整 `options` 分支。
+ * @remarks 传入 entries 数组会保留默认 identity；对象输入可同时声明项目 Check 字段。构造函数补齐 Git 可执行文件、默认展示和直接执行逻辑，返回值仍是普通 Check，可按现有原生对象组合规则替换完整 `options` 分支。
  * @example 创建一个单一 Check 的维护提醒
  * ```ts
  * import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
@@ -136,13 +149,55 @@ export function maintenanceReminders(
   typeof MAINTENANCE_REMINDERS_CHECK_ID,
   MaintenanceReminderOptions,
   typeof parseMaintenanceRemindersData
-> {
+>;
+export function maintenanceReminders(
+  input: MaintenanceRemindersInput<typeof MAINTENANCE_REMINDERS_CHECK_ID>
+): TypedCheckWithOptions<
+  typeof MAINTENANCE_REMINDERS_CHECK_ID,
+  MaintenanceReminderOptions,
+  typeof parseMaintenanceRemindersData
+>;
+export function maintenanceReminders<const Id extends string>(
+  input: MaintenanceRemindersInput<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<Id, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export function maintenanceReminders(
+  input: MaintenanceRemindersInput
+): TypedCheckWithOptions<string, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export function maintenanceReminders(
+  input: readonly MaintenanceReminder[] | MaintenanceRemindersInput
+): TypedCheckWithOptions<string, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData> {
+  if (isMaintenanceReminderEntries(input)) {
+    return createMaintenanceRemindersCheck(
+      {
+        checkId: MAINTENANCE_REMINDERS_CHECK_ID,
+        displayName: "Maintenance reminders",
+        omitQuietPassedRow: true
+      },
+      input
+    );
+  }
+  const resolvedInput = resolveMaintenanceRemindersInput(input);
+  if (resolvedInput === undefined) {
+    throw new TypeError(
+      "maintenanceReminders input must be entries or a closed { entries, checkId?, displayName?, enabledByFlags?, checks?, dependsOn?, observes?, maxParallel?, admissionPriority?, mutex?, resourceClaims?, omitQuietPassedRow? } object"
+    );
+  }
+  return createMaintenanceRemindersCheck(resolvedInput.definition, resolvedInput.entries);
+}
+
+type PackageCheckDefinition<Id extends string> = NonNullable<
+  ReturnType<typeof resolvePackageCheckAuthoringInput<Id>>
+>["definition"];
+
+function createMaintenanceRemindersCheck<Id extends string>(
+  definition: PackageCheckDefinition<Id>,
+  entries: readonly MaintenanceReminder[]
+): TypedCheckWithOptions<Id, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData> {
   return defineCheck({
-    checkId: MAINTENANCE_REMINDERS_CHECK_ID,
-    displayName: "Maintenance reminders",
-    execution: executeMaintenanceReminders,
+    ...definition,
+    execute: executeMaintenanceReminders,
     parseData: parseMaintenanceRemindersData,
-    preflight: (options) =>
+    prepare: (options) =>
       validMaintenanceReminderOptions(options)
         ? { status: "success", preparedOptions: options }
         : {
@@ -161,9 +216,34 @@ export function maintenanceReminders(
     options: {
       entries,
       git: { executable: "git" }
-    },
-    visibility: "attention"
+    }
+  });
+}
+
+function isMaintenanceReminderEntries(
+  input: readonly MaintenanceReminder[] | MaintenanceRemindersInput
+): input is readonly MaintenanceReminder[] {
+  return Array.isArray(input);
+}
+
+function resolveMaintenanceRemindersInput<Id extends string>(
+  input: MaintenanceRemindersInput<Id>
+):
+  | Readonly<{
+      readonly definition: PackageCheckDefinition<Id>;
+      readonly entries: readonly MaintenanceReminder[];
+    }>
+  | undefined {
+  const resolved = resolvePackageCheckAuthoringInput(input, ["entries"], {
+    checkId: MAINTENANCE_REMINDERS_CHECK_ID,
+    displayName: "Maintenance reminders",
+    omitQuietPassedRow: true
   });
+  if (resolved === undefined) return undefined;
+  const entries = resolved.domainOptions.entries;
+  if (!Array.isArray(entries)) return undefined;
+  const reminderEntries: readonly MaintenanceReminder[] = entries;
+  return Object.freeze({ definition: resolved.definition, entries: reminderEntries });
 }
 
 /** 在普通对象组合后验证完整的选项形状。 */

package/src/package-checks/maintenance-reminders/maintenance-support.ts

@@ -51,9 +51,9 @@ export async function runGit(input: {
       }
       stdout += text;
     });
-    child.once("error", () =>
-      settle(input.signal.aborted ? { kind: "cancelled" } : { kind: "failed" })
-    );
+    child.once("error", () => {
+      settle(input.signal.aborted ? { kind: "cancelled" } : { kind: "failed" });
+    });
     child.once("close", (status) => {
       if (input.signal.aborted) {
         settle({ kind: "cancelled" });