@zxyycom/vibe-check 0.0.1

package/types/package-checks/host-environment/process/contract.d.ts

@@ -0,0 +1,50 @@
+import type { SyncOptions } from "execa";
+export declare const DEFAULT_PROCESS_MAX_BUFFER_BYTES: number;
+export interface ProcessFailure extends Error {
+    code?: number | string | null;
+    signal?: NodeJS.Signals | null;
+    status?: number | null;
+    stderr?: Buffer | string;
+    stdout?: Buffer | string;
+}
+export type ProcessResult = {
+    readonly error?: Error;
+    readonly signal: NodeJS.Signals | null;
+    readonly status: number | null;
+    readonly stderr: string;
+    readonly stdout: string;
+};
+export type RunProcessSyncOptions = {
+    readonly args: readonly string[];
+    readonly command: string;
+    readonly cwd?: string | URL;
+    readonly encoding?: SyncOptions["encoding"];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly maxBuffer?: number;
+    readonly stdio?: SyncOptions["stdio"];
+    readonly timeout?: number;
+    readonly windowsHide?: boolean;
+};
+export type RunProcessOptions = {
+    readonly args?: readonly string[];
+    readonly command: string;
+    readonly cwd?: string | URL;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly label?: string;
+    readonly maxBuffer?: number;
+    readonly timeout?: number;
+    readonly windowsHide?: boolean;
+};
+export type ExecaResultLike = {
+    readonly code?: string;
+    readonly exitCode?: number;
+    readonly failed?: boolean;
+    readonly isMaxBuffer?: boolean;
+    readonly message?: string;
+    readonly originalMessage?: string;
+    readonly shortMessage?: string;
+    readonly signal?: NodeJS.Signals;
+    readonly stderr?: unknown;
+    readonly stdout?: unknown;
+    readonly timedOut?: boolean;
+};

package/types/package-checks/host-environment/process/env.d.ts

@@ -0,0 +1,16 @@
+export declare const PLAIN_TEXT_PROCESS_ENV: Readonly<{
+    CARGO_TERM_COLOR: string;
+    CLICOLOR: string;
+    CLICOLOR_FORCE: string;
+    FORCE_COLOR: string;
+    NO_COLOR: string;
+    PNPM_CONFIG_COLOR: string;
+    PY_COLORS: string;
+    TERM: string;
+    UV_NO_COLOR: string;
+    npm_config_color: string;
+}>;
+export type PlainTextProcessEnvInput = {
+    readonly env?: NodeJS.ProcessEnv;
+};
+export declare function plainTextProcessEnv({ env }?: PlainTextProcessEnvInput): NodeJS.ProcessEnv;

package/types/package-checks/host-environment/process/failure.d.ts

@@ -0,0 +1,4 @@
+import type { ProcessFailure, ProcessResult } from "./contract.ts";
+export declare function processFailure(error: unknown): ProcessFailure;
+export declare function processFailureFromResult(result: ProcessResult): ProcessFailure | null;
+export declare function processFailed(result: Pick<ProcessResult, "error" | "status">): boolean;

package/types/package-checks/host-environment/process/result.d.ts

@@ -0,0 +1,2 @@
+import type { ExecaResultLike, ProcessResult } from "./contract.ts";
+export declare function toProcessResult(result: ExecaResultLike, label: string): ProcessResult;

package/types/package-checks/host-environment/process/runner.d.ts

@@ -0,0 +1,3 @@
+import { type ProcessResult, type RunProcessOptions, type RunProcessSyncOptions } from "./contract.ts";
+export declare function runProcessSync(options: RunProcessSyncOptions): ProcessResult;
+export declare function runProcess(options: RunProcessOptions): Promise<ProcessResult>;

package/types/package-checks/json-document/strict-document.d.ts

