@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/package-checks/markdown-link-validation/default-check.ts

@@ -14,15 +14,21 @@ import { validMarkdownLinkValidationOptions } from "./options-validation.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 },

package/src/package-checks/markdown-link-validation/execution.ts

@@ -5,21 +5,24 @@ import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
 import { collectProjectFiles } from "../project-files/collection.ts";
 import type { ProjectFileSelection } from "../project-files/configuration.ts";
 import { partitionProjectFilesByEligibility } from "../project-files/input-eligibility.ts";
-import {
-  createMarkdownLocalResolver,
-  type MarkdownLocalResolutionReason,
-  type MarkdownLocalResolver,
-  type MarkdownSourceReadFailureReason
-} from "./local-resolver.ts";
+import { appendCheckMessages } from "../../check/finding-presentation.ts";
+import { createMarkdownLocalResolver, type MarkdownLocalResolver } from "./local-resolver.ts";
 import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+import { markdownFindingMessages } from "./finding-messages.ts";
 import {
   buildMarkdownInputRejectedRecord,
   buildMarkdownLinkRecordCandidate,
   type MarkdownLinkRecordCandidate
 } from "./records.ts";
 import { settledMarkdownTraversalResult } from "./traversal-result.ts";
+import {
+  markdownLinkUnavailableMessage,
+  type MarkdownLinkValidationUnavailableReason
+} from "./unavailable-reasons.ts";
 import { validMarkdownLinkValidationOptions } from "./options-validation.ts";
 
