@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,325 @@
+import path from "node:path";
+
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { collectProjectFiles } from "../project-files/collection.ts";
+import type { ProjectFileSelection } from "../project-files/configuration.ts";
+import { partitionProjectFilesByEligibility } from "../project-files/input-eligibility.ts";
+import {
+  createMarkdownLocalResolver,
+  type MarkdownLocalResolutionReason,
+  type MarkdownLocalResolver,
+  type MarkdownSourceReadFailureReason
+} from "./local-resolver.ts";
+import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+import {
+  buildMarkdownInputRejectedRecord,
+  buildMarkdownLinkRecordCandidate,
+  type MarkdownLinkRecordCandidate
+} from "./records.ts";
+import { settledMarkdownTraversalResult } from "./traversal-result.ts";
+import { validMarkdownLinkValidationOptions } from "./options-validation.ts";
+
+export const MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION = {
+  checkId: "markdown-link-validation",
+  displayName: "Markdown link validation"
+} as const;
+
+interface MarkdownLinkValidationRun {
+  readonly options: ResolvedMarkdownLinkValidationOptions;
+  readonly resolver: MarkdownLocalResolver;
+  readonly signal: AbortSignal;
+}
+
+/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MarkdownLinkValidationUnavailableReason =
+  | "invalid-options"
+  | "cancelled"
+  | "occurrence-limit-exceeded"
+  | "project-root-unavailable"
+  | MarkdownLocalResolutionReason
+  | MarkdownSourceReadFailureReason;
+
+type MarkdownLinkValidationUnavailable = Readonly<{
+  readonly kind: "unavailable";
+  readonly reason: MarkdownLinkValidationUnavailableReason;
+}>;
+
+type MarkdownSourceDiscovery =
+  | Readonly<{
+      readonly kind: "complete";
+      readonly rejectedPaths: readonly string[];
+      readonly selectedPathCount: number;
+      readonly sourcePaths: readonly string[];
+    }>
+  | MarkdownLinkValidationUnavailable;
+
+type MarkdownSourceValidation =
+  | Readonly<{
+      readonly kind: "complete";
+      readonly candidates: readonly MarkdownLinkRecordCandidate[];
+      readonly occurrenceCount: number;
+    }>
+  | MarkdownLinkValidationUnavailable;
+
+type MarkdownLinkTraversal =
+  | Readonly<{
+      readonly kind: "complete";
+      readonly candidates: readonly MarkdownLinkRecordCandidate[];
+      readonly occurrenceCount: number;
+      readonly sourceFileCount: number;
+    }>
+  | MarkdownLinkValidationUnavailable;
+
+/** 验证本 Check 选中的 Markdown source 的离线本地链接完整性。 */
+export async function executeMarkdownLinkValidation(
+  context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>
+): Promise<CheckResult<MarkdownLinkValidationFinalData>> {
+  if (!validMarkdownLinkValidationOptions(context.options)) return unavailable("invalid-options");
+  const prepared = await prepareMarkdownTraversal(context);
+  if (prepared.kind === "result") return prepared.result;
+  const { rejectedInputCount, traversal, resolver } = prepared;
+
+  for (const candidate of traversal.candidates) {
+    context.records.report({ id: candidate.id }, candidate.data);
+  }
+  return settledMarkdownTraversalResult({
+    findingCount: traversal.candidates.length,
+    findingPolicy: context.options.findingPolicy,
+    occurrenceCount: traversal.occurrenceCount,
+    rejectedInputCount,
+    sourceFileCount: traversal.sourceFileCount,
+    targetReadCount: resolver.targetReadCount
+  });
+}
+
+type PreparedMarkdownTraversal =
+  | Readonly<{
+      readonly kind: "result";
+      readonly result: CheckResult<MarkdownLinkValidationFinalData>;
+    }>
+  | Readonly<{
+      readonly kind: "traversal";
+      readonly rejectedInputCount: number;
+      readonly resolver: MarkdownLocalResolver;
+      readonly traversal: Extract<MarkdownLinkTraversal, { readonly kind: "complete" }>;
+    }>;
+
+async function prepareMarkdownTraversal(
+  context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>
+): Promise<PreparedMarkdownTraversal> {
+  if (context.signal.aborted) return result(unavailable("cancelled"));
+  const created = await createMarkdownLocalResolver(
+    context.project.root,
+    context.options.limits.maxTargetReads
+  );
+  if (!created.ok) return result(unavailable(created.reason));
+  if (context.signal.aborted) return result(unavailable("cancelled"));
+  const sourceDiscovery = discoverMarkdownSourcePaths(context.project, context.options.files);
+  if (sourceDiscovery.kind === "unavailable") return result(unavailable(sourceDiscovery.reason));
+  if (sourceDiscovery.selectedPathCount === 0) return result(noEligibleInput());
+  if (context.signal.aborted) return result(unavailable("cancelled"));
+  reportRejectedInputs(context, sourceDiscovery.rejectedPaths);
+  const traversal = await traverseMarkdownSources(sourceDiscovery.sourcePaths, {
+    resolver: created.resolver,
+    options: context.options,
+    signal: context.signal
+  });
+  if (traversal.kind === "unavailable") {
+    return result(
+      appendRejectedInputMessage(
+        unavailable(traversal.reason),
+        sourceDiscovery.rejectedPaths.length
+      )
+    );
+  }
+  if (context.signal.aborted) {
+    return result(
+      appendRejectedInputMessage(unavailable("cancelled"), sourceDiscovery.rejectedPaths.length)
+    );
+  }
+  return Object.freeze({
+    kind: "traversal",
+    rejectedInputCount: sourceDiscovery.rejectedPaths.length,
+    resolver: created.resolver,
+    traversal
+  });
+}
+
+function result(
+  checkResult: CheckResult<MarkdownLinkValidationFinalData>
+): PreparedMarkdownTraversal {
+  return Object.freeze({ kind: "result", result: checkResult });
+}
+
+function noEligibleInput(): CheckResult<MarkdownLinkValidationFinalData> {
+  return Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } });
+}
+
+function discoverMarkdownSourcePaths(
+  project: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>["project"],
+  files: ProjectFileSelection
+): MarkdownSourceDiscovery {
+  try {
+    const selectedPaths = collectProjectFiles(project.root, files);
+    const partition = partitionProjectFilesByEligibility(selectedPaths, isMarkdownSourcePath);
+    return Object.freeze({
+      kind: "complete" as const,
+      rejectedPaths: partition.rejectedPaths,
+      selectedPathCount: selectedPaths.length,
+      sourcePaths: partition.acceptedPaths
+    });
+  } catch {
+    return unavailableValidation("source-unavailable");
+  }
+}
+
+function reportRejectedInputs(
+  context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>,
+  paths: readonly string[]
+): void {
+  for (const selectedPath of paths) {
+    const record = buildMarkdownInputRejectedRecord(selectedPath);
+    context.records.report({ id: record.id }, record.data);
+  }
+}
+
+function appendRejectedInputMessage(
+  checkResult: CheckResult<MarkdownLinkValidationFinalData>,
+  rejectedInputCount: number
+): CheckResult<MarkdownLinkValidationFinalData> {
+  if (rejectedInputCount === 0) return checkResult;
+  return Object.freeze({
+    ...checkResult,
+    messages: Object.freeze([
+      ...(checkResult.messages ?? []),
+      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.`
+      })
+    ])
+  });
+}
+
+function unavailableValidation(
+  reason: MarkdownLinkValidationUnavailableReason
+): MarkdownLinkValidationUnavailable {
+  return Object.freeze({ kind: "unavailable", reason });
+}
+
+async function traverseMarkdownSources(
+  sourcePaths: readonly string[],
+  run: MarkdownLinkValidationRun
+): Promise<MarkdownLinkTraversal> {
+  const candidates: MarkdownLinkRecordCandidate[] = [];
+  let occurrenceCount = 0;
+  let sourceFileCount = 0;
+
+  for (const sourcePath of sourcePaths) {
+    const sourceValidation = await validateMarkdownSource(sourcePath, occurrenceCount, run);
+    if (sourceValidation.kind === "unavailable") return sourceValidation;
+
+    candidates.push(...sourceValidation.candidates);
+    occurrenceCount = sourceValidation.occurrenceCount;
+    sourceFileCount += 1;
+  }
+
+  return Object.freeze({
+    kind: "complete" as const,
+    candidates: Object.freeze(candidates),
+    occurrenceCount,
+    sourceFileCount
+  });
+}
+
+async function validateMarkdownSource(
+  sourcePath: string,
+  occurrenceCountBeforeSource: number,
+  run: MarkdownLinkValidationRun
+): Promise<MarkdownSourceValidation> {
+  if (run.signal.aborted) return unavailableValidation("cancelled");
+  const sourceRead = await run.resolver.readSource(sourcePath, run.options.limits.maxMarkdownBytes);
+  if (run.signal.aborted) return unavailableValidation("cancelled");
+  if (!sourceRead.ok) return unavailableValidation(sourceRead.reason);
+
+  const candidates: MarkdownLinkRecordCandidate[] = [];
+  let occurrenceCount = occurrenceCountBeforeSource;
+  for (const [occurrenceIndex, occurrence] of sourceRead.source.facts.occurrences.entries()) {
+    if (run.signal.aborted) return unavailableValidation("cancelled");
+    occurrenceCount += 1;
+    if (occurrenceCount > run.options.limits.maxOccurrences) {
+      return unavailableValidation("occurrence-limit-exceeded");
+    }
+
+    const resolution = await run.resolver.resolve({
+      source: sourceRead.source,
+      rawDestination: occurrence.rawDestination,
+      rootExternalTargetMode: run.options.rootExternalTargetMode,
+      requireExistingTargets: run.options.requireExistingTargets,
+      requireNonEmptyDirectories: run.options.requireNonEmptyDirectories,
+      validateSameDocumentAnchors: run.options.validateSameDocumentAnchors,
+      validateCrossDocumentAnchors: run.options.validateCrossDocumentAnchors,
+      maxMarkdownBytes: run.options.limits.maxMarkdownBytes
+    });
+    if (run.signal.aborted) return unavailableValidation("cancelled");
+    if (resolution.kind === "unavailable") return unavailableValidation(resolution.reason);
+    const candidate = buildMarkdownLinkRecordCandidate(
+      sourceRead.source.path,
+      occurrenceIndex,
+      occurrence,
+      resolution
+    );
+    if (candidate !== undefined) candidates.push(candidate);
+  }
+
+  return Object.freeze({
+    kind: "complete" as const,
+    candidates: Object.freeze(candidates),
+    occurrenceCount
+  });
+}
+
+function isMarkdownSourcePath(filePath: string): boolean {
+  const extension = path.extname(filePath).toLowerCase();
+  return extension === ".md" || extension === ".markdown";
+}
+
+function unavailable(
+  reason: MarkdownLinkValidationUnavailableReason
+): CheckResult<MarkdownLinkValidationFinalData> {
+  return Object.freeze({
+    status: "unavailable",
+    reason: { code: reason },
+    messages: Object.freeze([
+      Object.freeze({ code: reason, level: "error" as const, message: unavailableMessage(reason) })
+    ])
+  });
+}
+
+function unavailableMessage(reason: MarkdownLinkValidationUnavailableReason): string {
+  return UNAVAILABLE_MESSAGES[reason];
+}
+
+const UNAVAILABLE_MESSAGES: Readonly<Record<MarkdownLinkValidationUnavailableReason, string>> = {
+  "invalid-options":
+    "markdownLinkValidation options are invalid; recreate the Check with markdownLinkValidation(options) or restore its complete resolved options.",
+  "project-root-unavailable":
+    "Markdown link validation could not resolve the project root; check that the path exists and is accessible.",
+  "source-unavailable":
+    "A selected Markdown source could not be collected, read, decoded, or contained safely; check the file source and permissions.",
+  "source-too-large":
+    "A selected Markdown source exceeds maxMarkdownBytes; narrow the file selection or raise the bounded limit.",
+  "markdown-parse-failed":
+    "A selected Markdown source could not be parsed completely; inspect that document's Markdown syntax and encoding.",
+  "invalid-local-destination":
+    "A local Markdown destination could not be parsed safely; inspect the affected link destination syntax.",
+  "target-unavailable":
+    "A local Markdown target could not be probed or read safely; check the target path, permissions, size, and encoding.",
+  "occurrence-limit-exceeded":
+    "Markdown link validation exceeded maxOccurrences; narrow the source selection or raise the bounded limit.",
+  "target-read-limit-exceeded":
+    "Markdown link validation exceeded maxTargetReads; narrow the source selection or raise the bounded limit.",
+  cancelled:
+    "Markdown link validation was cancelled before it could form a complete result; inspect the caller's cancellation reason and retry if appropriate."
+};

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

@@ -0,0 +1,127 @@
+import { constants } from "node:fs";
+import { lstat, open, readlink } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  isNotFound,
+  isWithinRoot,
+  relativeSegments,
+  type EndpointProbe,
+  type RootProbe
+} from "./local-resolution.ts";
+
+export async function probeRootContainedPath(
+  canonicalProjectRoot: string,
+  candidatePath: string
+): Promise<RootProbe> {
+  if (!isWithinRoot(canonicalProjectRoot, candidatePath)) {
+    return Object.freeze({ kind: "outside" as const });
+  }
+  let pendingSegments = relativeSegments(canonicalProjectRoot, candidatePath);
+  let currentPath = canonicalProjectRoot;
+  let symlinkHops = 0;
+
+  while (pendingSegments.length > 0) {
+    const segment = pendingSegments.shift();
+    if (segment === undefined) {
+      return Object.freeze({ kind: "unavailable" as const });
+    }
+    const nextPath = path.join(currentPath, segment);
+    let status: Awaited<ReturnType<typeof lstat>>;
+    try {
+      status = await lstat(nextPath);
+    } catch (error: unknown) {
+      if (isNotFound(error)) {
+        return Object.freeze({ kind: "missing" as const, absolutePath: nextPath });
+      }
+      return Object.freeze({ kind: "unavailable" as const });
+    }
+    if (!status.isSymbolicLink()) {
+      currentPath = nextPath;
+      continue;
+    }
+    if (symlinkHops >= 40) {
+      return Object.freeze({ kind: "unavailable" as const });
+    }
+    symlinkHops += 1;
+    let linkDestination: string;
+    try {
+      linkDestination = path.resolve(path.dirname(nextPath), await readlink(nextPath));
+    } catch {
+      return Object.freeze({ kind: "unavailable" as const });
+    }
+    if (!isWithinRoot(canonicalProjectRoot, linkDestination)) {
+      return Object.freeze({ kind: "outside" as const });
+    }
+    pendingSegments = [
+      ...relativeSegments(canonicalProjectRoot, linkDestination),
+      ...pendingSegments
+    ];
+    currentPath = canonicalProjectRoot;
+  }
+
+  return Object.freeze({ kind: "contained" as const, absolutePath: currentPath });
+}
+
+export async function probeEndpoint(targetPath: string): Promise<EndpointProbe> {
+  let status: Awaited<ReturnType<typeof lstat>>;
+  try {
+    status = await lstat(targetPath);
+  } catch (error: unknown) {
+    return isNotFound(error)
+      ? Object.freeze({ kind: "missing" as const })
+      : Object.freeze({ kind: "unavailable" as const });
+  }
+  if (status.isSymbolicLink()) {
+    return Object.freeze({ kind: "unavailable" as const });
+  }
+  if (status.isDirectory()) {
+    return Object.freeze({ kind: "directory" as const });
+  }
+  if (status.isFile()) {
+    return Object.freeze({ kind: "file" as const });
+  }
+  return Object.freeze({ kind: "unsupported" as const });
+}
+
+export async function readRegularFile(
+  filePath: string,
+  maxBytes: number
+): Promise<
+  | Readonly<{ readonly ok: true; readonly bytes: Uint8Array }>
+  | Readonly<{ readonly ok: false; readonly reason: "too-large" | "unavailable" }>
+> {
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const status = await handle.stat();
+    if (!status.isFile()) {
+      return Object.freeze({ ok: false as const, reason: "unavailable" as const });
+    }
+    if (status.size > maxBytes) {
+      return Object.freeze({ ok: false as const, reason: "too-large" as const });
+    }
+    const bytes = await readBoundedBytes(handle, maxBytes);
+    return bytes === null
+      ? Object.freeze({ ok: false as const, reason: "too-large" as const })
+      : Object.freeze({ ok: true as const, bytes });
+  } catch {
+    return Object.freeze({ ok: false as const, reason: "unavailable" as const });
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+async function readBoundedBytes(
+  handle: Awaited<ReturnType<typeof open>>,
+  maxBytes: number
+): Promise<Uint8Array | null> {
+  const bytes = new Uint8Array(maxBytes + 1);
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const result = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+    if (result.bytesRead === 0) break;
+    offset += result.bytesRead;
+  }
+  return offset > maxBytes ? null : bytes.slice(0, offset);
+}

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

@@ -0,0 +1,47 @@
+import {
+  exactFinalDataRecord,
+  invalidFinalData,
+  nonNegativeSafeInteger
+} from "../final-data-parsing.ts";
+
+/** `markdown-link-validation` 在 passed/failed outcome 中发布的主数据。 */
+export interface MarkdownLinkValidationFinalData {
+  readonly sourceFileCount: number;
+  readonly occurrenceCount: number;
+  readonly targetReadCount: number;
+  readonly findingCount: number;
+  readonly rejectedInputCount: number;
+}
+
+/** 验证计数不变量并脱离一份 canonical final-data object。 */
+export function parseMarkdownLinkValidationData(data: unknown): MarkdownLinkValidationFinalData {
+  const value = exactFinalDataRecord(
+    data,
+    ["sourceFileCount", "occurrenceCount", "targetReadCount", "findingCount", "rejectedInputCount"],
+    "markdownLinkValidation"
+  );
+  const sourceFileCount = nonNegativeSafeInteger(value.sourceFileCount);
+  const occurrenceCount = nonNegativeSafeInteger(value.occurrenceCount);
+  const targetReadCount = nonNegativeSafeInteger(value.targetReadCount);
+  const findingCount = nonNegativeSafeInteger(value.findingCount);
+  const rejectedInputCount = nonNegativeSafeInteger(value.rejectedInputCount);
+  if (
+    sourceFileCount === undefined ||
+    occurrenceCount === undefined ||
+    targetReadCount === undefined ||
+    findingCount === undefined ||
+    rejectedInputCount === undefined ||
+    targetReadCount > occurrenceCount ||
+    findingCount < rejectedInputCount ||
+    findingCount - rejectedInputCount > occurrenceCount
+  ) {
+    throw invalidFinalData("markdownLinkValidation");
+  }
+  return Object.freeze({
+    sourceFileCount,
+    occurrenceCount,
+    targetReadCount,
+    findingCount,
+    rejectedInputCount
+  });
+}