@@ -0,0 +1,35 @@
+export type JsonDocumentIssue = "too-large" | "bom" | "invalid-utf8" | "invalid-json" | "duplicate-key";
+/**
+ * A strict JSON value retained only inside Product source boundaries.
+ * Objects have a null prototype and every aggregate is frozen, so document keys cannot affect ambient prototypes.
+ */
+export type StrictJsonArray = readonly StrictJsonValue[];
+export interface StrictJsonObject {
+    readonly [key: string]: StrictJsonValue;
+}
+export type StrictJsonValue = null | boolean | number | string | StrictJsonArray | StrictJsonObject;
+export type StrictJsonDocumentResult = Readonly<{
+    readonly kind: "valid";
+    readonly jsonValue: StrictJsonValue;
+}> | Readonly<{
+    readonly kind: "issue";
+    readonly reason: JsonDocumentIssue;
+}> | Readonly<{
+    readonly kind: "unavailable";
+}>;
+interface StrictJsonDocumentReadInput {
+    readonly filePath: string;
+    /** Normally validated at the Check options boundary; malformed private input becomes unavailable. */
+    readonly maximumBytes: number;
+}
+/**
+ * Reads one approved file with a byte limit, then applies the strict JSON document contract.
+ * The caller owns exact-input authorization and maps `unavailable` to its Check outcome.
+ */
+export declare function readStrictJsonDocument(input: StrictJsonDocumentReadInput): StrictJsonDocumentResult;
+/**
+ * Applies strict JSON grammar and duplicate-key semantics to already bounded bytes.
+ * This is package-private so controlled remote schema bytes use the same boundary as local files.
+ */
+export declare function inspectStrictJsonBytes(bytes: Uint8Array): StrictJsonDocumentResult;
+export {};

package/types/package-checks/json-schema-validation/default-check.d.ts

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseJsonSchemaValidationData } from "./final-data.ts";
+import type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions } from "./options.ts";
+/**
+ * 使用可省略的 file、identity、reference、schema 与 binding policy 构造 Check。
+ *
+ * @param options - 省略顶层字段和 file fields 使用 package defaults；显式数组是完整替换值。
+ * @returns 固定 `json-schema-validation` identity、完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} input 不符合 closed authoring policy、identity 或 binding 不变量时抛出。
+ */
+export declare function jsonSchemaValidation(options?: JsonSchemaValidationOptions): TypedCheckWithOptions<"json-schema-validation", ResolvedJsonSchemaValidationOptions, typeof parseJsonSchemaValidationData>;

package/types/package-checks/json-schema-validation/execution-stages.d.ts

@@ -0,0 +1,27 @@
+import type { CheckExecutionContext } from "../../check/check.ts";
+import { type CompiledSchemaSet, type LoadedSchema } from "./schema-engine.ts";
+import type { SchemaIssueCollector } from "./issue-collector.ts";
+import type { JsonSchemaValidationUnavailableCode } from "./json-schema-validation.ts";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+type UnavailableStage = Readonly<{
+    readonly code: JsonSchemaValidationUnavailableCode;
+    readonly kind: "unavailable";
+}>;
+type Stage<T> = Readonly<{
+    readonly kind: "complete";
+    readonly value: T;
+}> | UnavailableStage;
+export interface LoadedSchemaStage {
+    readonly failures: ReadonlySet<string>;
+    readonly schemas: readonly LoadedSchema[];
+}
+export interface BindingCounts {
+    readonly blockedBindingCount: number;
+    readonly invalidBindingCount: number;
+    readonly validBindingCount: number;
+}
+type SchemaContext = CheckExecutionContext<ResolvedJsonSchemaValidationOptions>;
+export declare function loadConfiguredSchemas(context: SchemaContext, selectedPaths: ReadonlySet<string>, issueCollector: SchemaIssueCollector): Promise<Stage<LoadedSchemaStage>>;
+export declare function reportCompilationFailures(context: SchemaContext, compiled: CompiledSchemaSet, failures: Set<string>, issueCollector: SchemaIssueCollector): void;
+export declare function validateSchemaBindings(context: SchemaContext, selectedPaths: ReadonlySet<string>, compiled: CompiledSchemaSet, schemaFailures: ReadonlySet<string>, issueCollector: SchemaIssueCollector): Promise<Stage<BindingCounts>>;
+export {};

package/types/package-checks/json-schema-validation/final-data.d.ts

@@ -0,0 +1,15 @@
+/** 单次运行最多发布的 JSON Schema issue Record 数量。 */
+export declare const MAX_REPORTED_JSON_SCHEMA_ISSUES = 100;
+/** `json-schema-validation` 在 passed/failed outcome 中发布的主数据。 */
+export interface JsonSchemaValidationFinalData {
+    readonly bindingCount: number;
+    readonly blockedBindingCount: number;
+    readonly invalidBindingCount: number;
+    readonly issueCount: number;
+    readonly issuesTruncated: boolean;
+    readonly reportedIssueCount: number;
+    readonly schemaCount: number;
+    readonly validBindingCount: number;
+}
+/** 验证计数与截断不变量并脱离 canonical final data。 */
+export declare function parseJsonSchemaValidationData(data: unknown): JsonSchemaValidationFinalData;

