@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,34 +1,63 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
-export type JsonSchemaIdentityMode = "require-match" | "configuration-authoritative" | "document-authoritative";
+/** 已注册 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;
 }
-export type JsonSchemaReferenceSource = Readonly<{
+/** 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;
 }>;
-export type JsonSchemaReferenceResolution = Readonly<{
+/** 本次 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/types/package-checks/json-validation/default-check.d.ts

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseJsonValidationData } from "./final-data.ts";
 import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./options.ts";
 /**
@@ -8,4 +9,6 @@ import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./opt
  * @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>;
+export declare function jsonValidation(options?: JsonValidationOptions<"json-validation">): TypedCheckWithOptions<"json-validation", ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export declare function jsonValidation<const Id extends string>(options: JsonValidationOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;
+export declare function jsonValidation(options: JsonValidationOptions): TypedCheckWithOptions<string, ResolvedJsonValidationOptions, typeof parseJsonValidationData>;

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

@@ -1,9 +1,14 @@
 /** `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;
 }
 /** 验证计数不变量并脱离一份 `json-validation` canonical final-data object。 */

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

@@ -1,6 +1,7 @@
+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/types/package-checks/local-cache-options.d.ts

@@ -0,0 +1,9 @@
+/** 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 declare function resolveOptionalLocalCacheOptions(value: unknown): LocalCacheOptions | undefined;
+export declare function validLocalCacheOptions(value: unknown): value is LocalCacheOptions;

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

@@ -17,30 +17,48 @@ 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<{
+    /** 未超过任何阈值时为 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;
 }>;
 /** 单条维护提醒的 measured 或 unavailable discriminated assessment。 */
 export type MaintenanceReminderAssessment = MeasuredMaintenanceReminderAssessment | UnavailableMaintenanceReminderAssessment;
 /** `maintenance-reminders` 在 passed/failed outcome 中发布的主数据。 */
 export interface MaintenanceRemindersFinalData {
+    /** 每个已配置 reminder 的唯一 assessment，按 Definition 顺序发布。 */
     readonly entries: readonly MaintenanceReminderAssessment[];
 }
 /** 验证 discriminated entry assessments 并脱离 canonical final data。 */

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

@@ -1,4 +1,5 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckAuthoringOptions, type PackageCheckIdentityInput } from "../check-authoring.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<{
@@ -33,6 +34,11 @@ export interface MaintenanceReminderOptions {
         readonly executable: string;
     }>;
 }
+/** `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];
 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;
@@ -68,9 +74,9 @@ export type ReminderMeasurement = Readonly<{
     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";
@@ -106,6 +112,9 @@ export type ReminderMeasurement = Readonly<{
  * ```
  */
 export declare function maintenanceReminders(entries: readonly MaintenanceReminder[]): TypedCheckWithOptions<typeof MAINTENANCE_REMINDERS_CHECK_ID, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders(input: MaintenanceRemindersInput<typeof MAINTENANCE_REMINDERS_CHECK_ID>): TypedCheckWithOptions<typeof MAINTENANCE_REMINDERS_CHECK_ID, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders<const Id extends string>(input: MaintenanceRemindersInput<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
+export declare function maintenanceReminders(input: MaintenanceRemindersInput): TypedCheckWithOptions<string, MaintenanceReminderOptions, typeof parseMaintenanceRemindersData>;
 /** 在普通对象组合后验证完整的选项形状。 */
 export declare function validMaintenanceReminderOptions(value: unknown): value is MaintenanceReminderOptions;
 export {};

package/types/package-checks/markdown-link-validation/default-check.d.ts

@@ -1,18 +1,25 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseMarkdownLinkValidationData } from "./final-data.ts";
 import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 /**
  * 使用可省略的 source、target 与 work-limit policy 构造离线 Markdown 引用 Check。
  *
- * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略。
+ * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略；cache 省略时关闭，启用时由调用方提供 absolute、可信且可删除的 directory，其中本 Check 只维护一个 source-derived JSONL local state；调用方负责容量和删除，cache 不可用不改变 Check 结果。
  * @returns 固定 `markdown-link-validation` identity、完整冻结 options、parser 与执行逻辑。
- * @throws {TypeError} input 含未知字段、非法 target policy 或非法 work limit 时抛出。
+ * @throws {TypeError} input 含未知字段、非法 target policy、cache branch/directory 或非法 work limit 时抛出。
  * @example 离线 Markdown 本地链接完整性
  * ```ts
  * import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
  *
+ * // 此调用方自有目录是 absolute、可删除的，并且可能保存 source-derived parse facts。
+ * const cacheDirectory = new URL(".vibe-check/markdown-link-parse-cache", import.meta.url).pathname;
  * const definition = defineConfig({
- *   checks: [markdownLinkValidation()],
+ *   checks: [
+ *     markdownLinkValidation({
+ *       cache: { enabled: true, directory: cacheDirectory }
+ *     })
+ *   ],
  *   outputs: {
  *     diagnosticLogging: { enabled: false },
  *     machinePublication: { enabled: false },
@@ -24,4 +31,6 @@ import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptio
  * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
  * ```
  */
