@zxyycom/vibe-check 0.0.1 → 0.0.3

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}`
+      });
+  }
+}

package/src/package-checks/markdown-lint/finding-waiver-identity.ts

@@ -0,0 +1,54 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintFindingIdentity,
+  type MarkdownLintRuleName
+} from "./options.ts";
+
+/** Validates and detaches the complete public location used for exact waiver matching. */
+export function resolveMarkdownLintFindingIdentity(
+  value: unknown
+): MarkdownLintFindingIdentity | undefined {
+  const identity = snapshotExactClosedRecord(value, ["path", "rule", "range"]);
+  if (
+    identity === undefined ||
+    !isNormalizedProjectRelativePath(identity.path) ||
+    !isMarkdownLintRuleName(identity.rule)
+  ) {
+    return undefined;
+  }
+  const range = snapshotExactClosedRecord(identity.range, ["start", "end"]);
+  if (range === undefined) return undefined;
+  const start = resolvePosition(range.start);
+  const end = resolvePosition(range.end);
+  if (
+    start === undefined ||
+    end === undefined ||
+    start.line !== end.line ||
+    end.column < start.column
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    path: identity.path,
+    rule: identity.rule,
+    range: Object.freeze({ start, end })
+  });
+}
+
+function resolvePosition(
+  value: unknown
+): MarkdownLintFindingIdentity["range"]["start"] | undefined {
+  const position = snapshotExactClosedRecord(value, ["line", "column"]);
+  return position !== undefined &&
+    isPositiveSafeInteger(position.line) &&
+    isPositiveSafeInteger(position.column)
+    ? Object.freeze({ line: position.line, column: position.column })
+    : undefined;
+}
+
+function isMarkdownLintRuleName(value: unknown): value is MarkdownLintRuleName {
+  return typeof value === "string" && MARKDOWN_LINT_RULE_NAMES.some((rule) => rule === value);
+}

package/src/package-checks/markdown-lint/findings-cache.ts

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+
+import {
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { cacheJsonByKey } from "../../package-tools/cache/cache-json-by-key.ts";
+import {
+  lintMarkdownString,
+  parseMarkdownLintRange,
+  type MarkdownLintBackendFinding
+} from "./adapter.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintCacheOptions,
+  type MarkdownLintRuleName
+} from "./options.ts";
+import type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+
+type LintFacts = Readonly<{ readonly findings: readonly MarkdownLintBackendFinding[] }>;
+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;
+
+/** Bump when adapter configuration or finding interpretation changes without a backend version change. */
+const CACHE_FORMAT_VERSION = "markdown-lint-findings-v1";
+const backendVersion = installedMarkdownlintVersion();
+
+class LintComputationUnavailable extends Error {
+  readonly reason: MarkdownLintUnavailableReason;
+
+  constructor(reason: MarkdownLintUnavailableReason) {
+    super(`Markdown lint unavailable: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+/** Reuses only validated per-source findings; all source reads and Check settlement remain live. */
+export async function lintMarkdownWithCache(
+  input: MarkdownLintCacheInput
+): Promise<MarkdownLintFactsResult> {
+  const { sourcePath, sourceText, rules, cache, signal } = input;
+  if (signal.aborted) return "cancelled";
+  if (!cache.enabled || backendVersion === undefined) return lintFresh(input);
+
+  try {
+    const result = await cacheJsonByKey({
+      directory: cache.directory,
+      key: JSON.stringify({
+        path: sourcePath,
+        sourceDigest: createHash("sha256").update(sourceText, "utf8").digest("hex"),
+        rules
+      }),
+      namespace: "markdown-lint-findings",
+      version: `${CACHE_FORMAT_VERSION}:${backendVersion}`,
+      compute: async () => {
+        if (signal.aborted) throw new LintComputationUnavailable("cancelled");
+        const findings = await lintMarkdownString(sourcePath, sourceText, rules);
+        if (typeof findings === "string") throw new LintComputationUnavailable(findings);
+        if (signal.aborted) throw new LintComputationUnavailable("cancelled");
+        return { findings };
+      },
+      parse: (value) => parseLintFacts(value, sourceText, rules)
+    });
+    if (signal.aborted) return "cancelled";
+    return Object.freeze({ findings: result.value.findings, source: result.source });
+  } catch (error: unknown) {
+    if (signal.aborted) return "cancelled";
+    if (error instanceof LintComputationUnavailable) return error.reason;
+    throw error;
+  }
+}
+
+async function lintFresh(input: MarkdownLintCacheInput): Promise<MarkdownLintFactsResult> {
+  const findings = await lintMarkdownString(input.sourcePath, input.sourceText, input.rules);
+  if (input.signal.aborted) return "cancelled";
+  return typeof findings === "string"
+    ? findings
+    : Object.freeze({ findings, source: "uncached" as const });
+}
+
+function parseLintFacts(
+  value: unknown,
+  sourceText: string,
+  rules: readonly MarkdownLintRuleName[]
+): LintFacts {
+  const payload = snapshotExactClosedRecord(value, ["findings"]);
+  if (payload === undefined || !Array.isArray(payload.findings))
+    throw new TypeError("Invalid Markdown lint cache payload");
+  const lines = sourceText.split(/\r\n|\r|\n/u);
+  const findings = payload.findings.map((rawFinding: unknown) => {
+    const finding = snapshotExactClosedRecord(rawFinding, ["lineNumber", "range", "rule"]);
+    if (
+      finding === undefined ||
+      !isMarkdownLintRuleName(finding.rule) ||
+      !rules.includes(finding.rule) ||
+      typeof finding.lineNumber !== "number" ||
+      !Number.isSafeInteger(finding.lineNumber) ||
+      finding.lineNumber < 1 ||
+      finding.lineNumber > lines.length
+    )
+      throw new TypeError("Invalid Markdown lint cached finding");
+    const line = lines[finding.lineNumber - 1];
+    if (line === undefined) throw new TypeError("Invalid Markdown lint cached line");
+    const range = parseMarkdownLintRange(finding.range, line);
+    if (range === undefined) throw new TypeError("Invalid Markdown lint cached range");
+    return Object.freeze({
+      lineNumber: finding.lineNumber,
+      range,
+      rule: finding.rule
+    });
+  });
+  return Object.freeze({ findings: Object.freeze(findings) });
+}
+
+function isMarkdownLintRuleName(value: unknown): value is MarkdownLintRuleName {
+  return typeof value === "string" && MARKDOWN_LINT_RULE_NAMES.some((rule) => rule === value);
+}
+
+function installedMarkdownlintVersion(): string | undefined {
+  try {
+    const packageJson: unknown = createRequire(import.meta.url)("markdownlint/package.json");
+    const metadata = snapshotClosedRecord(packageJson);
+    return typeof metadata?.version === "string" && metadata.version.length > 0
+      ? metadata.version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/package-checks/markdown-lint/options-resolution.ts

@@ -0,0 +1,102 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import {
+  defaultProjectFileSelection,
+  resolveProjectFileSelection,
+  snapshotProjectFileSelection
+} from "../project-files/configuration.ts";
+import { DEFAULT_FINDING_POLICY, resolveFindingPolicy } from "../code-quality-findings/policy.ts";
+import { resolveFindingWaiverAuthoring } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { resolveOptionalLocalCacheOptions } from "../local-cache-options.ts";
+import { resolveMarkdownLintFindingIdentity } from "./finding-waiver-identity.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintRuleName,
+  type ResolvedMarkdownLintOptions
+} from "./options.ts";
+import { validMarkdownLintOptions } from "./options-validation.ts";
+
+const DEFAULT_FILES = Object.freeze({
+  exclude: defaultProjectFileSelection.exclude,
+  include: Object.freeze(["**/*.[mM][dD]", "**/*.[mM][aA][rR][kK][dD][oO][wW][nN]"]),
+  source: defaultProjectFileSelection.source
+});
+const DEFAULT_LIMITS = Object.freeze({ maxMarkdownBytes: 1_048_576, maxFindings: 10_000 });
+const DEFAULT_RULES = Object.freeze(
+  MARKDOWN_LINT_RULE_NAMES.filter((rule) => rule !== "link-fragments")
+);
+const KNOWN_RULES = new Set<string>(MARKDOWN_LINT_RULE_NAMES);
+
+/** Resolves closed partial authoring options into an immutable complete policy. */
+export function resolveMarkdownLintOptions(
+  value: unknown
+): ResolvedMarkdownLintOptions | undefined {
+  const input = snapshotClosedRecord(value);
+  if (
+    input === undefined ||
+    !hasRequiredAndOptionalRecordKeys(input, {
+      optional: ["files", "findingPolicy", "findingWaivers", "rules", "limits", "cache"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+  const files =
+    input.files === undefined
+      ? snapshotProjectFileSelection(DEFAULT_FILES)
+      : resolveProjectFileSelection(input.files, DEFAULT_FILES);
+  const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
+  const findingWaivers = resolveFindingWaiverAuthoring(
+    input.findingWaivers,
+    resolveMarkdownLintFindingIdentity
+  );
+  const rules = resolveRules(input.rules);
+  const limits = resolveLimits(input.limits);
+  const cache = resolveOptionalLocalCacheOptions(input.cache);
+  const candidate = Object.freeze({
+    files,
+    findingPolicy,
+    findingWaivers,
+    rules,
+    limits,
+    cache
+  });
+  return validMarkdownLintOptions(candidate) ? candidate : undefined;
+}
+
+function resolveRules(value: unknown): readonly MarkdownLintRuleName[] | undefined {
+  if (value === undefined) return DEFAULT_RULES;
+  const rules = snapshotClosedArray(value);
+  if (
+    rules === undefined ||
+    rules.length === 0 ||
+    !rules.every((rule) => typeof rule === "string" && KNOWN_RULES.has(rule)) ||
+    new Set(rules).size !== rules.length
+  ) {
+    return undefined;
+  }
+  return Object.freeze(
+    MARKDOWN_LINT_RULE_NAMES.filter((catalogRule) => rules.includes(catalogRule))
+  );
+}
+
+function resolveLimits(value: unknown): ResolvedMarkdownLintOptions["limits"] | undefined {
+  if (value === undefined) return DEFAULT_LIMITS;
+  const limits = snapshotClosedRecord(value);
+  if (
+    limits === undefined ||
+    !hasRequiredAndOptionalRecordKeys(limits, {
+      optional: ["maxMarkdownBytes", "maxFindings"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+  const maxMarkdownBytes = limits.maxMarkdownBytes ?? DEFAULT_LIMITS.maxMarkdownBytes;
+  const maxFindings = limits.maxFindings ?? DEFAULT_LIMITS.maxFindings;
+  if (typeof maxMarkdownBytes !== "number" || typeof maxFindings !== "number") return undefined;
+  return Object.freeze({ maxMarkdownBytes, maxFindings });
+}