package/types/package-checks/json-schema-validation/issue-collector.d.ts

@@ -0,0 +1,12 @@
+import type { CheckExecutionContext } from "../../check/check.ts";
+import type { JsonSchemaValidationRecordData } from "./json-schema-validation.ts";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+/** Owns the invocation-local issue count, display cap, and deterministic Record identity ordinal. */
+export declare class SchemaIssueCollector {
+    #private;
+    constructor(context: CheckExecutionContext<ResolvedJsonSchemaValidationOptions>);
+    get count(): number;
+    get reportedCount(): number;
+    get truncated(): boolean;
+    add(issue: JsonSchemaValidationRecordData): void;
+}

package/types/package-checks/json-schema-validation/json-schema-validation.d.ts

@@ -0,0 +1,42 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { JsonDocumentIssue } from "../json-document/strict-document.ts";
+import { type SchemaCompileReason } from "./schema-engine.ts";
+import { type JsonSchemaValidationFinalData } from "./final-data.ts";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+export declare const JSON_SCHEMA_VALIDATION_CHECK_DEFINITION: {
+    readonly checkId: "json-schema-validation";
+    readonly displayName: "JSON Schema validation";
+};
+/** `json-schema-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type JsonSchemaValidationUnavailableCode = "invalid-options" | "engine-unavailable" | "execution-cancelled" | "reference-transport-unavailable" | "scan-input-unavailable" | "document-unavailable";
+/** Schema 或 instance document Record 的稳定 document reason。 */
+export type JsonSchemaDocumentReason = JsonDocumentIssue | "out-of-scope";
+/** Schema/document Record 中带 `reason` branch 的稳定问题原因。 */
+export type JsonSchemaValidationRecordReason = JsonSchemaDocumentReason | SchemaCompileReason;
+/** 一条 schema document、compile、instance 或 keyword issue Record 的 data。 */
+export type JsonSchemaValidationRecordData = Readonly<{
+    readonly kind: "schema-document";
+    readonly path: string;
+    readonly reason: JsonSchemaDocumentReason;
+    readonly schemaId: string;
+}> | Readonly<{
+    readonly kind: "schema-compile";
+    readonly path: string;
+    readonly reason: SchemaCompileReason;
+    readonly schemaId: string;
+}> | Readonly<{
+    readonly bindingId: string;
+    readonly kind: "instance-document";
+    readonly path: string;
+    readonly reason: JsonSchemaDocumentReason;
+    readonly schemaId: string;
+}> | Readonly<{
+    readonly bindingId: string;
+    readonly keyword: string;
+    readonly kind: "keyword-violation";
+    readonly path: string;
+    readonly pointer: string;
+    readonly schemaId: string;
+}>;
+/** Validates only explicitly registered/bound JSON files inside the current global scan scope. */
+export declare function executeJsonSchemaValidation(context: CheckExecutionContext<ResolvedJsonSchemaValidationOptions>): Promise<CheckResult<JsonSchemaValidationFinalData>>;

package/types/package-checks/json-schema-validation/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+/** 将可省略 schema registry policy 物化为完整、冻结的 execution options。 */
+export declare function resolveJsonSchemaValidationOptions(value: unknown): ResolvedJsonSchemaValidationOptions | undefined;

package/types/package-checks/json-schema-validation/options-validation.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+export declare function validJsonSchemaValidationOptions(candidateOptions: unknown): candidateOptions is ResolvedJsonSchemaValidationOptions;

package/types/package-checks/json-schema-validation/options.d.ts

