@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/package-checks/markdown-lint/adapter.ts

@@ -0,0 +1,167 @@
+import { lint } from "markdownlint/promise";
+
+import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { MARKDOWN_LINT_RULE_NAMES, type MarkdownLintRuleName } from "./options.ts";
+
+const FRONT_MATTER =
+  /((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m;
+
+const BACKEND_BY_RULE: Readonly<Record<MarkdownLintRuleName, string>> = {
+  "heading-increment": "MD001",
+  "no-reversed-links": "MD011",
+  "no-missing-space-atx": "MD018",
+  "fenced-code-language": "MD040",
+  "no-empty-links": "MD042",
+  "no-alt-text": "MD045",
+  "link-fragments": "MD051",
+  "reference-links-images": "MD052",
+  "table-column-count": "MD056"
+};
+
+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 async function lintMarkdownString(
+  sourcePath: string,
+  sourceText: string,
+  rules: readonly MarkdownLintRuleName[]
+): Promise<readonly MarkdownLintBackendFinding[] | "backend-failed" | "backend-protocol-invalid"> {
+  let raw: unknown;
+  try {
+    raw = await lint({
+      config: backendConfiguration(rules),
+      frontMatter: FRONT_MATTER,
+      noInlineConfig: true,
+      strings: { [sourcePath]: sourceText }
+    });
+  } catch {
+    return "backend-failed";
+  }
+  return parseBackendFindings(raw, sourcePath, sourceText, rules);
+}
+
+function backendConfiguration(
+  rules: readonly MarkdownLintRuleName[]
+): Readonly<Record<string, unknown>> {
+  const configuration: Record<string, unknown> = { default: false };
+  for (const rule of rules) configuration[BACKEND_BY_RULE[rule]] = configurationFor(rule);
+  if (rules.includes("reference-links-images") && !rules.includes("heading-increment")) {
+    configuration.MD001 = configurationFor("heading-increment");
+  }
+  return configuration;
+}
+
+function configurationFor(rule: MarkdownLintRuleName): unknown {
+  switch (rule) {
+    case "heading-increment":
+      return { front_matter_title: "^\\s*title\\s*[:=]" };
+    case "fenced-code-language":
+      return { allowed_languages: [], language_only: false };
+    case "link-fragments":
+      return { ignore_case: false, ignored_pattern: "" };
+    case "reference-links-images":
+      return { ignored_labels: ["x"], shortcut_syntax: false };
+    case "no-reversed-links":
+    case "no-missing-space-atx":
+    case "no-empty-links":
+    case "no-alt-text":
+    case "table-column-count":
+      return true;
+  }
+}
+
+function parseBackendFindings(
+  value: unknown,
+  sourcePath: string,
+  sourceText: string,
+  selectedRules: readonly MarkdownLintRuleName[]
+): readonly MarkdownLintBackendFinding[] | "backend-protocol-invalid" {
+  const result = snapshotClosedRecord(value);
+  if (
+    result === undefined ||
+    Object.keys(result).length !== 1 ||
+    !Object.hasOwn(result, sourcePath) ||
+    !Array.isArray(result[sourcePath])
+  )
+    return "backend-protocol-invalid";
+  const lines = sourceText.split(/\r\n|\r|\n/u);
+  const findings: MarkdownLintBackendFinding[] = [];
+  for (const rawFinding of result[sourcePath]) {
+    const finding = parseBackendFinding(rawFinding, lines);
+    if (finding === undefined) return "backend-protocol-invalid";
+    if (selectedRules.includes(finding.rule)) findings.push(finding);
+  }
+  return Object.freeze(findings);
+}
+
+function parseBackendFinding(
+  value: unknown,
+  lines: readonly string[]
+): MarkdownLintBackendFinding | undefined {
+  const fields = validatedBackendFindingFields(value, lines);
+  if (fields === undefined) return undefined;
+  const range = parseMarkdownLintRange(fields.errorRange, fields.line);
+  return range === undefined
+    ? undefined
+    : Object.freeze({ lineNumber: fields.lineNumber, range, rule: fields.rule });
+}
+
+function validatedBackendFindingFields(
+  value: unknown,
+  lines: readonly string[]
+):
+  | Readonly<{
+      readonly errorRange: unknown;
+      readonly line: string;
+      readonly lineNumber: number;
+      readonly rule: MarkdownLintRuleName;
+    }>
+  | undefined {
+  const finding = snapshotClosedRecord(value);
+  if (finding === undefined) return undefined;
+  const ruleNames = finding.ruleNames;
+  const lineNumber = finding.lineNumber;
+  if (
+    !Array.isArray(ruleNames) ||
+    typeof ruleNames[0] !== "string" ||
+    typeof lineNumber !== "number"
+  )
+    return undefined;
+  if (!Number.isSafeInteger(lineNumber) || lineNumber < 1 || lineNumber > lines.length)
+    return undefined;
+  const rule = ruleForBackend(ruleNames[0]);
+  const line = lines[lineNumber - 1];
+  return rule === undefined || line === undefined
+    ? undefined
+    : Object.freeze({ errorRange: finding.errorRange, line, lineNumber, rule });
+}
+
+function ruleForBackend(backendRule: string): MarkdownLintRuleName | undefined {
+  return MARKDOWN_LINT_RULE_NAMES.find((rule) => BACKEND_BY_RULE[rule] === backendRule);
+}
+
+/** Validates one backend or restored-cache range against the current source line. */
+export function parseMarkdownLintRange(
+  value: unknown,
+  line: string
+): readonly [number, number] | null | undefined {
+  if (value === null) return null;
+  const range = snapshotClosedArray(value);
+  if (range?.length !== 2) return undefined;
+  const [column, length] = range;
+  if (
+    typeof column !== "number" ||
+    typeof length !== "number" ||
+    !Number.isSafeInteger(column) ||
+    !Number.isSafeInteger(length) ||
+    column < 1 ||
+    length < 1 ||
+    column - 1 + length > line.length
+  )
+    return undefined;
+  return Object.freeze([column, length] as const);
+}

package/src/package-checks/markdown-lint/default-check.ts

@@ -0,0 +1,92 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
+import { MARKDOWN_LINT_CHECK_DEFINITION, executeMarkdownLint } from "./execution.ts";
+import { parseMarkdownLintData } from "./final-data.ts";
+import type { MarkdownLintOptions, ResolvedMarkdownLintOptions } from "./options.ts";
+import { resolveMarkdownLintOptions } from "./options-resolution.ts";
+import { validMarkdownLintOptions } from "./options-validation.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 function markdownLint(
+  options?: MarkdownLintOptions<"markdown-lint">
+): TypedCheckWithOptions<
+  "markdown-lint",
+  ResolvedMarkdownLintOptions,
+  typeof parseMarkdownLintData
+>;
+export function markdownLint<const Id extends string>(
+  options: MarkdownLintOptions<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<Id, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export function markdownLint(
+  options: MarkdownLintOptions
+): TypedCheckWithOptions<string, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData>;
+export function markdownLint(
+  options: MarkdownLintOptions = {}
+): TypedCheckWithOptions<string, ResolvedMarkdownLintOptions, typeof parseMarkdownLintData> {
+  const input = resolvePackageCheckAuthoringInput(
+    options,
+    ["files", "findingPolicy", "findingWaivers", "rules", "limits", "cache"],
+    MARKDOWN_LINT_CHECK_DEFINITION
+  );
+  if (input === undefined) {
+    throw new TypeError("markdownLint options must match the documented closed policy");
+  }
+  const resolvedOptions = resolveMarkdownLintOptions(input.domainOptions);
+  if (resolvedOptions === undefined) {
+    throw new TypeError("markdownLint options must match the documented closed policy");
+  }
+  return defineCheck({
+    ...input.definition,
+    execute: executeMarkdownLint,
+    parseData: parseMarkdownLintData,
+    prepare: (preparedOptions) =>
+      validMarkdownLintOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "markdownLint options are invalid; recreate the Check with markdownLint(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}

package/src/package-checks/markdown-lint/execution.ts

@@ -0,0 +1,266 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { appendCheckMessages } from "../../package-tools/finding-presentation/finding-presentation.ts";
+import { reconcileFindingWaivers } from "../../package-tools/finding-waivers/reconciliation.ts";
+import { reportFindingWaiverAudits } from "../code-quality-findings/finding-waiver-evidence.ts";
+import { collectProjectFiles } from "../project-files/collection.ts";
+import { partitionProjectFilesByEligibility } from "../project-files/input-eligibility.ts";
+import {
+  probeRootContainedPath,
+  readRegularFile
+} from "../markdown-link-validation/filesystem-probes.ts";
+import { isRootRelativePath } from "../markdown-link-validation/local-resolution.ts";
+import type { MarkdownLintBackendFinding } from "./adapter.ts";
+import type { MarkdownLintFinalData } from "./final-data.ts";
+import { lintMarkdownWithCache } from "./findings-cache.ts";
+import { markdownLintFindingMessages, markdownLintWaiverMessages } from "./finding-messages.ts";
+import type { ResolvedMarkdownLintOptions } from "./options.ts";
+import { validMarkdownLintOptions } from "./options-validation.ts";
+import {
+  buildMarkdownLintInputRejectedRecord,
+  markdownLintFindingIdentity,
+  markdownLintWaiverAuditRecord,
+  orderedMarkdownLintCandidates,
+  type MarkdownLintRecordCandidate
+} from "./records.ts";
+import {
+  markdownLintUnavailableMessage,
+  type MarkdownLintUnavailableReason
+} from "./unavailable-reasons.ts";
+
+export type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+
+export const MARKDOWN_LINT_CHECK_DEFINITION = {
+  checkId: "markdown-lint",
+  displayName: "Markdown lint"
+} as const;
+
+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 async function executeMarkdownLint(
+  context: CheckExecutionContext<ResolvedMarkdownLintOptions>
+): Promise<CheckResult<MarkdownLintFinalData>> {
+  return validMarkdownLintOptions(context.options)
+    ? executeResolvedMarkdownLint(context)
+    : unavailable("invalid-options");
+}
+
+async function executeResolvedMarkdownLint(
+  context: CheckExecutionContext<ResolvedMarkdownLintOptions>
+): Promise<CheckResult<MarkdownLintFinalData>> {
+  if (context.signal.aborted) return unavailable("cancelled");
+  const discovered = discoverSources(context);
+  if (discovered.kind === "unavailable") return unavailable(discovered.reason);
+  if (discovered.selectedPathCount === 0) {
+    return Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } });
+  }
+  for (const rejectedPath of discovered.rejectedPaths) {
+    const record = buildMarkdownLintInputRejectedRecord(rejectedPath);
+    context.records.report({ id: record.id }, record.data);
+  }
+  const root = await canonicalProjectRoot(context.project.root);
+  if (root === undefined) return unavailable("project-root-unavailable");
+  const traversal = await traverseSources(
+    discovered.sourcePaths,
+    root,
+    context.options,
+    context.signal
+  );
+  if (traversal.kind === "unavailable")
+    return appendRejected(unavailable(traversal.reason), discovered.rejectedPaths.length);
+  if (context.signal.aborted)
+    return appendRejected(unavailable("cancelled"), discovered.rejectedPaths.length);
+  return publishMarkdownLintTraversal(context, traversal, discovered.rejectedPaths);
+}
+
+/** Reconciles only a complete traversal, then publishes all evidence and the live policy outcome. */
+export function publishMarkdownLintTraversal(
+  context: CheckExecutionContext<ResolvedMarkdownLintOptions>,
+  traversal: Extract<Traversal, { readonly kind: "complete" }>,
+  rejectedPaths: readonly string[]
+): CheckResult<MarkdownLintFinalData> {
+  const reconciliation = reconcileFindingWaivers({
+    findings: traversal.candidates,
+    identify: markdownLintFindingIdentity,
+    waivers: context.options.findingWaivers
+  });
+  const actionable: MarkdownLintRecordCandidate[] = [];
+  for (const finding of reconciliation.findings) {
+    const data =
+      finding.disposition === "waived"
+        ? Object.freeze({
+            ...finding.finding.data,
+            waiver: Object.freeze({ reason: finding.waiver.reason })
+          })
+        : finding.finding.data;
+    context.records.report({ id: finding.finding.id }, data);
+    if (finding.disposition !== "waived") actionable.push(finding.finding);
+  }
+  reportFindingWaiverAudits(context, reconciliation, markdownLintWaiverAuditRecord);
+  const findingCount = traversal.candidates.length + rejectedPaths.length;
+  const blocking = context.options.findingPolicy === "blocking";
+  const result: CheckResult<MarkdownLintFinalData> = Object.freeze({
+    status: actionable.length > 0 && blocking ? "failed" : "passed",
+    data: Object.freeze({
+      sourceFileCount: traversal.sourceFileCount,
+      findingCount,
+      rejectedInputCount: rejectedPaths.length
+    })
+  });
+  return appendCheckMessages(result, [
+    ...markdownLintFindingMessages(
+      actionable,
+      rejectedPaths,
+      // Preserve legacy summaries without waivers; fully waived lint must not make rejected-input summaries errors.
+      blocking && (reconciliation.waiverAudits.length === 0 || actionable.length > 0)
+    ),
+    ...markdownLintWaiverMessages(reconciliation)
+  ]);
+}
+
+function discoverSources(context: CheckExecutionContext<ResolvedMarkdownLintOptions>):
+  | Readonly<{
+      readonly kind: "complete";
+      readonly sourcePaths: readonly string[];
+      readonly rejectedPaths: readonly string[];
+      readonly selectedPathCount: number;
+    }>
+  | Readonly<{ readonly kind: "unavailable"; readonly reason: "source-unavailable" }> {
+  try {
+    const selectedPaths = collectProjectFiles(context.project.root, context.options.files);
+    const partition = partitionProjectFilesByEligibility(selectedPaths, isMarkdownPath);
+    return Object.freeze({
+      kind: "complete" as const,
+      sourcePaths: partition.acceptedPaths,
+      rejectedPaths: partition.rejectedPaths,
+      selectedPathCount: selectedPaths.length
+    });
+  } catch {
+    return Object.freeze({ kind: "unavailable" as const, reason: "source-unavailable" as const });
+  }
+}
+
+async function canonicalProjectRoot(projectRoot: string): Promise<string | undefined> {
+  try {
+    return await realpath(projectRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+async function traverseSources(
+  sourcePaths: readonly string[],
+  rootPath: string,
+  options: ResolvedMarkdownLintOptions,
+  signal: AbortSignal
+): Promise<Traversal> {
+  const rawFindings: Array<
+    Readonly<{ readonly path: string; readonly finding: MarkdownLintBackendFinding }>
+  > = [];
+  let sourceFileCount = 0;
+  for (const sourcePath of sourcePaths) {
+    if (signal.aborted) return unavailableTraversal("cancelled");
+    const source = await readMarkdownSource(rootPath, sourcePath, options.limits.maxMarkdownBytes);
+    if (!source.ok) return unavailableTraversal(source.reason);
+    const text = source.text;
+    if (signal.aborted) return unavailableTraversal("cancelled");
+    const linted = await lintMarkdownWithCache({
+      sourcePath,
+      sourceText: text,
+      rules: options.rules,
+      cache: options.cache,
+      signal
+    });
+    const findings = typeof linted === "string" ? linted : linted.findings;
+    if (typeof findings === "string") return unavailableTraversal(findings);
+    if (signal.aborted) return unavailableTraversal("cancelled");
+    sourceFileCount += 1;
+    for (const finding of findings) rawFindings.push(Object.freeze({ path: sourcePath, finding }));
+    if (rawFindings.length > options.limits.maxFindings)
+      return unavailableTraversal("finding-limit-exceeded");
+  }
+  return Object.freeze({
+    kind: "complete" as const,
+    candidates: orderedMarkdownLintCandidates(rawFindings, options.rules),
+    sourceFileCount
+  });
+}
+
+async function readMarkdownSource(
+  rootPath: string,
+  rootRelativePath: string,
+  maxBytes: number
+): Promise<
+  | Readonly<{ readonly ok: true; readonly text: string }>
+  | Readonly<{ readonly ok: false; readonly reason: "source-too-large" | "source-unavailable" }>
+> {
+  if (!isRootRelativePath(rootPath, rootRelativePath))
+    return Object.freeze({ ok: false, reason: "source-unavailable" });
+  const candidatePath = path.resolve(rootPath, rootRelativePath);
+  const probe = await probeRootContainedPath(rootPath, candidatePath);
+  if (probe.kind !== "contained") return Object.freeze({ ok: false, reason: "source-unavailable" });
+  const source = await readRegularFile(probe.absolutePath, maxBytes);
+  if (!source.ok)
+    return Object.freeze({
+      ok: false,
+      reason: source.reason === "too-large" ? "source-too-large" : "source-unavailable"
+    });
+  try {
+    return Object.freeze({
+      ok: true as const,
+      text: new TextDecoder("utf-8", { fatal: true }).decode(source.bytes)
+    });
+  } catch {
+    return Object.freeze({ ok: false, reason: "source-unavailable" });
+  }
+}
+
+function isMarkdownPath(filePath: string): boolean {
+  const extension = path.extname(filePath).toLowerCase();
+  return extension === ".md" || extension === ".markdown";
+}
+
+function unavailableTraversal(reason: MarkdownLintUnavailableReason): Traversal {
+  return Object.freeze({ kind: "unavailable" as const, reason });
+}
+
+function unavailable(reason: MarkdownLintUnavailableReason): CheckResult<MarkdownLintFinalData> {
+  return Object.freeze({
+    status: "unavailable",
+    reason: { code: reason },
+    messages: Object.freeze([
+      Object.freeze({
+        code: reason,
+        level: "error" as const,
+        message: markdownLintUnavailableMessage(reason)
+      })
+    ])
+  });
+}
+
+function appendRejected(
+  result: CheckResult<MarkdownLintFinalData>,
+  rejectedInputCount: number
+): CheckResult<MarkdownLintFinalData> {
+  if (rejectedInputCount === 0) return result;
+  return Object.freeze({
+    ...result,
+    messages: Object.freeze([
+      ...(result.messages ?? []),
+      Object.freeze({
+        code: "input-rejected",
+        level: "warning" as const,
+        message: `${rejectedInputCount} selected markdownLint input file(s) were rejected because only .md/.markdown paths are supported; inspect this Check's Records and narrow files.include/exclude.`
+      })
+    ])
+  });
+}

package/src/package-checks/markdown-lint/final-data.ts

@@ -0,0 +1,33 @@
+import {
+  exactFinalDataRecord,
+  invalidFinalData,
+  nonNegativeSafeInteger
+} from "../final-data-parsing.ts";
+
+/** 已完成 `markdownLint` execution 的 canonical final data。 */
+export interface MarkdownLintFinalData {
+  readonly sourceFileCount: number;
+  readonly findingCount: number;
+  readonly rejectedInputCount: number;
+}
+
+/** 解析并验证 `markdownLint` 完成结果中的 canonical final data。 */
+export function parseMarkdownLintData(data: unknown): MarkdownLintFinalData {
+  const value = exactFinalDataRecord(
+    data,
+    ["sourceFileCount", "findingCount", "rejectedInputCount"],
+    "markdownLint"
+  );
+  const sourceFileCount = nonNegativeSafeInteger(value.sourceFileCount);
+  const findingCount = nonNegativeSafeInteger(value.findingCount);
+  const rejectedInputCount = nonNegativeSafeInteger(value.rejectedInputCount);
+  if (
+    sourceFileCount === undefined ||
+    findingCount === undefined ||
+    rejectedInputCount === undefined ||
+    findingCount < rejectedInputCount
+  ) {
+    throw invalidFinalData("markdownLint");
+  }
+  return Object.freeze({ sourceFileCount, findingCount, rejectedInputCount });
+}

package/src/package-checks/markdown-lint/finding-messages.ts

@@ -0,0 +1,87 @@
+import type { CheckMessage } from "../../check/check.ts";
+import { presentCheckFindings } from "../../package-tools/finding-presentation/finding-presentation.ts";
+import type {
+  FindingWaiverAudit,
+  FindingWaiverReconciliation
+} from "../../package-tools/finding-waivers/reconciliation.ts";
+import { markdownLintWaiverIdentity, type MarkdownLintRecordCandidate } from "./records.ts";
+
+const SUMMARY: Readonly<Record<MarkdownLintRecordCandidate["data"]["rule"], string>> = {
+  "heading-increment": "heading levels may increase by only one level",
+  "no-reversed-links": "reversed link syntax is not supported",
+  "no-missing-space-atx": "ATX heading markers require a following space",
+  "fenced-code-language": "fenced code blocks require a language",
+  "no-empty-links": "links require a non-empty destination",
+  "no-alt-text": "images require alternative text",
+  "link-fragments": "same-document fragments must match a heading",
+  "reference-links-images": "reference links and images require a definition",
+  "table-column-count": "pipe table rows must have a consistent column count"
+};
+
+export function markdownLintFindingMessages(
+  candidates: readonly MarkdownLintRecordCandidate[],
+  rejectedPaths: readonly string[],
+  blocking: boolean
+): readonly CheckMessage[] {
+  const findings = [
+    ...candidates.map((candidate) => Object.freeze({ kind: "lint" as const, candidate })),
+    ...rejectedPaths.map((path) => Object.freeze({ kind: "rejected" as const, path }))
+  ];
+  return presentCheckFindings({
+    findings,
+    limit: 10,
+    message: (finding) => {
+      if (finding.kind === "rejected") {
+        return Object.freeze({
+          code: "finding-detail",
+          level: "warning" as const,
+          message: `${finding.path}: selected input is not a supported Markdown source.`
+        });
+      }
+      const { path, range, rule } = finding.candidate.data;
+      return Object.freeze({
+        code: "finding-detail",
+        level: blocking ? ("error" as const) : ("warning" as const),
+        message: `${path}:${range.start.line}:${range.start.column} ${rule}: ${SUMMARY[rule]}.`
+      });
+    },
+    omittedMessage: ({ omittedCount }) =>
+      Object.freeze({
+        code: "findings-omitted",
+        level: blocking ? ("error" as const) : ("warning" as const),
+        message: `${omittedCount} additional Markdown lint finding(s) were not shown; inspect this Check's Records for the complete set.`
+      })
+  });
+}
+
+/** Explains every configured waiver without turning accepted findings into error messages. */
+export function markdownLintWaiverMessages(
+  reconciliation: FindingWaiverReconciliation<MarkdownLintRecordCandidate>
+): readonly CheckMessage[] {
+  return Object.freeze(reconciliation.waiverAudits.map(markdownLintWaiverMessage));
+}
+
+function markdownLintWaiverMessage(audit: FindingWaiverAudit): CheckMessage {
+  const { path, rule, range } = markdownLintWaiverIdentity(audit.waiver);
+  const subject = `${path}:${range.start.line}:${range.start.column}-${range.end.column} ${rule}`;
+  switch (audit.status) {
+    case "applied":
+      return Object.freeze({
+        code: "finding-waived",
+        level: "info",
+        message: `Markdown lint finding for ${subject} was waived: ${audit.waiver.reason}`
+      });
+    case "unused":
+      return Object.freeze({
+        code: "unused-finding-waiver",
+        level: "warning",
+        message: `Configured markdown-lint finding waiver for ${subject} matched no finding; remove it or update its identity. Reason: ${audit.waiver.reason}`
+      });
+    case "overmatched":
+      return Object.freeze({
+        code: "overmatched-finding-waiver",
+        level: "warning",
+        message: `Configured markdown-lint finding waiver for ${subject} matched ${audit.matchCount} findings and was not applied; inspect the duplicate identities. Reason: ${audit.waiver.reason}`
+      });
+  }
+}