@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,264 @@
+import {
+  defineCheck,
+  type CheckExecutionContext,
+  type CheckResult,
+  type TypedCheckWithOptions
+} from "../../check/check.ts";
+import {
+  MAINTENANCE_REMINDER_UNAVAILABLE_REASON,
+  parseMaintenanceRemindersData,
+  type MaintenanceReminderAssessment,
+  type MaintenanceRemindersFinalData
+} from "./final-data.ts";
+import { runGit } from "./maintenance-support.ts";
+import { exactRecord, validEntries, validGit } from "./options-validation.ts";
+import {
+  completedResult,
+  reminderEvaluation,
+  unavailableAssessment,
+  unavailableHistory,
+  unavailableResult
+} from "./assessment-results.ts";
+import { measureReminder, parseCommitId, parseFirstParentHistory } from "./measurement.ts";
+
+export const MAINTENANCE_REMINDERS_CHECK_ID = "maintenance-reminders";
+
+const MAINTENANCE_REMINDER_OPTION_KEYS: readonly string[] = ["entries", "git"];
+const WHOLE_CHECK_UNAVAILABLE_CODE = Object.freeze({
+  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 function maintenanceReminders(
+  entries: readonly MaintenanceReminder[]
+): TypedCheckWithOptions<
+  typeof MAINTENANCE_REMINDERS_CHECK_ID,
+  MaintenanceReminderOptions,
+  typeof parseMaintenanceRemindersData
+> {
+  return defineCheck({
+    checkId: MAINTENANCE_REMINDERS_CHECK_ID,
+    displayName: "Maintenance reminders",
+    execution: executeMaintenanceReminders,
+    parseData: parseMaintenanceRemindersData,
+    preflight: (options) =>
+      validMaintenanceReminderOptions(options)
+        ? { status: "success", preparedOptions: options }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "maintenanceReminders options are invalid; recreate the Check with maintenanceReminders(entries) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: {
+      entries,
+      git: { executable: "git" }
+    },
+    visibility: "attention"
+  });
+}
+
+/** 在普通对象组合后验证完整的选项形状。 */
+export function validMaintenanceReminderOptions(
+  value: unknown
+): value is MaintenanceReminderOptions {
+  const options = exactRecord(value, MAINTENANCE_REMINDER_OPTION_KEYS);
+  return options !== undefined && validEntries(options.entries) && validGit(options.git);
+}
+
+async function executeMaintenanceReminders(
+  context: CheckExecutionContext<MaintenanceReminderOptions>
+): Promise<CheckResult<MaintenanceRemindersFinalData>> {
+  if (!validMaintenanceReminderOptions(context.options))
+    return unavailableResult("invalid-options");
+  if (context.signal.aborted)
+    return unavailableResult(WHOLE_CHECK_UNAVAILABLE_CODE.executionCancelled);
+
+  try {
+    const history = await resolveFirstParentHistory({
+      executable: context.options.git.executable,
+      projectRoot: context.project.root,
+      signal: context.signal
+    });
+    if (history.kind === "cancelled") {
+      return unavailableResult(WHOLE_CHECK_UNAVAILABLE_CODE.executionCancelled);
+    }
+
+    if (history.kind === "unavailable") {
+      return completedResult(
+        context.options.entries.map((entry) =>
+          reminderEvaluation(entry, unavailableAssessment(entry, null, history.reason))
+        )
+      );
+    }
+
+    const evaluations: ReminderEvaluation[] = [];
+    for (const entry of context.options.entries) {
+      const measurement = await measureReminder({
+        entry,
+        executable: context.options.git.executable,
+        history: history.value,
+        projectRoot: context.project.root,
+        signal: context.signal
+      });
+      if (measurement.kind === "cancelled") {
+        return unavailableResult(WHOLE_CHECK_UNAVAILABLE_CODE.executionCancelled);
+      }
+      evaluations.push(measurement.value);
+    }
+    return completedResult(evaluations);
+  } catch {
+    return unavailableResult(WHOLE_CHECK_UNAVAILABLE_CODE.internalFailure);
+  }
+}
+
+async function resolveFirstParentHistory(input: {
+  readonly executable: string;
+  readonly projectRoot: string;
+  readonly signal: AbortSignal;
+}): Promise<FirstParentHistoryResolution> {
+  const head = await runGit({
+    args: ["rev-parse", "--verify", "HEAD^{commit}"],
+    executable: input.executable,
+    projectRoot: input.projectRoot,
+    signal: input.signal
+  });
+  if (head.kind === "cancelled") return head;
+  if (head.kind === "failed")
+    return unavailableHistory(MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headUnavailable);
+
+  const headCommit = parseCommitId(head.stdout);
+  if (headCommit === null)
+    return unavailableHistory(MAINTENANCE_REMINDER_UNAVAILABLE_REASON.headInvalid);
+
+  const history = await runGit({
+    args: ["rev-list", "--first-parent", "HEAD"],
+    executable: input.executable,
+    projectRoot: input.projectRoot,
+    signal: input.signal
+  });
+  if (history.kind === "cancelled") return history;
+  if (history.kind === "failed") {
+    return unavailableHistory(
+      MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryUnavailable
+    );
+  }
+
+  const firstParentHistory = parseFirstParentHistory(history.stdout, headCommit);
+  if (firstParentHistory === undefined) {
+    return unavailableHistory(MAINTENANCE_REMINDER_UNAVAILABLE_REASON.firstParentHistoryInvalid);
+  }
+
+  return {
+    kind: "succeeded",
+    value: firstParentHistory
+  };
+}

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

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process";
+
+import type { GitCommandResult } from "./maintenance-reminders.ts";
+
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+export async function runGit(input: {
+  readonly args: readonly string[];
+  readonly executable: string;
+  readonly projectRoot: string;
+  readonly signal: AbortSignal;
+}): Promise<GitCommandResult> {
+  if (input.signal.aborted) return { kind: "cancelled" };
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let outputBytes = 0;
+    let stdout = "";
+    let overflowed = false;
+    let child: ReturnType<typeof spawn>;
+
+    const settle = (result: GitCommandResult): void => {
+      if (settled) return;
+      settled = true;
+      input.signal.removeEventListener("abort", abort);
+      resolve(result);
+    };
+    const abort = (): void => {
+      child.kill("SIGTERM");
+    };
+
+    try {
+      child = spawn(input.executable, input.args, {
+        cwd: input.projectRoot,
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true
+      });
+    } catch {
+      settle({ kind: "failed" });
+      return;
+    }
+
+    input.signal.addEventListener("abort", abort, { once: true });
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      const text = String(chunk);
+      outputBytes += Buffer.byteLength(text);
+      if (outputBytes > MAX_GIT_OUTPUT_BYTES) {
+        overflowed = true;
+        child.kill("SIGTERM");
+        return;
+      }
+      stdout += text;
+    });
+    child.once("error", () =>
+      settle(input.signal.aborted ? { kind: "cancelled" } : { kind: "failed" })
+    );
+    child.once("close", (status) => {
+      if (input.signal.aborted) {
+        settle({ kind: "cancelled" });
+      } else if (overflowed || status !== 0) {
+        settle({ kind: "failed" });
+      } else {
+        settle({ kind: "succeeded", stdout });
+      }
+    });
+  });
+}

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