@@ -0,0 +1,53 @@
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+export type JsonSchemaIdentityMode = "require-match" | "configuration-authoritative" | "document-authoritative";
+export interface JsonSchemaIdentity {
+    readonly mode: JsonSchemaIdentityMode;
+}
+export type JsonSchemaReferenceSource = Readonly<{
+    readonly kind: "bundled";
+    readonly catalog: "json-schema-2020-12";
+}> | Readonly<{
+    readonly kind: "https";
+    readonly id: string;
+    readonly origin: string;
+    readonly pathPrefix: string;
+}>;
+export type JsonSchemaReferenceResolution = Readonly<{
+    readonly mode: "offline";
+}> | Readonly<{
+    readonly mode: "allowlisted";
+    readonly sources: readonly JsonSchemaReferenceSource[];
+}>;
+export interface RegisteredJsonSchema {
+    readonly id: string;
+    readonly path: string;
+}
+export interface JsonSchemaInstanceBinding {
+    readonly id: string;
+    readonly instancePath: string;
+    readonly schemaId: string;
+}
+/** `jsonSchemaValidation(options?)` 接受的可省略 authoring policy。 */
+export interface JsonSchemaValidationOptions {
+    /** schema/instance declarations 必须属于的 repository-file selection。 */
+    readonly files?: ProjectFileSelectionOptions;
+    /** 每个 local schema/instance document 允许的最大 raw byte 数；省略时为 1 MiB。 */
+    readonly maximumBytes?: number;
+    /** 整个 Check 共用的 schema root identity 规则；不得按 schema 混用。 */
+    readonly schemaIdentity?: JsonSchemaIdentity;
+    /** 默认离线；额外 schema source 必须显式 allowlist。 */
+    readonly referenceResolution?: JsonSchemaReferenceResolution;
+    /** 显式注册的 schema resources；ID 是 binding 和 public fact 使用的安全 authoring identity。 */
+    readonly schemas?: readonly RegisteredJsonSchema[];
+    /** 明确把一个由本 Check file selection 批准的 instance path 绑定到已声明 schema。 */
+    readonly bindings?: readonly JsonSchemaInstanceBinding[];
+}
+/** `json-schema-validation` execution 消费的完整、冻结 options。 */
+export interface ResolvedJsonSchemaValidationOptions {
+    readonly files: ProjectFileSelection;
+    readonly maximumBytes: number;
+    readonly schemaIdentity: JsonSchemaIdentity;
+    readonly referenceResolution: JsonSchemaReferenceResolution;
+    readonly schemas: readonly RegisteredJsonSchema[];
+    readonly bindings: readonly JsonSchemaInstanceBinding[];
+}

package/types/package-checks/json-schema-validation/reference-resolver.d.ts

@@ -0,0 +1,23 @@
+import type { AnySchemaObject } from "ajv";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import type { SchemaCompileReason } from "./schema-engine.ts";
+interface ControlledResolverInput {
+    readonly referenceResolution: ResolvedJsonSchemaValidationOptions["referenceResolution"];
+    readonly signal: AbortSignal;
+}
+export declare class ControlledReferenceResolver {
+    #private;
+    constructor(input: ControlledResolverInput);
+    load(referenceUri: string): Promise<AnySchemaObject>;
+    private queueLoad;
+    private loadUncached;
+    private loadWithController;
+    private isAllowedReference;
+}
+export declare class ReferenceResolutionFailure extends Error {
+    readonly reason: SchemaCompileReason;
+    constructor(reason: SchemaCompileReason);
+}
+export declare class ReferenceTransportFailure extends Error {
+}
+export {};

package/types/package-checks/json-schema-validation/remote-response.d.ts

@@ -0,0 +1,2 @@
+export declare function readBoundedResponse(response: Response, maximumBytes: number, signal: AbortSignal): Promise<Uint8Array | "too-large">;
+export declare function normalizeRemoteReference(referenceUri: string): string;

package/types/package-checks/json-schema-validation/schema-engine.d.ts