-export declare function markdownLinkValidation(options?: MarkdownLinkValidationOptions): TypedCheckWithOptions<"markdown-link-validation", ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation(options?: MarkdownLinkValidationOptions<"markdown-link-validation">): TypedCheckWithOptions<"markdown-link-validation", ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation<const Id extends string>(options: MarkdownLinkValidationOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;
+export declare function markdownLinkValidation(options: MarkdownLinkValidationOptions): TypedCheckWithOptions<string, ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;

package/types/package-checks/markdown-link-validation/execution.d.ts

@@ -1,12 +1,10 @@
 import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
-import { type MarkdownLocalResolutionReason, type MarkdownSourceReadFailureReason } from "./local-resolver.ts";
 import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+export type { MarkdownLinkValidationUnavailableReason } from "./unavailable-reasons.ts";
 export declare const MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION: {
     readonly checkId: "markdown-link-validation";
     readonly displayName: "Markdown link validation";
 };
-/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
-export type MarkdownLinkValidationUnavailableReason = "invalid-options" | "cancelled" | "occurrence-limit-exceeded" | "project-root-unavailable" | MarkdownLocalResolutionReason | MarkdownSourceReadFailureReason;
 /** 验证本 Check 选中的 Markdown source 的离线本地链接完整性。 */
 export declare function executeMarkdownLinkValidation(context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>): Promise<CheckResult<MarkdownLinkValidationFinalData>>;

package/types/package-checks/markdown-link-validation/final-data.d.ts

@@ -1,9 +1,14 @@
 /** `markdown-link-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface MarkdownLinkValidationFinalData {
+    /** 已成功读取并完成 Markdown link occurrence 提取的 source 文件数。 */
     readonly sourceFileCount: number;
+    /** 从已处理 source 中提取的 semantic link occurrence 数。 */
     readonly occurrenceCount: number;
+    /** 进入 direct endpoint validation 的 logical occurrence 数，包括 target memo hit。 */
     readonly targetReadCount: number;
+    /** occurrence finding 与 rejected input 的合计数。 */
     readonly findingCount: number;
+    /** files policy 已选中、但因不是 `.md`/`.markdown` path 而被拒绝的输入数。 */
     readonly rejectedInputCount: number;
 }
 /** 验证计数不变量并脱离一份 canonical final-data object。 */

package/types/package-checks/markdown-link-validation/finding-messages.d.ts

@@ -0,0 +1,4 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { MarkdownLinkRecordCandidate } from "./records.ts";
+/** Projects completed Link findings without copying raw destinations into presentation. */
+export declare function markdownFindingMessages(candidates: readonly MarkdownLinkRecordCandidate[], rejectedPaths: readonly string[], blocking: boolean): readonly CheckMessage[];

package/types/package-checks/markdown-link-validation/local-resolution.d.ts