@@ -0,0 +1,183 @@
+import {
+  isMaintenanceCommitId,
+  type MaintenanceReminderAssessment,
+  type MaintenanceReminderUnavailableReason
+} from "./final-data.ts";
+import { completedMeasurement, modeOf, unavailableAssessment } from "./assessment-results.ts";
+import { runGit } from "./maintenance-support.ts";
+import type {
+  FirstParentHistory,
+  MaintenanceReminder,
+  ReminderMeasurement
+} from "./maintenance-reminders.ts";
+
+export async function measureReminder(input: {
+  readonly entry: Readonly<MaintenanceReminder>;
+  readonly executable: string;
+  readonly history: FirstParentHistory;
+  readonly projectRoot: string;
+  readonly signal: AbortSignal;
+}): Promise<ReminderMeasurement> {
+  const base = await resolvedBaseCommit(input);
+  if (base.kind === "cancelled") return base;
+  if (base.kind === "unavailable") return unavailableMeasurement(input, base.reason);
+  const changedLines = await measuredChangedLines(input, base.value);
+  if (changedLines.kind === "cancelled") return changedLines;
+  if (changedLines.kind === "unavailable")
+    return unavailableMeasurement(input, changedLines.reason);
+  return completedMeasurement(
+    input.entry,
+    measuredAssessment(input, base.value, changedLines.value)
+  );
+}
+
+type ReminderMeasureStage<T> =
+  | Readonly<{ readonly kind: "cancelled" }>
+  | Readonly<{ readonly kind: "complete"; readonly value: T }>
+  | Readonly<{
+      readonly kind: "unavailable";
+      readonly reason: MaintenanceReminderUnavailableReason;
+    }>;
+
+async function resolvedBaseCommit(input: {
+  readonly entry: Readonly<MaintenanceReminder>;
+  readonly executable: string;
+  readonly history: FirstParentHistory;
+  readonly projectRoot: string;
+  readonly signal: AbortSignal;
+}): Promise<ReminderMeasureStage<number>> {
+  const base = await runGit({
+    args: ["rev-parse", "--verify", `${input.entry.baseCommit}^{commit}`],
+    executable: input.executable,
+    projectRoot: input.projectRoot,
+    signal: input.signal
+  });
+  if (base.kind === "cancelled") return base;
+  if (base.kind === "failed") return unavailableMeasure("base-commit-unavailable");
+
+  const baseCommit = parseCommitId(base.stdout);
+  if (baseCommit === null) return unavailableMeasure("base-commit-unavailable");
+
+  const baseIndex = input.history.commits.indexOf(baseCommit);
+  return baseIndex < 0
+    ? unavailableMeasure("base-not-first-parent-ancestor")
+    : completeMeasure(baseIndex);
+}
+
+async function measuredChangedLines(
+  input: {
+    readonly executable: string;
+    readonly history: FirstParentHistory;
+    readonly projectRoot: string;
+    readonly signal: AbortSignal;
+  },
+  baseIndex: number
+): Promise<ReminderMeasureStage<number>> {
+  let changedLines = 0;
+  for (const commit of input.history.commits.slice(0, baseIndex)) {
+    const numstat = await runGit({
+      args: ["diff-tree", "--no-commit-id", "--numstat", "-r", `${commit}^`, commit],
+      executable: input.executable,
+      projectRoot: input.projectRoot,
+      signal: input.signal
+    });
+    if (numstat.kind === "cancelled") return numstat;
+    if (numstat.kind === "failed") return unavailableMeasure("numstat-unavailable");
+    const count = parseChangedLines(numstat.stdout);
+    if (count === null || !Number.isSafeInteger(changedLines + count))
+      return unavailableMeasure("numstat-invalid");
+    changedLines += count;
+  }
+  return completeMeasure(changedLines);
+}
+
+function measuredAssessment(
+  input: Readonly<{
+    readonly entry: Readonly<MaintenanceReminder>;
+    readonly history: FirstParentHistory;
+  }>,
+  baseIndex: number,
+  changedLines: number
+): MaintenanceReminderAssessment {
+  const mode = modeOf(input.entry);
+  const exceeded = [
+    ...(input.entry.limits.commits !== undefined && baseIndex > input.entry.limits.commits
+      ? (["commits"] as const)
+      : []),
+    ...(input.entry.limits.changedLines !== undefined &&
+    changedLines > input.entry.limits.changedLines
+      ? (["changed-lines"] as const)
+      : [])
+  ];
+  return {
+    assessment: exceeded.length > 0 ? "due" : "clear",
+    baseCommit: input.entry.baseCommit,
+    changedLines,
+    commitCount: baseIndex,
+    exceeded,
+    headCommit: input.history.headCommit,
+    id: input.entry.id,
+    mode
+  };
+}
+
+function unavailableMeasurement(
+  input: Readonly<{
+    readonly entry: Readonly<MaintenanceReminder>;
+    readonly history: FirstParentHistory;
+  }>,
+  reason: MaintenanceReminderUnavailableReason
+): ReminderMeasurement {
+  return completedMeasurement(
+    input.entry,
+    unavailableAssessment(input.entry, input.history.headCommit, reason)
+  );
+}
+
+function completeMeasure<T>(value: T): ReminderMeasureStage<T> {
+  return { kind: "complete", value };
+}
+
+function unavailableMeasure(
+  reason: MaintenanceReminderUnavailableReason
+): ReminderMeasureStage<never> {
+  return { kind: "unavailable", reason };
+}
+
+export function parseCommitId(stdout: string): string | null {
+  const value = stdout.trim();
+  return isMaintenanceCommitId(value) ? value.toLowerCase() : null;
+}
+
+export function parseFirstParentHistory(
+  stdout: string,
+  headCommit: string
+): FirstParentHistory | undefined {
+  const commits: string[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+    const commit = parseCommitId(line);
+    if (commit === null) return undefined;
+    commits.push(commit);
+  }
+  if (commits.length === 0 || commits[0] !== headCommit) return undefined;
+  return Object.freeze({ commits: Object.freeze(commits), headCommit });
+}
+
+function parseChangedLines(stdout: string): number | null {
+  let changedLines = 0;
+  for (const line of stdout.split(/\r?\n/)) {
+    if (line.length === 0) continue;
+    const [additions, deletions] = line.split("\t", 3);
+    if (additions === "-" && deletions === "-") continue;
+    if (!decimal(additions) || !decimal(deletions)) return null;
+    const count = Number(additions) + Number(deletions);
+    if (!Number.isSafeInteger(count) || !Number.isSafeInteger(changedLines + count)) return null;
+    changedLines += count;
+  }
+  return changedLines;
+}
+
+function decimal(value: string | undefined): value is string {
+  return value !== undefined && /^(?:0|[1-9]\d*)$/.test(value);
+}

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