@@ -0,0 +1,33 @@
+import type { ErrorObject, ValidateFunction } from "ajv";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import type { StrictJsonValue } from "../json-document/strict-document.ts";
+export type SchemaCompileReason = "duplicate-engine-id" | "invalid-document-id" | "invalid-schema" | "missing-schema-id" | "schema-id-mismatch" | "unapproved-reference" | "unsupported-reference" | "remote-document-invalid" | "remote-schema-id-mismatch";
+export interface LoadedSchema {
+    readonly id: string;
+    readonly documentValue: StrictJsonValue;
+}
+export interface CompiledSchemaSet {
+    readonly failures: ReadonlyMap<string, SchemaCompileReason>;
+    readonly validators: ReadonlyMap<string, ValidateFunction>;
+}
+/** The only validation fields that may cross from the Ajv adapter to Check-owned Record settlement. */
+export interface NormalizedValidationError {
+    readonly keyword: string;
+    readonly pointer: string;
+}
+export type CompileSchemaSetResult = Readonly<{
+    readonly compiledSchemaSet: CompiledSchemaSet;
+    readonly kind: "settled";
+}> | Readonly<{
+    readonly kind: "unavailable";
+    readonly reason: "engine-unavailable" | "execution-cancelled" | "reference-transport-unavailable";
+}>;
+/** Compiles a closed set without exposing Ajv objects, errors, or resolved remote material to callers. */
+export declare function compileSchemaSet(input: {
+    readonly referenceResolution: ResolvedJsonSchemaValidationOptions["referenceResolution"];
+    readonly schemaIdentity: ResolvedJsonSchemaValidationOptions["schemaIdentity"];
+    readonly schemas: readonly LoadedSchema[];
+    readonly signal: AbortSignal;
+}): Promise<CompileSchemaSetResult>;
+/** Converts the only engine-visible error fields into fixed safe validation facts. */
+export declare function normalizeValidationErrors(errors: readonly ErrorObject[] | null | undefined): readonly NormalizedValidationError[];

package/types/package-checks/json-schema-validation/schema-policy.d.ts

@@ -0,0 +1,17 @@
+import type { AnySchema } from "ajv";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import type { LoadedSchema, SchemaCompileReason } from "./schema-engine.ts";
+import type { StrictJsonValue } from "../json-document/strict-document.ts";
+export interface PreparedSchema {
+    readonly authoringId: string;
+    readonly engineId: string;
+    readonly engineSchema: AnySchema;
+}
+export declare function prepareSchema(loadedSchema: LoadedSchema, mode: ResolvedJsonSchemaValidationOptions["schemaIdentity"]["mode"]): PreparedSchema | SchemaCompileReason;
+export declare function rejectDuplicateEngineIds(preparedSchemas: Map<string, PreparedSchema>, failures: Map<string, SchemaCompileReason>): void;
+/**
+ * Inspects only JSON Schema-bearing locations. Annotation payloads and property names are data, not keywords,
+ * so they must not be mistaken for `$ref`, `$dynamicRef`, or an Ajv extension.
+ */
+export declare function inspectSchemaPolicy(schemaValue: StrictJsonValue): SchemaCompileReason | undefined;
+export declare function isJsonObject(candidateValue: StrictJsonValue): candidateValue is Readonly<Record<string, StrictJsonValue>>;

package/types/package-checks/json-validation/default-check.d.ts

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseJsonValidationData } from "./final-data.ts";
+import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./options.ts";
+/**
+ * 使用可省略的文件范围与 byte limit 构造严格 JSON document Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
+ * @returns 固定 `json-validation` identity、完整冻结 options、final-data parser 与执行逻辑。
+ * @throws {TypeError} input 含未知字段、非法文件选择或非法 byte limit 时抛出。
+ */
+export declare function jsonValidation(options?: JsonValidationOptions): TypedCheckWithOptions<"json-validation", ResolvedJsonValidationOptions, typeof parseJsonValidationData>;

package/types/package-checks/json-validation/final-data.d.ts

@@ -0,0 +1,10 @@
+/** `json-validation` 在 passed/failed outcome 中发布的主数据。 */
+export interface JsonValidationFinalData {
+    readonly scannedFileCount: number;
+    readonly validFileCount: number;
+    readonly invalidFileCount: number;
+    readonly issueCount: number;
+    readonly rejectedInputCount: number;
+}
+/** 验证计数不变量并脱离一份 `json-validation` canonical final-data object。 */
+export declare function parseJsonValidationData(data: unknown): JsonValidationFinalData;

package/types/package-checks/json-validation/json-validation.d.ts