+export type { MarkdownLinkValidationUnavailableReason } from "./unavailable-reasons.ts";
+
 export const MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION = {
   checkId: "markdown-link-validation",
   displayName: "Markdown link validation"
@@ -31,15 +34,6 @@ interface MarkdownLinkValidationRun {
   readonly signal: AbortSignal;
 }
 
-/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
-export type MarkdownLinkValidationUnavailableReason =
-  | "invalid-options"
-  | "cancelled"
-  | "occurrence-limit-exceeded"
-  | "project-root-unavailable"
-  | MarkdownLocalResolutionReason
-  | MarkdownSourceReadFailureReason;
-
 type MarkdownLinkValidationUnavailable = Readonly<{
   readonly kind: "unavailable";
   readonly reason: MarkdownLinkValidationUnavailableReason;
@@ -78,19 +72,26 @@ export async function executeMarkdownLinkValidation(
   if (!validMarkdownLinkValidationOptions(context.options)) return unavailable("invalid-options");
   const prepared = await prepareMarkdownTraversal(context);
   if (prepared.kind === "result") return prepared.result;
-  const { rejectedInputCount, traversal, resolver } = prepared;
+  const { rejectedPaths, traversal, resolver } = prepared;
 
   for (const candidate of traversal.candidates) {
     context.records.report({ id: candidate.id }, candidate.data);
   }
-  return settledMarkdownTraversalResult({
-    findingCount: traversal.candidates.length,
-    findingPolicy: context.options.findingPolicy,
-    occurrenceCount: traversal.occurrenceCount,
-    rejectedInputCount,
-    sourceFileCount: traversal.sourceFileCount,
-    targetReadCount: resolver.targetReadCount
-  });
+  return appendCheckMessages(
+    settledMarkdownTraversalResult({
+      findingCount: traversal.candidates.length,
+      findingPolicy: context.options.findingPolicy,
+      occurrenceCount: traversal.occurrenceCount,
+      rejectedInputCount: rejectedPaths.length,
+      sourceFileCount: traversal.sourceFileCount,
+      targetReadCount: resolver.targetReadCount
+    }),
+    markdownFindingMessages(
+      traversal.candidates,
+      rejectedPaths,
+      context.options.findingPolicy === "blocking"
+    )
+  );
 }
 
 type PreparedMarkdownTraversal =
@@ -100,7 +101,7 @@ type PreparedMarkdownTraversal =
     }>
   | Readonly<{
       readonly kind: "traversal";
-      readonly rejectedInputCount: number;
+      readonly rejectedPaths: readonly string[];
       readonly resolver: MarkdownLocalResolver;
       readonly traversal: Extract<MarkdownLinkTraversal, { readonly kind: "complete" }>;
     }>;
@@ -111,9 +112,24 @@ async function prepareMarkdownTraversal(
   if (context.signal.aborted) return result(unavailable("cancelled"));
   const created = await createMarkdownLocalResolver(
     context.project.root,
-    context.options.limits.maxTargetReads
+    context.options.limits.maxTargetReads,
+    context.options.cache,
+    context.signal
   );
   if (!created.ok) return result(unavailable(created.reason));
+  let prepared: PreparedMarkdownTraversal;
+  try {
+    prepared = await prepareCreatedMarkdownTraversal(context, created.resolver);
+  } finally {
+    await created.resolver.finalize();
+  }
+  return context.signal.aborted ? result(unavailable("cancelled")) : prepared;
+}
+
+async function prepareCreatedMarkdownTraversal(
+  context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>,
+  resolver: MarkdownLocalResolver
+): Promise<PreparedMarkdownTraversal> {
   if (context.signal.aborted) return result(unavailable("cancelled"));
   const sourceDiscovery = discoverMarkdownSourcePaths(context.project, context.options.files);
   if (sourceDiscovery.kind === "unavailable") return result(unavailable(sourceDiscovery.reason));
@@ -121,7 +137,7 @@ async function prepareMarkdownTraversal(
   if (context.signal.aborted) return result(unavailable("cancelled"));
   reportRejectedInputs(context, sourceDiscovery.rejectedPaths);
   const traversal = await traverseMarkdownSources(sourceDiscovery.sourcePaths, {
-    resolver: created.resolver,
+    resolver,
     options: context.options,
     signal: context.signal
   });
@@ -140,8 +156,8 @@ async function prepareMarkdownTraversal(
   }
   return Object.freeze({
     kind: "traversal",
-    rejectedInputCount: sourceDiscovery.rejectedPaths.length,
-    resolver: created.resolver,
+    rejectedPaths: sourceDiscovery.rejectedPaths,
+    resolver,
     traversal
   });
 }
@@ -216,6 +232,7 @@ async function traverseMarkdownSources(
   let occurrenceCount = 0;
   let sourceFileCount = 0;
 
+  // The Run's shared Scheduler owns cross-Check concurrency; this Check processes sources strictly in order.
   for (const sourcePath of sourcePaths) {
     const sourceValidation = await validateMarkdownSource(sourcePath, occurrenceCount, run);
     if (sourceValidation.kind === "unavailable") return sourceValidation;
@@ -292,34 +309,11 @@ function unavailable(
     status: "unavailable",
     reason: { code: reason },
     messages: Object.freeze([
-      Object.freeze({ code: reason, level: "error" as const, message: unavailableMessage(reason) })
+      Object.freeze({
+        code: reason,
+        level: "error" as const,
+        message: markdownLinkUnavailableMessage(reason)
+      })
     ])
   });
 }
-
-function unavailableMessage(reason: MarkdownLinkValidationUnavailableReason): string {
-  return UNAVAILABLE_MESSAGES[reason];
-}
-
-const UNAVAILABLE_MESSAGES: Readonly<Record<MarkdownLinkValidationUnavailableReason, string>> = {
-  "invalid-options":
-    "markdownLinkValidation options are invalid; recreate the Check with markdownLinkValidation(options) or restore its complete resolved options.",
-  "project-root-unavailable":
-    "Markdown link validation could not resolve the project root; check that the path exists and is accessible.",
-  "source-unavailable":
-    "A selected Markdown source could not be collected, read, decoded, or contained safely; check the file source and permissions.",
-  "source-too-large":
-    "A selected Markdown source exceeds maxMarkdownBytes; narrow the file selection or raise the bounded limit.",
-  "markdown-parse-failed":
-    "A selected Markdown source could not be parsed completely; inspect that document's Markdown syntax and encoding.",
-  "invalid-local-destination":
-    "A local Markdown destination could not be parsed safely; inspect the affected link destination syntax.",
-  "target-unavailable":
-    "A local Markdown target could not be probed or read safely; check the target path, permissions, size, and encoding.",
-  "occurrence-limit-exceeded":
-    "Markdown link validation exceeded maxOccurrences; narrow the source selection or raise the bounded limit.",
-  "target-read-limit-exceeded":
-    "Markdown link validation exceeded maxTargetReads; narrow the source selection or raise the bounded limit.",
-  cancelled:
-    "Markdown link validation was cancelled before it could form a complete result; inspect the caller's cancellation reason and retry if appropriate."
-};

package/src/package-checks/markdown-link-validation/filesystem-probes.ts

@@ -6,10 +6,22 @@ import {
   isNotFound,
   isWithinRoot,
   relativeSegments,
+  type ExistingEndpointProbe,
   type EndpointProbe,
   type RootProbe
 } from "./local-resolution.ts";
 
+interface RootContainedPathProbeState {
+  readonly currentPath: string;
+  readonly pendingSegments: readonly string[];
+  readonly symlinkHops: number;
+}
+
+type RootContainedPathProbeAdvance = RootProbe | RootContainedPathProbeState;
+type RootContainedPathStatus =
+  | RootProbe
+  | Readonly<{ readonly kind: "status"; readonly status: Awaited<ReturnType<typeof lstat>> }>;
+
 export async function probeRootContainedPath(
   canonicalProjectRoot: string,
   candidatePath: string
@@ -17,71 +29,103 @@ export async function probeRootContainedPath(
   if (!isWithinRoot(canonicalProjectRoot, candidatePath)) {
     return Object.freeze({ kind: "outside" as const });
   }
-  let pendingSegments = relativeSegments(canonicalProjectRoot, candidatePath);
-  let currentPath = canonicalProjectRoot;
-  let symlinkHops = 0;
+  let state: RootContainedPathProbeState = {
+    currentPath: canonicalProjectRoot,
+    pendingSegments: relativeSegments(canonicalProjectRoot, candidatePath),
+    symlinkHops: 0
+  };
 
-  while (pendingSegments.length > 0) {
-    const segment = pendingSegments.shift();
-    if (segment === undefined) {
-      return Object.freeze({ kind: "unavailable" as const });
-    }
-    const nextPath = path.join(currentPath, segment);
-    let status: Awaited<ReturnType<typeof lstat>>;
-    try {
-      status = await lstat(nextPath);
-    } catch (error: unknown) {
-      if (isNotFound(error)) {
-        return Object.freeze({ kind: "missing" as const, absolutePath: nextPath });
-      }
-      return Object.freeze({ kind: "unavailable" as const });
-    }
-    if (!status.isSymbolicLink()) {
-      currentPath = nextPath;
-      continue;
-    }
-    if (symlinkHops >= 40) {
-      return Object.freeze({ kind: "unavailable" as const });
-    }
-    symlinkHops += 1;
-    let linkDestination: string;
-    try {
-      linkDestination = path.resolve(path.dirname(nextPath), await readlink(nextPath));
-    } catch {
-      return Object.freeze({ kind: "unavailable" as const });
-    }
-    if (!isWithinRoot(canonicalProjectRoot, linkDestination)) {
-      return Object.freeze({ kind: "outside" as const });
-    }
-    pendingSegments = [
-      ...relativeSegments(canonicalProjectRoot, linkDestination),
-      ...pendingSegments
-    ];
-    currentPath = canonicalProjectRoot;
+  while (state.pendingSegments.length > 0) {
+    const advance = await advanceRootContainedPathProbe(canonicalProjectRoot, state);
+    if (!isRootContainedPathProbeState(advance)) return advance;
+    state = advance;
   }
 
-  return Object.freeze({ kind: "contained" as const, absolutePath: currentPath });
+  return Object.freeze({ kind: "contained" as const, absolutePath: state.currentPath });
 }
 
-export async function probeEndpoint(targetPath: string): Promise<EndpointProbe> {
-  let status: Awaited<ReturnType<typeof lstat>>;
+function isRootContainedPathProbeState(
+  value: RootContainedPathProbeAdvance
+): value is RootContainedPathProbeState {
+  return "currentPath" in value;
+}
+
+async function advanceRootContainedPathProbe(
+  canonicalProjectRoot: string,
+  state: RootContainedPathProbeState
+): Promise<RootContainedPathProbeAdvance> {
+  const [segment, ...remainingSegments] = state.pendingSegments;
+  if (segment === undefined) return Object.freeze({ kind: "unavailable" as const });
+  const nextPath = path.join(state.currentPath, segment);
+  const pathStatus = await rootContainedPathStatus(nextPath);
+  if (pathStatus.kind !== "status") return pathStatus;
+  if (!pathStatus.status.isSymbolicLink()) {
+    return remainingSegments.length === 0
+      ? Object.freeze({
+          kind: "contained" as const,
+          absolutePath: nextPath,
+          endpoint: endpointFromStatus(pathStatus.status)
+        })
+      : Object.freeze({
+          currentPath: nextPath,
+          pendingSegments: remainingSegments,
+          symlinkHops: state.symlinkHops
+        });
+  }
+  return advanceThroughContainedSymlink(
+    canonicalProjectRoot,
+    nextPath,
+    remainingSegments,
+    state.symlinkHops
+  );
+}
+
+async function rootContainedPathStatus(nextPath: string): Promise<RootContainedPathStatus> {
   try {
-    status = await lstat(targetPath);
+    return Object.freeze({ kind: "status" as const, status: await lstat(nextPath) });
   } catch (error: unknown) {
     return isNotFound(error)
-      ? Object.freeze({ kind: "missing" as const })
+      ? Object.freeze({ kind: "missing" as const, absolutePath: nextPath })
       : Object.freeze({ kind: "unavailable" as const });
   }
-  if (status.isSymbolicLink()) {
+}
+
+async function advanceThroughContainedSymlink(
+  canonicalProjectRoot: string,
+  linkPath: string,
+  remainingSegments: readonly string[],
+  symlinkHops: number
+): Promise<RootContainedPathProbeAdvance> {
+  if (symlinkHops >= 40) return Object.freeze({ kind: "unavailable" as const });
+  let linkDestination: string;
+  try {
+    linkDestination = path.resolve(path.dirname(linkPath), await readlink(linkPath));
+  } catch {
     return Object.freeze({ kind: "unavailable" as const });
   }
-  if (status.isDirectory()) {
-    return Object.freeze({ kind: "directory" as const });
+  if (!isWithinRoot(canonicalProjectRoot, linkDestination)) {
+    return Object.freeze({ kind: "outside" as const });
   }
-  if (status.isFile()) {
-    return Object.freeze({ kind: "file" as const });
+  return Object.freeze({
+    currentPath: canonicalProjectRoot,
+    pendingSegments: [
+      ...relativeSegments(canonicalProjectRoot, linkDestination),
+      ...remainingSegments
+    ],
+    symlinkHops: symlinkHops + 1
+  });
+}
+
+export async function probeEndpoint(targetPath: string): Promise<EndpointProbe> {
+  let status: Awaited<ReturnType<typeof lstat>>;
+  try {
+    status = await lstat(targetPath);
+  } catch (error: unknown) {
+    return isNotFound(error)
+      ? Object.freeze({ kind: "missing" as const })
+      : Object.freeze({ kind: "unavailable" as const });
   }
-  return Object.freeze({ kind: "unsupported" as const });
+  return endpointFromStatus(status);
 }
 
 export async function readRegularFile(
@@ -125,3 +169,16 @@ async function readBoundedBytes(
   }
   return offset > maxBytes ? null : bytes.slice(0, offset);
 }
+
+function endpointFromStatus(status: Awaited<ReturnType<typeof lstat>>): ExistingEndpointProbe {
+  if (status.isSymbolicLink()) {
+    return Object.freeze({ kind: "unavailable" as const });
+  }
+  if (status.isDirectory()) {
+    return Object.freeze({ kind: "directory" as const });
+  }
+  if (status.isFile()) {
+    return Object.freeze({ kind: "file" as const });
+  }
+  return Object.freeze({ kind: "unsupported" as const });
+}

package/src/package-checks/markdown-link-validation/final-data.ts

@@ -6,10 +6,15 @@ import {
 
 /** `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;
 }
 

package/src/package-checks/markdown-link-validation/finding-messages.ts

@@ -0,0 +1,48 @@
+import type { CheckMessage } from "../../check/check.ts";
+import { presentCheckFindings } from "../../check/finding-presentation.ts";
+import type { MarkdownLinkRecordCandidate } from "./records.ts";
+
+const PRESENTED_FINDING_LIMIT = 10;
+
+type PresentedMarkdownFinding =
+  | Readonly<{ readonly kind: "link"; readonly candidate: MarkdownLinkRecordCandidate }>
+  | Readonly<{ readonly kind: "input-rejected"; readonly path: string }>;
+
+/** Projects completed Link findings without copying raw destinations into presentation. */
+export function markdownFindingMessages(
+  candidates: readonly MarkdownLinkRecordCandidate[],
+  rejectedPaths: readonly string[],
+  blocking: boolean
+): readonly CheckMessage[] {
+  const findings: PresentedMarkdownFinding[] = [
+    ...candidates.map((candidate) => Object.freeze({ kind: "link" as const, candidate })),
+    ...rejectedPaths.map((path) => Object.freeze({ kind: "input-rejected" as const, path }))
+  ];
+  return presentCheckFindings({
+    findings,
+    limit: PRESENTED_FINDING_LIMIT,
+    message: (finding) => {
+      if (finding.kind === "input-rejected") {
+        return Object.freeze({
+          code: "finding-detail",
+          level: "warning" as const,
+          message: `${finding.path}: selected input is not a supported Markdown source.`
+        });
+      }
+      const { occurrenceKind, range, reason, sourcePath } = finding.candidate.data;
+      return Object.freeze({
+        code: "finding-detail",
+        level: blocking ? ("error" as const) : ("warning" as const),
+        message: `${sourcePath}:${range.start.line}:${range.start.column} ${occurrenceKind}: ${reason}.`
+      });
+    },
+    omittedMessage: ({ omittedCount, omittedFindings }) =>
+      Object.freeze({
+        code: "findings-omitted",
+        level: omittedFindings.some((finding) => finding.kind === "link" && blocking)
+          ? ("error" as const)
+          : ("warning" as const),
+        message: `${omittedCount} additional Markdown link finding(s) were not shown; inspect this Check's Records for the complete set.`
+      })
+  });
+}

package/src/package-checks/markdown-link-validation/local-resolution.ts

@@ -33,6 +33,7 @@ interface MarkdownLinkSource {
 interface MarkdownLocalResolver {
   readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
   resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+  finalize(): Promise<void>;
   readonly targetReadCount: number;
 }
 
@@ -82,19 +83,25 @@ interface ParsedLocalDestination {
   readonly isAbsolute: boolean;
 }
 
-interface RootContainedPath {
-  readonly kind: "contained" | "missing";
-  readonly absolutePath: string;
-}
-
 type RootProbe =
-  | RootContainedPath
+  | Readonly<{
+      readonly kind: "contained";
+      readonly absolutePath: string;
+      /** 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<{ readonly kind: "directory" | "file" | "unsupported" | "unavailable" }>;
+type EndpointProbe = Readonly<{ readonly kind: "missing" }> | ExistingEndpointProbe;
+
+type ExistingEndpointProbe = Readonly<{
+  readonly kind: "directory" | "file" | "unsupported" | "unavailable";
+}>;
 
 export function parseLocalDestination(
   rawDestination: string
@@ -302,5 +309,6 @@ export type {
   MarkdownSourceReadFailureReason,
   RootProbe,
   EndpointProbe,
+  ExistingEndpointProbe,
   RootExternalTargetMode
 };

package/src/package-checks/markdown-link-validation/local-resolver.ts

@@ -2,17 +2,20 @@ import { realpath } from "node:fs/promises";
 
 import { LinkLocalResolver } from "./resolver-engine.ts";
 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 async function createMarkdownLocalResolver(
   projectRoot: string,
-  maxTargetReads: number
+  maxTargetReads: number,
+  cache: ResolvedMarkdownLinkValidationOptions["cache"],
+  signal: AbortSignal
 ): Promise<MarkdownLocalResolverCreation> {
   try {
     const canonicalProjectRoot = await realpath(projectRoot);
     return Object.freeze({
       ok: true as const,
-      resolver: new LinkLocalResolver(canonicalProjectRoot, maxTargetReads)
+      resolver: new LinkLocalResolver(canonicalProjectRoot, maxTargetReads, cache, signal)
     });
   } catch {
     return Object.freeze({ ok: false as const, reason: "project-root-unavailable" as const });

package/src/package-checks/markdown-link-validation/options-resolution.ts

@@ -1,5 +1,6 @@
 import { canonicalizeJsonObject } from "../../data-boundary/canonical-data.ts";
 import {
+  hasExactPlainRecordKeys,
   hasRequiredAndOptionalRecordKeys,
   snapshotClosedRecord
 } from "../../data-boundary/closed-values.ts";
@@ -32,8 +33,15 @@ export function resolveMarkdownLinkValidationOptions(
   const limits = resolvedLimits(input.limits);
   const files = resolvedFiles(input.files);
   const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
-  if (limits === undefined || files === undefined || findingPolicy === undefined) return undefined;
-  const candidate = optionsCandidate(input, files, findingPolicy, limits);
+  const cache = resolvedCache(input.cache);
+  if (
+    limits === undefined ||
+    files === undefined ||
+    findingPolicy === undefined ||
+    cache === undefined
+  )
+    return undefined;
+  const candidate = optionsCandidate(input, files, findingPolicy, limits, cache);
   return candidate !== undefined && validMarkdownLinkValidationOptions(candidate)
     ? candidate
     : undefined;
@@ -43,7 +51,8 @@ function optionsCandidate(
   input: Readonly<Record<string, unknown>>,
   files: Exclude<ReturnType<typeof resolvedFiles>, undefined>,
   findingPolicy: Exclude<ReturnType<typeof resolveFindingPolicy>, undefined>,
-  limits: Readonly<Record<string, unknown>>
+  limits: Readonly<Record<string, unknown>>,
+  cache: ResolvedMarkdownLinkValidationOptions["cache"]
 ) {
   return canonicalizeJsonObject({
     files,
@@ -58,6 +67,7 @@ function optionsCandidate(
       input.rootExternalTargetMode === undefined ? "report" : input.rootExternalTargetMode,
     requireNonEmptyDirectories:
       input.requireNonEmptyDirectories === undefined ? false : input.requireNonEmptyDirectories,
+    cache,
     limits
   });
 }
@@ -76,6 +86,7 @@ function isMarkdownLinkValidationInput(
         "validateCrossDocumentAnchors",
         "rootExternalTargetMode",
         "requireNonEmptyDirectories",
+        "cache",
         "limits"
       ],
       required: []
@@ -83,6 +94,23 @@ function isMarkdownLinkValidationInput(
   );
 }
 
+function resolvedCache(value: unknown): ResolvedMarkdownLinkValidationOptions["cache"] | 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;
+}
+
 function resolvedFiles(value: unknown) {
   return value === undefined
     ? snapshotProjectFileSelection(DEFAULT_FILES)