@@ -0,0 +1,88 @@
+import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isMaintenanceCommitId, isMaintenanceReminderId } from "./final-data.ts";
+
+const MAINTENANCE_REMINDER_ENTRY_KEYS: readonly string[] = [
+  "id",
+  "baseCommit",
+  "limits",
+  "message",
+  "mode"
+];
+const MAINTENANCE_REMINDER_LIMIT_KEYS: readonly string[] = ["commits", "changedLines"];
+const MAINTENANCE_REMINDER_GIT_KEYS: readonly string[] = ["executable"];
+
+export function validEntries(value: unknown): boolean {
+  const entries = snapshotClosedArray(value);
+  if (entries === undefined) return false;
+  const identifiers = new Set<string>();
+  return entries.every((candidate) => {
+    const entry = snapshotClosedRecord(candidate);
+    if (entry === undefined || !validEntry(entry)) return false;
+    const identifier = entry.id;
+    if (typeof identifier !== "string" || identifiers.has(identifier)) return false;
+    identifiers.add(identifier);
+    return true;
+  });
+}
+
+function validEntry(entry: Readonly<Record<string, unknown>>): boolean {
+  return (
+    hasExpectedEntryKeys(entry) &&
+    validEntryIdentity(entry) &&
+    validLimits(entry.limits) &&
+    validEntryMode(entry)
+  );
+}
+
+function hasExpectedEntryKeys(entry: Readonly<Record<string, unknown>>): boolean {
+  return (
+    Object.keys(entry).every((key) => MAINTENANCE_REMINDER_ENTRY_KEYS.includes(key)) &&
+    ["id", "baseCommit", "limits", "message"].every((key) => Object.hasOwn(entry, key))
+  );
+}
+
+function validEntryIdentity(entry: Readonly<Record<string, unknown>>): boolean {
+  return (
+    isMaintenanceReminderId(entry.id) &&
+    isMaintenanceCommitId(entry.baseCommit) &&
+    typeof entry.message === "string" &&
+    entry.message.length > 0
+  );
+}
+
+function validEntryMode(entry: Readonly<Record<string, unknown>>): boolean {
+  return !Object.hasOwn(entry, "mode") || entry.mode === "advisory" || entry.mode === "enforcing";
+}
+
+export function validGit(value: unknown): boolean {
+  const git = exactRecord(value, MAINTENANCE_REMINDER_GIT_KEYS);
+  return git !== undefined && typeof git.executable === "string" && git.executable.length > 0;
+}
+
+function validLimits(value: unknown): boolean {
+  const limits = snapshotClosedRecord(value);
+  if (limits === undefined) return false;
+  const keys = Object.keys(limits);
+  return (
+    keys.length > 0 &&
+    keys.every((key) => MAINTENANCE_REMINDER_LIMIT_KEYS.includes(key)) &&
+    (!Object.hasOwn(limits, "commits") || positiveSafeInteger(limits.commits)) &&
+    (!Object.hasOwn(limits, "changedLines") || positiveSafeInteger(limits.changedLines))
+  );
+}
+
+export function exactRecord(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined &&
+    Object.keys(record).length === keys.length &&
+    keys.every((key) => Object.hasOwn(record, key))
+    ? record
+    : undefined;
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}

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