@@ -0,0 +1,28 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { type JsonDocumentIssue } from "../json-document/strict-document.ts";
+import type { JsonValidationFinalData } from "./final-data.ts";
+import type { ResolvedJsonValidationOptions } from "./options.ts";
+export declare const JSON_VALIDATION_CHECK_DEFINITION: {
+    readonly checkId: "json-validation";
+    readonly displayName: "JSON validation";
+};
+/** `json-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type JsonValidationUnavailableCode = "invalid-options" | "document-unavailable" | "execution-cancelled" | "scan-input-unavailable";
+/** Validates the lower-case JSON subset selected by this Check's options. */
+export declare function executeJsonValidation(context: CheckExecutionContext<ResolvedJsonValidationOptions>): CheckResult<JsonValidationFinalData>;
+/** 一条 invalid JSON document supplemental Record 的 data。 */
+export interface JsonValidationDocumentRecordData {
+    readonly path: string;
+    readonly reason: JsonValidationRecordReason;
+}
+/** 一条 files policy 已选中但不受 JSON validation 支持的输入 Finding。 */
+export interface JsonValidationInputRejectedRecordData {
+    readonly blocking: false;
+    readonly kind: "input-rejected";
+    readonly path: string;
+    readonly reason: "unsupported-file-type";
+}
+/** JSON validation 发布的 document issue 或 input-rejection Record data。 */
+export type JsonValidationRecordData = JsonValidationDocumentRecordData | JsonValidationInputRejectedRecordData;
+/** JSON document Record 的稳定问题原因。 */
+export type JsonValidationRecordReason = JsonDocumentIssue;

package/types/package-checks/json-validation/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedJsonValidationOptions } from "./options.ts";
+/** 将可省略 JSON validation policy 物化为完整、冻结的 execution options。 */
+export declare function resolveJsonValidationOptions(value: unknown): ResolvedJsonValidationOptions | undefined;

package/types/package-checks/json-validation/options-validation.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedJsonValidationOptions } from "./options.ts";
+export declare function validJsonValidationOptions(value: unknown): value is ResolvedJsonValidationOptions;

package/types/package-checks/json-validation/options.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+/** `jsonValidation(options?)` 接受的可省略 authoring policy。 */
+export interface JsonValidationOptions {
+    /** 参与本 Check 的 repository-file selection；省略字段使用 package defaults。 */
+    readonly files?: ProjectFileSelectionOptions;
+    /** 单个 JSON document 允许的最大 raw byte 数；省略时为 1 MiB。 */
+    readonly maximumBytes?: number;
+}
+/** `json-validation` execution 消费的完整、冻结 options。 */
+export interface ResolvedJsonValidationOptions {
+    readonly files: ProjectFileSelection;
+    readonly maximumBytes: number;
+}

package/types/package-checks/maintenance-reminders/assessment-results.d.ts

@@ -0,0 +1,10 @@
+import type { CheckResult } from "../../check/check.ts";
+import type { MaintenanceReminder, MaintenanceRemindersUnavailableCode, ReminderEvaluation, ReminderMeasurement, FirstParentHistoryResolution, FirstParentHistoryUnavailableReason } from "./maintenance-reminders.ts";
+import type { MaintenanceReminderAssessment, MaintenanceReminderMode, MaintenanceReminderUnavailableReason, MaintenanceRemindersFinalData, UnavailableMaintenanceReminderAssessment } from "./final-data.ts";
+export declare function completedResult(evaluations: readonly ReminderEvaluation[]): CheckResult<MaintenanceRemindersFinalData>;
+export declare function unavailableResult(code: MaintenanceRemindersUnavailableCode): CheckResult<MaintenanceRemindersFinalData>;
+export declare function unavailableAssessment(entry: Readonly<MaintenanceReminder>, headCommit: string | null, reason: MaintenanceReminderUnavailableReason): UnavailableMaintenanceReminderAssessment;
+export declare function modeOf(entry: Readonly<MaintenanceReminder>): MaintenanceReminderMode;
+export declare function unavailableHistory(reason: FirstParentHistoryUnavailableReason): FirstParentHistoryResolution;
+export declare function reminderEvaluation(entry: Readonly<MaintenanceReminder>, assessment: MaintenanceReminderAssessment): ReminderEvaluation;
+export declare function completedMeasurement(entry: Readonly<MaintenanceReminder>, assessment: MaintenanceReminderAssessment): ReminderMeasurement;

package/types/package-checks/maintenance-reminders/final-data.d.ts