@@ -11,6 +11,7 @@ interface MarkdownLinkSource {
 interface MarkdownLocalResolver {
     readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
     resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    finalize(): Promise<void>;
     readonly targetReadCount: number;
 }
 interface MarkdownLocalResolutionRequest {
@@ -62,18 +63,23 @@ interface ParsedLocalDestination {
     readonly fragment: string | null;
     readonly isAbsolute: boolean;
 }
-interface RootContainedPath {
-    readonly kind: "contained" | "missing";
+type RootProbe = Readonly<{
+    readonly kind: "contained";
     readonly absolutePath: string;
-}
-type RootProbe = RootContainedPath | Readonly<{
+    /** The final component observation is present when containment walked it. */
+    readonly endpoint?: ExistingEndpointProbe;
+}> | Readonly<{
+    readonly kind: "missing";
+    readonly absolutePath: string;
+}> | Readonly<{
     readonly kind: "outside";
 }> | Readonly<{
     readonly kind: "unavailable";
 }>;
 type EndpointProbe = Readonly<{
     readonly kind: "missing";
-}> | Readonly<{
+}> | ExistingEndpointProbe;
+type ExistingEndpointProbe = Readonly<{
     readonly kind: "directory" | "file" | "unsupported" | "unavailable";
 }>;
 export declare function parseLocalDestination(rawDestination: string): ParsedLocalDestination | "not-local" | null;
@@ -89,4 +95,4 @@ export declare function sourceUnavailable(): MarkdownSourceReadResult;
 export declare function valid(target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
 export declare function finding(reason: MarkdownLinkFindingReason, target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
 export declare function unavailable(reason: MarkdownLocalResolutionReason): MarkdownLocalResolution;
-export type { MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownLocalResolutionRequest, MarkdownSafeTargetDescriptor, MarkdownSourceReadResult, MarkdownSourceReadFailureReason, RootProbe, EndpointProbe, RootExternalTargetMode };
+export type { MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownLocalResolutionRequest, MarkdownSafeTargetDescriptor, MarkdownSourceReadResult, MarkdownSourceReadFailureReason, RootProbe, EndpointProbe, ExistingEndpointProbe, RootExternalTargetMode };

package/types/package-checks/markdown-link-validation/local-resolver.d.ts

@@ -1,5 +1,6 @@
 import type { MarkdownLocalResolverCreation } from "./local-resolution.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 /** Link-private, per-invocation state for source reads and direct local targets. */
-export declare function createMarkdownLocalResolver(projectRoot: string, maxTargetReads: number): Promise<MarkdownLocalResolverCreation>;
+export declare function createMarkdownLocalResolver(projectRoot: string, maxTargetReads: number, cache: ResolvedMarkdownLinkValidationOptions["cache"], signal: AbortSignal): Promise<MarkdownLocalResolverCreation>;
 export { anchorResolution, finding, isMarkdownPath, isNotFound, isRootRelativePath, isWithinRoot, parseLocalDestination, relativeSegments, sameRootRelativePath, sourceUnavailable, toSlashPath, unavailable, valid } from "./local-resolution.ts";
 export type { EndpointProbe, MarkdownLinkFindingReason, MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolutionRequest, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownSafeTargetDescriptor, MarkdownSourceReadFailureReason, MarkdownSourceReadResult, RootExternalTargetMode, RootProbe } from "./local-resolution.ts";

package/types/package-checks/markdown-link-validation/options.d.ts

@@ -1,6 +1,10 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { LocalCacheOptions } from "../local-cache-options.ts";
 export type MarkdownRootExternalTargetMode = "ignore" | "report" | "validate";
+/** 调用方显式拥有的 Link-private parse-facts local cache policy。 */
+type MarkdownLinkValidationCacheOptions = LocalCacheOptions;
 /** 可省略的 Markdown validation work limits。 */
 export interface MarkdownLinkValidationLimitOptions {
     readonly maxMarkdownBytes?: number;
@@ -8,7 +12,7 @@ export interface MarkdownLinkValidationLimitOptions {
     readonly maxTargetReads?: number;
 }
 /** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */
-export interface MarkdownLinkValidationOptions {
+export interface MarkdownLinkValidationOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */
     readonly files?: ProjectFileSelectionOptions;
     /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */
@@ -25,6 +29,12 @@ export interface MarkdownLinkValidationOptions {
     readonly requireNonEmptyDirectories?: boolean;
     /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */
     readonly limits?: MarkdownLinkValidationLimitOptions;
+    /**
+     * 显式启用的、调用方拥有的 Link parse-facts persistent cache。省略时关闭；enabled directory 必须 absolute、可信且可删除。
+     * 本 Check 只在其中使用 `markdown-link-parse-facts-v1.jsonl` 保存 source-derived facts；调用方负责容量和删除，且不提供
+     * confidentiality、automatic cleanup、concurrency 或 durability guarantees。cache 不可用时 fresh-parse，Check 结果不变。
+     */
+    readonly cache?: MarkdownLinkValidationCacheOptions;
 }
 /** `markdown-link-validation` execution 消费的完整、冻结 options。 */
 export interface ResolvedMarkdownLinkValidationOptions {
@@ -35,9 +45,11 @@ export interface ResolvedMarkdownLinkValidationOptions {
     readonly validateCrossDocumentAnchors: boolean;
     readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;
     readonly requireNonEmptyDirectories: boolean;
+    readonly cache: MarkdownLinkValidationCacheOptions;
     readonly limits: Readonly<{
         readonly maxMarkdownBytes: number;
         readonly maxOccurrences: number;
         readonly maxTargetReads: number;
     }>;
 }
+export {};

package/types/package-checks/markdown-link-validation/parse-facts-cache-payload.d.ts

@@ -0,0 +1,24 @@
+import type { MarkdownHeading, MarkdownLinkOccurrence, ParsedMarkdownLinkFacts } from "./markdown-parser.ts";
+/** Version the resolver memo and persistent identity share when parser facts change. */
+export declare const MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION = "mdast-gfm-frontmatter-github-slug-v1";
+type MarkdownLinkParseFactsPayload = Readonly<{
+    readonly occurrences: readonly MarkdownLinkOccurrence[];
+    readonly headings: readonly MarkdownHeading[];
+}>;
+/**
+ * Serializes one complete Link-private JSONL envelope from immutable parser facts.
+ * The session owns when this line is appended; this codec owns its shape and identity.
+ */
+export declare function cacheEnvelopeLine(identityDigest: string, facts: ParsedMarkdownLinkFacts): string;
+/** Restores one complete, current-version JSONL envelope or rejects it as a cache miss. */
+export declare function parseCacheEnvelopeLine(line: string): Readonly<{
+    readonly identityDigest: string;
+    readonly facts: ParsedMarkdownLinkFacts;
+}> | undefined;
+/** SHA-256 identity over the current, exact authorized Markdown bytes. */
+export declare function markdownBytesDigest(bytes: Uint8Array): string;
+/** Converts parser-owned immutable facts to the closed persistent JSON payload. */
+export declare function projectMarkdownLinkParseFactsPayload(facts: ParsedMarkdownLinkFacts): MarkdownLinkParseFactsPayload;
+/** Strictly restores the Link-private persistent JSON payload to immutable parser facts. */
+export declare function parseMarkdownLinkParseFactsPayload(value: unknown): ParsedMarkdownLinkFacts;
+export {};

package/types/package-checks/markdown-link-validation/parse-facts-cache.d.ts

@@ -0,0 +1,13 @@
+import { type MarkdownLinkParseResult } from "./markdown-parser.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+/**
+ * Link-private state for one resolver invocation's parse-facts cache lifecycle.
+ * It restores at most once, collects successful fresh facts by identity, and
+ * publishes at the execution terminal boundary.
+ */
+export declare class MarkdownLinkParseFactsSession {
+    #private;
+    constructor(cache: ResolvedMarkdownLinkValidationOptions["cache"]);
+    parse(bytes: Uint8Array, signal: AbortSignal): Promise<MarkdownLinkParseResult | undefined>;
+    finalize(signal: AbortSignal): Promise<void>;
+}

package/types/package-checks/markdown-link-validation/resolver-engine.d.ts

@@ -1,13 +1,15 @@
-import { type MarkdownLocalResolution, type MarkdownLocalResolutionRequest, type MarkdownLocalResolver, type MarkdownSafeTargetDescriptor, type MarkdownSourceReadResult } from "./local-resolution.ts";
+import { type MarkdownLocalResolution, type MarkdownLocalResolutionRequest, type MarkdownLocalResolver, type MarkdownSafeTargetDescriptor, type EndpointProbe } from "./local-resolution.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 export declare class LinkLocalResolver implements MarkdownLocalResolver {
     #private;
-    constructor(canonicalProjectRoot: string, maxTargetReads: number);
+    constructor(canonicalProjectRoot: string, maxTargetReads: number, cache: ResolvedMarkdownLinkValidationOptions["cache"], signal: AbortSignal);
     get targetReadCount(): number;
-    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
+    finalize(): Promise<void>;
+    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<import("./local-resolution.ts").MarkdownSourceReadResult>;
     resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
     resolveRootContainedTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
     resolveExternalTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
-    resolveEndpoint(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
+    resolveEndpoint(endpoint: EndpointProbe, targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     resolveFile(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     resolveDirectory(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     beginTargetValidation(): boolean;

package/types/package-checks/markdown-link-validation/source-reader.d.ts

@@ -0,0 +1,11 @@
+import type { MarkdownLinkParseResult } from "./markdown-parser.ts";
+import { type MarkdownSourceReadResult } from "./local-resolution.ts";
+export interface RootContainedMarkdownSourceReadRequest {
+    readonly canonicalProjectRoot: string;
+    readonly maxMarkdownBytes: number;
+    readonly parseMarkdownBytes: (bytes: Uint8Array) => Promise<MarkdownLinkParseResult | undefined>;
+    readonly rootRelativePath: string;
+    readonly signal: AbortSignal;
+}
+/** Reads one authorized Markdown source without granting target-resolution behavior. */
+export declare function readRootContainedMarkdownSource(request: RootContainedMarkdownSourceReadRequest): Promise<MarkdownSourceReadResult>;

package/types/package-checks/markdown-link-validation/unavailable-reasons.d.ts

@@ -0,0 +1,4 @@
+import type { MarkdownLocalResolutionReason, MarkdownSourceReadFailureReason } from "./local-resolver.ts";
+/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MarkdownLinkValidationUnavailableReason = "invalid-options" | "cancelled" | "occurrence-limit-exceeded" | "project-root-unavailable" | MarkdownLocalResolutionReason | MarkdownSourceReadFailureReason;
+export declare function markdownLinkUnavailableMessage(reason: MarkdownLinkValidationUnavailableReason): string;

package/types/package-checks/markdown-lint/adapter.d.ts

@@ -0,0 +1,10 @@
+import { type MarkdownLintRuleName } from "./options.ts";
+export interface MarkdownLintBackendFinding {
+    readonly lineNumber: number;
+    readonly range: readonly [number, number] | null;
+    readonly rule: MarkdownLintRuleName;
+}
+/** Runs the fixed markdownlint Promise strings API and validates its raw protocol. */
+export declare function lintMarkdownString(sourcePath: string, sourceText: string, rules: readonly MarkdownLintRuleName[]): Promise<readonly MarkdownLintBackendFinding[] | "backend-failed" | "backend-protocol-invalid">;
+/** Validates one backend or restored-cache range against the current source line. */
+export declare function parseMarkdownLintRange(value: unknown, line: string): readonly [number, number] | null | undefined;

package/types/package-checks/markdown-lint/default-check.d.ts

@@ -0,0 +1,37 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
+import { parseMarkdownLintData } from "./final-data.ts";
+import type { MarkdownLintOptions, ResolvedMarkdownLintOptions } from "./options.ts";
+/**
+ * 构造使用稳定闭合规则与受限输入的 Markdown 结构检查。
+ * 精确 findingWaivers 只在完整 traversal 后应用；原 Finding、计数与缓存 facts 保留。
+ *
+ * @param options - 省略时采用八项 recommended 规则；非空 rules 数组完整替换该集合。
+ * @returns 使用默认或指定 checkId 的 typed Check，携带完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} options 含未知字段、未知/重复规则、非法 limits 或 findingWaivers 时抛出。
+ * @example 最小用法
+ * ```ts
+ * import { defineConfig, markdownLint, run } from "@zxyycom/vibe-check";
+ *
+ * const check = markdownLint({ findingPolicy: "blocking" });
+ * const definition = defineConfig({
+ *   checks: [check],
+ *   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}`);
+ * const outcome = result.snapshot.checks.find(({ checkId }) => checkId === check.checkId)?.outcome;
+ * if (outcome?.status !== "passed" && outcome?.status !== "not-applicable") {
+ *   throw new Error(`Markdown lint did not pass: ${outcome?.status ?? "no outcome"}`);
+ * }
+ * if (outcome.status === "not-applicable") console.warn("No Markdown input selected; no lint evidence.");
+ * ```
+ */
+export declare function markdownLint(options?: MarkdownLintOptions<"markdown-lint">): TypedCheckWithOptions<"markdown-lint", ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export declare function markdownLint<const Id extends string>(options: MarkdownLintOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export declare function markdownLint(options: MarkdownLintOptions): TypedCheckWithOptions<string, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;

package/types/package-checks/markdown-lint/execution.d.ts

@@ -0,0 +1,24 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { MarkdownLintFinalData } from "./final-data.ts";
+import type { ResolvedMarkdownLintOptions } from "./options.ts";
+import { type MarkdownLintRecordCandidate } from "./records.ts";
+import { type MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+export type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+export declare const MARKDOWN_LINT_CHECK_DEFINITION: {
+    readonly checkId: "markdown-lint";
+    readonly displayName: "Markdown lint";
+};
+type Traversal = Readonly<{
+    readonly kind: "complete";
+    readonly candidates: readonly MarkdownLintRecordCandidate[];
+    readonly sourceFileCount: number;
+}> | Readonly<{
+    readonly kind: "unavailable";
+    readonly reason: MarkdownLintUnavailableReason;
+}>;
+/** Executes one bounded, ordered lint pass over the exact selected Markdown source paths. */
+export declare function executeMarkdownLint(context: CheckExecutionContext<ResolvedMarkdownLintOptions>): Promise<CheckResult<MarkdownLintFinalData>>;
+/** Reconciles only a complete traversal, then publishes all evidence and the live policy outcome. */
+export declare function publishMarkdownLintTraversal(context: CheckExecutionContext<ResolvedMarkdownLintOptions>, traversal: Extract<Traversal, {
+    readonly kind: "complete";
+}>, rejectedPaths: readonly string[]): CheckResult<MarkdownLintFinalData>;

package/types/package-checks/markdown-lint/final-data.d.ts

@@ -0,0 +1,8 @@
+/** 已完成 `markdownLint` execution 的 canonical final data。 */
+export interface MarkdownLintFinalData {
+    readonly sourceFileCount: number;
+    readonly findingCount: number;
+    readonly rejectedInputCount: number;
+}
+/** 解析并验证 `markdownLint` 完成结果中的 canonical final data。 */
+export declare function parseMarkdownLintData(data: unknown): MarkdownLintFinalData;

package/types/package-checks/markdown-lint/finding-messages.d.ts

@@ -0,0 +1,6 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
+import { type MarkdownLintRecordCandidate } from "./records.ts";
+export declare function markdownLintFindingMessages(candidates: readonly MarkdownLintRecordCandidate[], rejectedPaths: readonly string[], blocking: boolean): readonly CheckMessage[];
+/** Explains every configured waiver without turning accepted findings into error messages. */
+export declare function markdownLintWaiverMessages(reconciliation: FindingWaiverReconciliation<MarkdownLintRecordCandidate>): readonly CheckMessage[];

package/types/package-checks/markdown-lint/finding-waiver-identity.d.ts

@@ -0,0 +1,3 @@
+import { type MarkdownLintFindingIdentity } from "./options.ts";
+/** Validates and detaches the complete public location used for exact waiver matching. */
+export declare function resolveMarkdownLintFindingIdentity(value: unknown): MarkdownLintFindingIdentity | undefined;

package/types/package-checks/markdown-lint/findings-cache.d.ts

@@ -0,0 +1,17 @@
+import { type MarkdownLintBackendFinding } from "./adapter.ts";
+import { type MarkdownLintCacheOptions, type MarkdownLintRuleName } from "./options.ts";
+import type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+type MarkdownLintCacheInput = Readonly<{
+    readonly sourcePath: string;
+    readonly sourceText: string;
+    readonly rules: readonly MarkdownLintRuleName[];
+    readonly cache: MarkdownLintCacheOptions;
+    readonly signal: AbortSignal;
+}>;
+export type MarkdownLintFactsResult = Readonly<{
+    readonly findings: readonly MarkdownLintBackendFinding[];
+    readonly source: "cache" | "computed" | "uncached";
+}> | MarkdownLintUnavailableReason;
+/** Reuses only validated per-source findings; all source reads and Check settlement remain live. */
+export declare function lintMarkdownWithCache(input: MarkdownLintCacheInput): Promise<MarkdownLintFactsResult>;
+export {};

package/types/package-checks/markdown-lint/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import { type ResolvedMarkdownLintOptions } from "./options.ts";
+/** Resolves closed partial authoring options into an immutable complete policy. */
+export declare function resolveMarkdownLintOptions(value: unknown): ResolvedMarkdownLintOptions | undefined;

package/types/package-checks/markdown-lint/options-validation.d.ts

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