@@ -0,0 +1,70 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION,
+  executeMarkdownLinkValidation
+} from "./execution.ts";
+import { parseMarkdownLinkValidationData } from "./final-data.ts";
+import type {
+  MarkdownLinkValidationOptions,
+  ResolvedMarkdownLinkValidationOptions
+} from "./options.ts";
+import { resolveMarkdownLinkValidationOptions } from "./options-resolution.ts";
+import { validMarkdownLinkValidationOptions } from "./options-validation.ts";
+
+/**
+ * 使用可省略的 source、target 与 work-limit policy 构造离线 Markdown 引用 Check。
+ *
+ * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略。
+ * @returns 固定 `markdown-link-validation` identity、完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} input 含未知字段、非法 target policy 或非法 work limit 时抛出。
+ * @example 离线 Markdown 本地链接完整性
+ * ```ts
+ * import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
+ *
+ * const definition = defineConfig({
+ *   checks: [markdownLinkValidation()],
+ *   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 function markdownLinkValidation(
+  options: MarkdownLinkValidationOptions = {}
+): TypedCheckWithOptions<
+  "markdown-link-validation",
+  ResolvedMarkdownLinkValidationOptions,
+  typeof parseMarkdownLinkValidationData
+> {
+  const resolvedOptions = resolveMarkdownLinkValidationOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError("markdownLinkValidation options must match the documented closed policy");
+  }
+  return defineCheck({
+    ...MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION,
+    execution: executeMarkdownLinkValidation,
+    parseData: parseMarkdownLinkValidationData,
+    preflight: (preparedOptions) =>
+      validMarkdownLinkValidationOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "markdownLinkValidation options are invalid; recreate the Check with markdownLinkValidation(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}