@@ -0,0 +1,47 @@
+/** 单条维护提醒无法测量时使用的稳定 reason code。 */
+export declare const MAINTENANCE_REMINDER_UNAVAILABLE_REASON: Readonly<{
+    readonly baseCommitUnavailable: "base-commit-unavailable";
+    readonly baseNotFirstParentAncestor: "base-not-first-parent-ancestor";
+    readonly firstParentHistoryInvalid: "first-parent-history-invalid";
+    readonly firstParentHistoryUnavailable: "first-parent-history-unavailable";
+    readonly headInvalid: "head-invalid";
+    readonly headUnavailable: "head-unavailable";
+    readonly numstatInvalid: "numstat-invalid";
+    readonly numstatUnavailable: "numstat-unavailable";
+}>;
+export type MaintenanceReminderMode = "advisory" | "enforcing";
+/** 单条维护提醒无法测量时保留在 final data 中的稳定 reason。 */
+export type MaintenanceReminderUnavailableReason = (typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON)[keyof typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON];
+/** 判断 unknown value 是否为维护提醒的稳定局部 ID。 */
+export declare function isMaintenanceReminderId(value: unknown): value is string;
+/** 判断 unknown value 是否为 Git 的完整 SHA-1 或 SHA-256 commit ID。 */
+export declare function isMaintenanceCommitId(value: unknown): value is string;
+export type MeasuredMaintenanceReminderAssessment = Readonly<{
+    readonly assessment: "clear" | "due";
+    readonly baseCommit: string;
+    readonly changedLines: number;
+    readonly commitCount: number;
+    readonly exceeded: readonly ("commits" | "changed-lines")[];
+    readonly headCommit: string;
+    readonly id: string;
+    readonly mode: MaintenanceReminderMode;
+}>;
+export type UnavailableMaintenanceReminderAssessment = Readonly<{
+    readonly assessment: "unavailable";
+    readonly baseCommit: string;
+    readonly changedLines: null;
+    readonly commitCount: null;
+    readonly exceeded: readonly [];
+    readonly headCommit: string | null;
+    readonly id: string;
+    readonly mode: MaintenanceReminderMode;
+    readonly reason: MaintenanceReminderUnavailableReason;
+}>;
+/** 单条维护提醒的 measured 或 unavailable discriminated assessment。 */
+export type MaintenanceReminderAssessment = MeasuredMaintenanceReminderAssessment | UnavailableMaintenanceReminderAssessment;
+/** `maintenance-reminders` 在 passed/failed outcome 中发布的主数据。 */
+export interface MaintenanceRemindersFinalData {
+    readonly entries: readonly MaintenanceReminderAssessment[];
+}
+/** 验证 discriminated entry assessments 并脱离 canonical final data。 */
+export declare function parseMaintenanceRemindersData(data: unknown): MaintenanceRemindersFinalData;

package/types/package-checks/maintenance-reminders/maintenance-reminders.d.ts

