@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,114 @@
+import { canonicalizeJsonObject } from "../../data-boundary/canonical-data.ts";
+import {
+  hasRequiredAndOptionalRecordKeys,
+  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 type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+import { validMarkdownLinkValidationOptions } from "./options-validation.ts";
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxMarkdownBytes: 1_048_576,
+  maxOccurrences: 10_000,
+  maxTargetReads: 1_000
+});
+const DEFAULT_FILES = Object.freeze({
+  exclude: defaultProjectFileSelection.exclude,
+  include: Object.freeze(["**/*.[mM][dD]", "**/*.[mM][aA][rR][kK][dD][oO][wW][nN]"]),
+  source: defaultProjectFileSelection.source
+});
+
+/** 将可省略 Markdown link policy 物化为完整、冻结的 execution options。 */
+export function resolveMarkdownLinkValidationOptions(
+  value: unknown
+): ResolvedMarkdownLinkValidationOptions | undefined {
+  const input = snapshotClosedRecord(value);
+  if (!isMarkdownLinkValidationInput(input)) return undefined;
+  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);
+  return candidate !== undefined && validMarkdownLinkValidationOptions(candidate)
+    ? candidate
+    : undefined;
+}
+
+function optionsCandidate(
+  input: Readonly<Record<string, unknown>>,
+  files: Exclude<ReturnType<typeof resolvedFiles>, undefined>,
+  findingPolicy: Exclude<ReturnType<typeof resolveFindingPolicy>, undefined>,
+  limits: Readonly<Record<string, unknown>>
+) {
+  return canonicalizeJsonObject({
+    files,
+    findingPolicy,
+    requireExistingTargets:
+      input.requireExistingTargets === undefined ? true : input.requireExistingTargets,
+    validateSameDocumentAnchors:
+      input.validateSameDocumentAnchors === undefined ? true : input.validateSameDocumentAnchors,
+    validateCrossDocumentAnchors:
+      input.validateCrossDocumentAnchors === undefined ? true : input.validateCrossDocumentAnchors,
+    rootExternalTargetMode:
+      input.rootExternalTargetMode === undefined ? "report" : input.rootExternalTargetMode,
+    requireNonEmptyDirectories:
+      input.requireNonEmptyDirectories === undefined ? false : input.requireNonEmptyDirectories,
+    limits
+  });
+}
+
+function isMarkdownLinkValidationInput(
+  input: Readonly<Record<string, unknown>> | undefined
+): input is Readonly<Record<string, unknown>> {
+  return (
+    input !== undefined &&
+    hasRequiredAndOptionalRecordKeys(input, {
+      optional: [
+        "files",
+        "findingPolicy",
+        "requireExistingTargets",
+        "validateSameDocumentAnchors",
+        "validateCrossDocumentAnchors",
+        "rootExternalTargetMode",
+        "requireNonEmptyDirectories",
+        "limits"
+      ],
+      required: []
+    })
+  );
+}
+
+function resolvedFiles(value: unknown) {
+  return value === undefined
+    ? snapshotProjectFileSelection(DEFAULT_FILES)
+    : resolveProjectFileSelection(value, DEFAULT_FILES);
+}
+
+function resolvedLimits(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  if (value === undefined) return DEFAULT_LIMITS;
+  const limits = snapshotClosedRecord(value);
+  if (
+    limits === undefined ||
+    !hasRequiredAndOptionalRecordKeys(limits, {
+      optional: ["maxMarkdownBytes", "maxOccurrences", "maxTargetReads"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    maxMarkdownBytes:
+      limits.maxMarkdownBytes === undefined
+        ? DEFAULT_LIMITS.maxMarkdownBytes
+        : limits.maxMarkdownBytes,
+    maxOccurrences:
+      limits.maxOccurrences === undefined ? DEFAULT_LIMITS.maxOccurrences : limits.maxOccurrences,
+    maxTargetReads:
+      limits.maxTargetReads === undefined ? DEFAULT_LIMITS.maxTargetReads : limits.maxTargetReads
+  });
+}

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

@@ -0,0 +1,72 @@
+import {
+  hasExactPlainRecordKeys,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import { validFindingPolicy } from "../code-quality-findings/policy.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+
+function exactRecord(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function boundedPositiveSafeInteger(value: unknown, maximum: number): value is number {
+  return positiveSafeInteger(value) && value <= maximum;
+}
+
+export function validMarkdownLinkValidationOptions(
+  value: unknown
+): value is ResolvedMarkdownLinkValidationOptions {
+  const options = exactRecord(value, [
+    "files",
+    "findingPolicy",
+    "requireExistingTargets",
+    "validateSameDocumentAnchors",
+    "validateCrossDocumentAnchors",
+    "rootExternalTargetMode",
+    "requireNonEmptyDirectories",
+    "limits"
+  ]);
+  return options !== undefined && validOptionFields(options);
+}
+
+function validOptionFields(options: Readonly<Record<string, unknown>>): boolean {
+  return (
+    validProjectFileSelection(options.files) &&
+    validFindingPolicy(options.findingPolicy) &&
+    validAnchorValidationOptions(options) &&
+    validMarkdownLinkLimits(options.limits)
+  );
+}
+
+function validAnchorValidationOptions(options: Readonly<Record<string, unknown>>): boolean {
+  return (
+    typeof options.requireExistingTargets === "boolean" &&
+    typeof options.validateSameDocumentAnchors === "boolean" &&
+    typeof options.validateCrossDocumentAnchors === "boolean" &&
+    validRootExternalTargetMode(options.rootExternalTargetMode) &&
+    typeof options.requireNonEmptyDirectories === "boolean"
+  );
+}
+
+function validRootExternalTargetMode(value: unknown): boolean {
+  return value === "ignore" || value === "report" || value === "validate";
+}
+
+function validMarkdownLinkLimits(value: unknown): boolean {
+  const limits = exactRecord(value, ["maxMarkdownBytes", "maxOccurrences", "maxTargetReads"]);
+  return (
+    limits !== undefined &&
+    boundedPositiveSafeInteger(limits.maxMarkdownBytes, 16_777_216) &&
+    boundedPositiveSafeInteger(limits.maxOccurrences, 100_000) &&
+    boundedPositiveSafeInteger(limits.maxTargetReads, 10_000)
+  );
+}

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

@@ -0,0 +1,50 @@
+import type {
+  ProjectFileSelection,
+  ProjectFileSelectionOptions
+} from "../project-files/configuration.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+
+export type MarkdownRootExternalTargetMode = "ignore" | "report" | "validate";
+
+/** 可省略的 Markdown validation work limits。 */
+export interface MarkdownLinkValidationLimitOptions {
+  readonly maxMarkdownBytes?: number;
+  readonly maxOccurrences?: number;
+  readonly maxTargetReads?: number;
+}
+
+/** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */
+export interface MarkdownLinkValidationOptions {
+  /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */
+  readonly files?: ProjectFileSelectionOptions;
+  /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** `false` 时缺失的本地文件或目录不构成 finding。 */
+  readonly requireExistingTargets?: boolean;
+  /** 是否检查 `#anchor` 对当前 Markdown 文档标题的引用。 */
+  readonly validateSameDocumentAnchors?: boolean;
+  /** 是否检查直接指向的 Markdown 文件中的 `#anchor`。 */
+  readonly validateCrossDocumentAnchors?: boolean;
+  /** root 外本机目标的授权模式；不授权网络请求。 */
+  readonly rootExternalTargetMode?: MarkdownRootExternalTargetMode;
+  /** 是否将空目录目标视为 finding。 */
+  readonly requireNonEmptyDirectories?: boolean;
+  /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */
+  readonly limits?: MarkdownLinkValidationLimitOptions;
+}
+
+/** `markdown-link-validation` execution 消费的完整、冻结 options。 */
+export interface ResolvedMarkdownLinkValidationOptions {
+  readonly files: ProjectFileSelection;
+  readonly findingPolicy: FindingPolicy;
+  readonly requireExistingTargets: boolean;
+  readonly validateSameDocumentAnchors: boolean;
+  readonly validateCrossDocumentAnchors: boolean;
+  readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;
+  readonly requireNonEmptyDirectories: boolean;
+  readonly limits: Readonly<{
+    readonly maxMarkdownBytes: number;
+    readonly maxOccurrences: number;
+    readonly maxTargetReads: number;
+  }>;
+}

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

@@ -0,0 +1,77 @@
+import type {
+  MarkdownLinkFindingReason,
+  MarkdownLocalResolution,
+  MarkdownSafeTargetDescriptor
+} from "./local-resolver.ts";
+import type { MarkdownLinkOccurrence, MarkdownSourceRange } from "./markdown-parser.ts";
+
+/** 一条本地 Markdown link finding supplemental Record 的 data。 */
+export type MarkdownLinkFindingRecordData = Readonly<{
+  readonly occurrenceKind: "link" | "image";
+  readonly range: Readonly<{
+    readonly end: Readonly<{ readonly column: number; readonly line: number }>;
+    readonly start: Readonly<{ readonly column: number; readonly line: number }>;
+  }>;
+  readonly reason: MarkdownLinkFindingReason;
+  readonly sourcePath: string;
+  readonly target: MarkdownSafeTargetDescriptor;
+}>;
+
+/** 一条 files policy 已选中但不受 Markdown Link 支持的输入 Finding。 */
+export type MarkdownLinkInputRejectedRecordData = Readonly<{
+  readonly blocking: false;
+  readonly kind: "input-rejected";
+  readonly path: string;
+  readonly reason: "unsupported-file-type";
+}>;
+
+/** Markdown Link 发布的 link 或 input-rejection Record data。 */
+export type MarkdownLinkValidationRecordData =
+  | MarkdownLinkFindingRecordData
+  | MarkdownLinkInputRejectedRecordData;
+
+export interface MarkdownLinkRecordCandidate {
+  readonly data: MarkdownLinkFindingRecordData;
+  readonly id: string;
+}
+
+export function buildMarkdownLinkRecordCandidate(
+  sourcePath: string,
+  occurrenceIndex: number,
+  occurrence: MarkdownLinkOccurrence,
+  resolution: MarkdownLocalResolution
+): MarkdownLinkRecordCandidate | undefined {
+  if (resolution.kind !== "finding") return undefined;
+  return Object.freeze({
+    id: `source:${encodeURIComponent(sourcePath)}:occurrence:${occurrenceIndex + 1}:reason:${resolution.reason}`,
+    data: Object.freeze({
+      reason: resolution.reason,
+      occurrenceKind: occurrence.kind,
+      sourcePath,
+      range: publicRange(occurrence.range),
+      target: resolution.target
+    })
+  });
+}
+
+export function buildMarkdownInputRejectedRecord(path: string): Readonly<{
+  readonly data: MarkdownLinkInputRejectedRecordData;
+  readonly id: string;
+}> {
+  return Object.freeze({
+    data: Object.freeze({
+      blocking: false,
+      kind: "input-rejected",
+      path,
+      reason: "unsupported-file-type"
+    }),
+    id: `/input-rejected/${path}`
+  });
+}
+
+function publicRange(range: MarkdownSourceRange): MarkdownLinkFindingRecordData["range"] {
+  return Object.freeze({
+    start: Object.freeze({ line: range.start.line, column: range.start.column }),
+    end: Object.freeze({ line: range.end.line, column: range.end.column })
+  });
+}

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

@@ -0,0 +1,276 @@
+import { opendir } from "node:fs/promises";
+import path from "node:path";
+
+import { parseMarkdownLinkFacts } from "./markdown-parser.ts";
+import {
+  directoryTarget,
+  fileTargetDescriptor,
+  outsideProjectRootTarget,
+  projectTarget
+} from "./target-descriptor.ts";
+import { probeEndpoint, probeRootContainedPath, readRegularFile } from "./filesystem-probes.ts";
+import {
+  anchorResolution,
+  finding,
+  isMarkdownPath,
+  isRootRelativePath,
+  isWithinRoot,
+  parseLocalDestination,
+  sameRootRelativePath,
+  sourceUnavailable,
+  toSlashPath,
+  unavailable,
+  valid,
+  type MarkdownLocalResolution,
+  type MarkdownLocalResolutionRequest,
+  type MarkdownLocalResolver,
+  type MarkdownSafeTargetDescriptor,
+  type MarkdownSourceReadResult
+} from "./local-resolution.ts";
+
+export class LinkLocalResolver implements MarkdownLocalResolver {
+  #targetReadCount = 0;
+  readonly #canonicalProjectRoot: string;
+  readonly #maxTargetReads: number;
+
+  constructor(canonicalProjectRoot: string, maxTargetReads: number) {
+    this.#canonicalProjectRoot = canonicalProjectRoot;
+    this.#maxTargetReads = maxTargetReads;
+  }
+
+  get targetReadCount(): number {
+    return this.#targetReadCount;
+  }
+
+  async readSource(
+    rootRelativePath: string,
+    maxMarkdownBytes: number
+  ): Promise<MarkdownSourceReadResult> {
+    if (!isRootRelativePath(this.#canonicalProjectRoot, rootRelativePath)) {
+      return sourceUnavailable();
+    }
+
+    const sourcePath = path.resolve(this.#canonicalProjectRoot, rootRelativePath);
+    const rootProbe = await probeRootContainedPath(this.#canonicalProjectRoot, sourcePath);
+    if (
+      rootProbe.kind === "outside" ||
+      rootProbe.kind === "unavailable" ||
+      rootProbe.kind === "missing"
+    ) {
+      return sourceUnavailable();
+    }
+
+    const sourceBytes = await readRegularFile(rootProbe.absolutePath, maxMarkdownBytes);
+    if (!sourceBytes.ok) {
+      return sourceBytes.reason === "too-large"
+        ? Object.freeze({ ok: false as const, reason: "source-too-large" as const })
+        : sourceUnavailable();
+    }
+
+    let markdown: string;
+    try {
+      markdown = new TextDecoder("utf-8", { fatal: true }).decode(sourceBytes.bytes);
+    } catch {
+      return sourceUnavailable();
+    }
+
+    const parsed = parseMarkdownLinkFacts(markdown);
+    if (!parsed.ok) {
+      return Object.freeze({ ok: false as const, reason: "markdown-parse-failed" as const });
+    }
+
+    return Object.freeze({
+      ok: true as const,
+      source: Object.freeze({
+        path: toSlashPath(path.relative(this.#canonicalProjectRoot, sourcePath)),
+        facts: parsed.facts
+      })
+    });
+  }
+
+  async resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution> {
+    const destination = parseLocalDestination(request.rawDestination);
+    if (destination === "not-local") {
+      return Object.freeze({ kind: "not-local" as const });
+    }
+    if (destination === null) {
+      return unavailable("invalid-local-destination");
+    }
+
+    let targetPath: string;
+    if (destination.path === "") {
+      targetPath = path.resolve(this.#canonicalProjectRoot, request.source.path);
+    } else if (destination.isAbsolute) {
+      targetPath = path.normalize(destination.path);
+    } else {
+      targetPath = path.resolve(
+        this.#canonicalProjectRoot,
+        path.dirname(request.source.path),
+        destination.path
+      );
+    }
+    const isSameDocument =
+      !destination.isAbsolute &&
+      sameRootRelativePath(request.source.path, targetPath, this.#canonicalProjectRoot);
+    if (isSameDocument) {
+      return this.resolveSameDocument(destination.fragment, request);
+    }
+    const lexicalTargetIsExternal =
+      destination.isAbsolute || !isWithinRoot(this.#canonicalProjectRoot, targetPath);
+
+    if (lexicalTargetIsExternal) {
+      return this.resolveExternalTarget(targetPath, destination.fragment, request);
+    }
+
+    return this.resolveRootContainedTarget(targetPath, destination.fragment, request);
+  }
+
+  async resolveRootContainedTarget(
+    targetPath: string,
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest
+  ): Promise<MarkdownLocalResolution> {
+    const rootProbe = await probeRootContainedPath(this.#canonicalProjectRoot, targetPath);
+    if (rootProbe.kind === "outside") {
+      return this.resolveExternalTarget(targetPath, fragment, request);
+    }
+    if (rootProbe.kind === "unavailable") {
+      return unavailable("target-unavailable");
+    }
+    if (rootProbe.kind === "missing") {
+      if (!this.beginTargetValidation()) {
+        return unavailable("target-read-limit-exceeded");
+      }
+      const target = projectTarget(this.#canonicalProjectRoot, targetPath, fragment);
+      return request.requireExistingTargets ? finding("missing-target", target) : valid(target);
+    }
+    if (!this.beginTargetValidation()) {
+      return unavailable("target-read-limit-exceeded");
+    }
+    return this.resolveEndpoint(
+      rootProbe.absolutePath,
+      fragment,
+      request,
+      projectTarget(this.#canonicalProjectRoot, targetPath, fragment)
+    );
+  }
+
+  async resolveExternalTarget(
+    targetPath: string,
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest
+  ): Promise<MarkdownLocalResolution> {
+    if (request.rootExternalTargetMode === "ignore") {
+      return Object.freeze({ kind: "ignored" as const });
+    }
+    if (request.rootExternalTargetMode === "report") {
+      return finding("target-outside-project-root", outsideProjectRootTarget());
+    }
+    if (!this.beginTargetValidation()) {
+      return unavailable("target-read-limit-exceeded");
+    }
+    return this.resolveEndpoint(targetPath, fragment, request, outsideProjectRootTarget());
+  }
+
+  async resolveEndpoint(
+    targetPath: string,
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest,
+    target: MarkdownSafeTargetDescriptor
+  ): Promise<MarkdownLocalResolution> {
+    const endpoint = await probeEndpoint(targetPath);
+    if (endpoint.kind === "missing") {
+      return request.requireExistingTargets ? finding("missing-target", target) : valid(target);
+    }
+    if (endpoint.kind === "unavailable") {
+      return unavailable("target-unavailable");
+    }
+    if (endpoint.kind === "directory") {
+      return this.resolveDirectory(targetPath, fragment, request, directoryTarget(target));
+    }
+    if (endpoint.kind === "unsupported") {
+      return finding("unsupported-target-type", target);
+    }
+
+    return this.resolveFile(targetPath, fragment, request, fileTargetDescriptor(target));
+  }
+
+  async resolveFile(
+    targetPath: string,
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest,
+    target: MarkdownSafeTargetDescriptor
+  ): Promise<MarkdownLocalResolution> {
+    if (fragment === null || !request.validateCrossDocumentAnchors) {
+      return valid(target);
+    }
+    if (!isMarkdownPath(targetPath)) {
+      return finding("anchor-target-not-markdown", target);
+    }
+
+    const targetMarkdown = await readRegularFile(targetPath, request.maxMarkdownBytes);
+    if (!targetMarkdown.ok) {
+      return unavailable("target-unavailable");
+    }
+    let decodedTarget: string;
+    try {
+      decodedTarget = new TextDecoder("utf-8", { fatal: true }).decode(targetMarkdown.bytes);
+    } catch {
+      return unavailable("target-unavailable");
+    }
+    const parsedTarget = parseMarkdownLinkFacts(decodedTarget);
+    if (!parsedTarget.ok) {
+      return unavailable("target-unavailable");
+    }
+    return anchorResolution(parsedTarget.facts.headings, fragment, target);
+  }
+
+  async resolveDirectory(
+    targetPath: string,
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest,
+    target: MarkdownSafeTargetDescriptor
+  ): Promise<MarkdownLocalResolution> {
+    if (fragment !== null) {
+      return finding("anchor-on-directory", target);
+    }
+    if (!request.requireNonEmptyDirectories) {
+      return valid(target);
+    }
+    try {
+      const directory = await opendir(targetPath);
+      try {
+        return (await directory.read()) === null
+          ? finding("empty-directory", target)
+          : valid(target);
+      } finally {
+        await directory.close();
+      }
+    } catch {
+      return unavailable("target-unavailable");
+    }
+  }
+
+  beginTargetValidation(): boolean {
+    if (this.#targetReadCount >= this.#maxTargetReads) {
+      return false;
+    }
+    this.#targetReadCount += 1;
+    return true;
+  }
+
+  resolveSameDocument(
+    fragment: string | null,
+    request: MarkdownLocalResolutionRequest
+  ): MarkdownLocalResolution {
+    const target = Object.freeze({
+      kind: "same-document" as const,
+      path: request.source.path,
+      fragment
+    });
+    if (fragment === null || !request.validateSameDocumentAnchors) {
+      return valid(target);
+    }
+    return anchorResolution(request.source.facts.headings, fragment, target);
+  }
+}

package/src/package-checks/markdown-link-validation/target-descriptor.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+
+import { toSlashPath, type MarkdownSafeTargetDescriptor } from "./local-resolution.ts";
+
+export function projectTarget(
+  canonicalProjectRoot: string,
+  targetPath: string,
+  fragment: string | null,
+  kind: "project-directory" | "project-file" | "project-path" = "project-path"
+): MarkdownSafeTargetDescriptor {
+  return Object.freeze({
+    kind,
+    path: toSlashPath(path.relative(canonicalProjectRoot, targetPath)),
+    fragment
+  });
+}
+
+export function outsideProjectRootTarget(): MarkdownSafeTargetDescriptor {
+  return Object.freeze({ kind: "outside-project-root" as const });
+}
+
+export function fileTargetDescriptor(
+  target: MarkdownSafeTargetDescriptor
+): MarkdownSafeTargetDescriptor {
+  if (target.kind === "outside-project-root") return target;
+  return Object.freeze({ ...target, kind: "project-file" as const });
+}
+
+export function directoryTarget(
+  target: MarkdownSafeTargetDescriptor
+): MarkdownSafeTargetDescriptor {
+  if (target.kind === "outside-project-root") return target;
+  return Object.freeze({ ...target, kind: "project-directory" as const });
+}

package/src/package-checks/markdown-link-validation/traversal-result.ts

@@ -0,0 +1,58 @@
+import type { CheckMessage, CheckResult } from "../../check/check.ts";
+
+import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+
+/** Materializes one completed source traversal into its Check-owned final result. */
+export function settledMarkdownTraversalResult(
+  input: Readonly<{
+    readonly findingCount: number;
+    readonly findingPolicy: ResolvedMarkdownLinkValidationOptions["findingPolicy"];
+    readonly occurrenceCount: number;
+    readonly rejectedInputCount: number;
+    readonly sourceFileCount: number;
+    readonly targetReadCount: number;
+  }>
+): CheckResult<MarkdownLinkValidationFinalData> {
+  const data = Object.freeze({
+    sourceFileCount: input.sourceFileCount,
+    occurrenceCount: input.occurrenceCount,
+    targetReadCount: input.targetReadCount,
+    findingCount: input.findingCount + input.rejectedInputCount,
+    rejectedInputCount: input.rejectedInputCount
+  });
+  const messages: CheckMessage[] = [];
+  if (input.findingCount > 0) messages.push(linkFindingMessage(input));
+  if (input.rejectedInputCount > 0) messages.push(rejectedInputMessage(input.rejectedInputCount));
+  if (messages.length === 0) return Object.freeze({ data, status: "passed" });
+  const isBlocking = input.findingPolicy === "blocking";
+  return Object.freeze({
+    data,
+    messages: Object.freeze(messages),
+    status: isBlocking && input.findingCount > 0 ? "failed" : "passed"
+  });
+}
+
+function linkFindingMessage(
+  input: Readonly<{
+    readonly findingCount: number;
+    readonly findingPolicy: ResolvedMarkdownLinkValidationOptions["findingPolicy"];
+  }>
+): CheckMessage {
+  const isBlocking = input.findingPolicy === "blocking";
+  return Object.freeze({
+    code: "invalid-local-links",
+    level: isBlocking ? ("error" as const) : ("warning" as const),
+    message: isBlocking
+      ? `${input.findingCount} local Markdown link finding(s) require attention; inspect this Check's Records for source ranges, targets, and reasons.`
+      : `${input.findingCount} local Markdown link finding(s) were recorded as non-blocking; inspect this Check's Records for source ranges, targets, and reasons.`
+  });
+}
+
+function rejectedInputMessage(rejectedInputCount: number): CheckMessage {
+  return Object.freeze({
+    code: "input-rejected",
+    level: "warning" as const,
+    message: `${rejectedInputCount} selected markdownLinkValidation input file(s) were rejected because only .md/.markdown paths are supported; inspect this Check's Records and narrow files.include/exclude.`
+  });
+}