@@ -0,0 +1,111 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { MAINTENANCE_REMINDER_UNAVAILABLE_REASON, parseMaintenanceRemindersData, type MaintenanceReminderAssessment } from "./final-data.ts";
+export declare const MAINTENANCE_REMINDERS_CHECK_ID = "maintenance-reminders";
+declare const WHOLE_CHECK_UNAVAILABLE_CODE: Readonly<{
+    invalidOptions: "invalid-options";
+    executionCancelled: "execution-cancelled";
+    internalFailure: "maintenance-reminders-internal-failure";
+}>;
+/** 一项维护提醒的项目政策输入。 */
+export interface MaintenanceReminder {
+    /** 在同一次构造函数调用中唯一的小写短横线命名局部标识。 */
+    readonly id: string;
+    /** 维护者在完成真实复核后手动推进的不可变完整 Git commit ID。 */
+    readonly baseCommit: string;
+    /** 超过任一已配置上限时触发该提醒。 */
+    readonly limits: Readonly<{
+        /** 从基线到 `HEAD` 的 `first-parent` 提交数上限。 */
+        readonly commits?: number;
+        /** 从基线到 `HEAD` 的累计 Git `numstat` 增加行加删除行上限。 */
+        readonly changedLines?: number;
+    }>;
+    /** 到期或无法评估时展示给人的非空提醒正文。 */
+    readonly message: string;
+    /** 省略时只提示；`enforcing` 会使到期或不可测量的条目令所属 Check 失败。 */
+    readonly mode?: "advisory" | "enforcing";
+}
+/** `maintenanceReminders` 生成且完全由 Check 持有的选项。 */
+export interface MaintenanceReminderOptions {
+    /** 保留作者声明顺序的提醒政策条目。 */
+    readonly entries: readonly MaintenanceReminder[];
+    /** 执行已提交历史测量的 Git 可执行文件。 */
+    readonly git: Readonly<{
+        readonly executable: string;
+    }>;
+}
+/** `maintenance-reminders` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MaintenanceRemindersUnavailableCode = (typeof WHOLE_CHECK_UNAVAILABLE_CODE)[keyof typeof WHOLE_CHECK_UNAVAILABLE_CODE];
+export type FirstParentHistoryUnavailableReason = typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryInvalid | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryUnavailable | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headInvalid | typeof MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headUnavailable;
+export type ReminderEvaluation = Readonly<{
+    readonly assessment: MaintenanceReminderAssessment;
+    readonly message: string;
+}>;
+export type GitCommandResult = Readonly<{
+    readonly kind: "cancelled";
+}> | Readonly<{
+    readonly kind: "failed";
+}> | Readonly<{
+    readonly kind: "succeeded";
+    readonly stdout: string;
+}>;
+export type FirstParentHistory = Readonly<{
+    readonly commits: readonly string[];
+    readonly headCommit: string;
+}>;
+export type FirstParentHistoryResolution = Readonly<{
+    readonly kind: "cancelled";
+}> | Readonly<{
+    readonly kind: "unavailable";
+    readonly reason: FirstParentHistoryUnavailableReason;
+}> | Readonly<{
+    readonly kind: "succeeded";
+    readonly value: FirstParentHistory;
+}>;
+export type ReminderMeasurement = Readonly<{
+    readonly kind: "cancelled";
+}> | Readonly<{
+    readonly kind: "succeeded";
+    readonly value: ReminderEvaluation;
+}>;
+/**
+ * 创建一个固定 ID 的普通 Check，并在其局部最终数据中评估多条维护提醒。
+ *
+ * @remarks 构造函数只接收项目无法可靠推断的提醒政策；它补齐 Git 可执行文件、身份、可见性和直接执行逻辑。返回值仍是普通 Check，可按现有原生对象组合规则替换完整 `options` 分支。
+ * @example 创建一个单一 Check 的维护提醒
+ * ```ts
+ * import { defineConfig, maintenanceReminders, run } from "@zxyycom/vibe-check";
+ *
+ * // 下列 baseCommit 都是示例占位值；实际使用时，每条都必须替换为该提醒最近一次真实复核对应的完整 commit ID。
+ * const maintenance = maintenanceReminders([
+ *   {
+ *     id: "documentation-review",
+ *     baseCommit: "0123456789abcdef0123456789abcdef01234567",
+ *     limits: { commits: 40, changedLines: 2_000 },
+ *     message: "Review the documentation structure after this body of change."
+ *   },
+ *   {
+ *     id: "optimization-audit",
+ *     baseCommit: "89abcdef0123456789abcdef0123456789abcdef",
+ *     limits: { commits: 80 },
+ *     message: "Audit optimization quality before this becomes older.",
+ *     mode: "enforcing"
+ *   }
+ * ]);
+ *
+ * const definition = defineConfig({
+ *   checks: [maintenance],
+ *   outputs: {
+ *     diagnosticLogging: { enabled: false },
+ *     machinePublication: { enabled: false },
+ *     progressRendering: { enabled: false }
+ *   }
+ * });
+ *
+ * const result = await run(definition);
+ * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+ * ```
+ */
+export declare function maintenanceReminders(entries: readonly MaintenanceReminder[]): TypedCheckWithOptions<typeof MAINTENANCE_REMINDERS_CHECK_ID, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+/** 在普通对象组合后验证完整的选项形状。 */
+export declare function validMaintenanceReminderOptions(value: unknown): value is MaintenanceReminderOptions;
+export {};

package/types/package-checks/maintenance-reminders/maintenance-support.d.ts

@@ -0,0 +1,7 @@
+import type { GitCommandResult } from "./maintenance-reminders.ts";
+export declare function runGit(input: {
+    readonly args: readonly string[];
+    readonly executable: string;
+    readonly projectRoot: string;
+    readonly signal: AbortSignal;
+}): Promise<GitCommandResult>;