@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,306 @@
+import path from "node:path";
+
+import type { MarkdownHeading, ParsedMarkdownLinkFacts } from "./markdown-parser.ts";
+
+type RootExternalTargetMode = "ignore" | "report" | "validate";
+const NOT_LOCAL_FILE_URI: unique symbol = Symbol("not-local-file-uri");
+
+/** Markdown local-link finding Record 的稳定 reason。 */
+export type MarkdownLinkFindingReason =
+  | "anchor-on-directory"
+  | "anchor-target-not-markdown"
+  | "empty-directory"
+  | "missing-anchor"
+  | "missing-target"
+  | "target-outside-project-root"
+  | "unsupported-target-type";
+
+type MarkdownLocalResolutionReason =
+  | "invalid-local-destination"
+  | "target-read-limit-exceeded"
+  | "target-unavailable";
+
+type MarkdownSourceReadFailureReason =
+  | "markdown-parse-failed"
+  | "source-unavailable"
+  | "source-too-large";
+
+interface MarkdownLinkSource {
+  readonly path: string;
+  readonly facts: ParsedMarkdownLinkFacts;
+}
+
+interface MarkdownLocalResolver {
+  readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
+  resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+  readonly targetReadCount: number;
+}
+
+interface MarkdownLocalResolutionRequest {
+  readonly source: MarkdownLinkSource;
+  readonly rawDestination: string;
+  readonly rootExternalTargetMode: RootExternalTargetMode;
+  readonly requireExistingTargets: boolean;
+  readonly requireNonEmptyDirectories: boolean;
+  readonly validateSameDocumentAnchors: boolean;
+  readonly validateCrossDocumentAnchors: boolean;
+  readonly maxMarkdownBytes: number;
+}
+
+type MarkdownLocalResolverCreation =
+  | Readonly<{ readonly ok: true; readonly resolver: MarkdownLocalResolver }>
+  | Readonly<{ readonly ok: false; readonly reason: "project-root-unavailable" }>;
+
+type MarkdownSourceReadResult =
+  | Readonly<{ readonly ok: true; readonly source: MarkdownLinkSource }>
+  | Readonly<{
+      readonly ok: false;
+      readonly reason: MarkdownSourceReadFailureReason;
+    }>;
+
+type MarkdownLocalResolution =
+  | Readonly<{ readonly kind: "not-local" | "ignored" }>
+  | Readonly<{ readonly kind: "valid"; readonly target: MarkdownSafeTargetDescriptor }>
+  | Readonly<{
+      readonly kind: "finding";
+      readonly reason: MarkdownLinkFindingReason;
+      readonly target: MarkdownSafeTargetDescriptor;
+    }>
+  | Readonly<{ readonly kind: "unavailable"; readonly reason: MarkdownLocalResolutionReason }>;
+
+type MarkdownSafeTargetDescriptor =
+  | Readonly<{
+      readonly kind: "same-document" | "project-file" | "project-directory" | "project-path";
+      readonly path: string;
+      readonly fragment: string | null;
+    }>
+  | Readonly<{ readonly kind: "outside-project-root" }>;
+
+interface ParsedLocalDestination {
+  readonly path: string;
+  readonly fragment: string | null;
+  readonly isAbsolute: boolean;
+}
+
+interface RootContainedPath {
+  readonly kind: "contained" | "missing";
+  readonly absolutePath: string;
+}
+
+type RootProbe =
+  | RootContainedPath
+  | Readonly<{ readonly kind: "outside" }>
+  | Readonly<{ readonly kind: "unavailable" }>;
+
+type EndpointProbe =
+  | Readonly<{ readonly kind: "missing" }>
+  | Readonly<{ readonly kind: "directory" | "file" | "unsupported" | "unavailable" }>;
+
+export function parseLocalDestination(
+  rawDestination: string
+): ParsedLocalDestination | "not-local" | null {
+  if (rawDestination.startsWith("//") || rawDestination.startsWith("\\\\")) {
+    return "not-local";
+  }
+  if (isHostWindowsDriveAbsolute(rawDestination)) {
+    return parsePathAndFragment(rawDestination, false);
+  }
+  const scheme = /^([A-Za-z][A-Za-z\d+.-]*):/u.exec(rawDestination);
+  if (scheme !== null) {
+    if (scheme[1]?.toLowerCase() !== "file") {
+      return "not-local";
+    }
+    return parseFileDestination(rawDestination);
+  }
+  if (path.sep !== "\\" && /^[A-Za-z]:[\\/]/u.test(rawDestination)) {
+    return "not-local";
+  }
+  return parsePathAndFragment(rawDestination, false);
+}
+
+function parseFileDestination(rawDestination: string): ParsedLocalDestination | "not-local" | null {
+  const match = /^file:\/\/(\/.*)$/iu.exec(rawDestination);
+  if (match === null) {
+    return "not-local";
+  }
+  const uriPathAndFragment = match[1];
+  if (uriPathAndFragment === undefined || uriPathAndFragment.startsWith("//")) {
+    return "not-local";
+  }
+  if (hasUriQuery(uriPathAndFragment) || containsUnsafeRawFileCharacter(uriPathAndFragment)) {
+    return "not-local";
+  }
+  const parsed = parsePathAndFragment(uriPathAndFragment, true);
+  if (parsed === null || parsed === "not-local") {
+    return parsed;
+  }
+  return Object.freeze({ ...parsed, isAbsolute: true });
+}
+
+function parsePathAndFragment(
+  rawDestination: string,
+  isFileUri: boolean
+): ParsedLocalDestination | "not-local" | null {
+  const hashIndex = rawDestination.indexOf("#");
+  const queryIndex = rawDestination.indexOf("?");
+  const pathEnd = [hashIndex, queryIndex]
+    .filter((index) => index >= 0)
+    .reduce((smallest, index) => Math.min(smallest, index), rawDestination.length);
+  const rawPath = rawDestination.slice(0, pathEnd);
+  const rawFragment = hashIndex >= 0 ? rawDestination.slice(hashIndex + 1) : null;
+  const decodedPath = decodeLocalComponent(rawPath);
+  const decodedFragment = rawFragment === null ? null : decodeLocalComponent(rawFragment);
+  if (decodedPath === null || (decodedFragment === null && rawFragment !== null)) {
+    return null;
+  }
+  const resolvedPath = isFileUri ? hostFileUriPath(decodedPath) : decodedPath;
+  if (resolvedPath === null) return null;
+  if (resolvedPath === NOT_LOCAL_FILE_URI) return "not-local";
+  return Object.freeze({
+    path: resolvedPath,
+    fragment: decodedFragment,
+    isAbsolute: isFileUri || path.isAbsolute(resolvedPath)
+  });
+}
+
+function decodeLocalComponent(rawComponent: string): string | null {
+  if (containsControlCharacter(rawComponent) || /%(?:2f|5c|00|0[0-9a-f]|7f)/iu.test(rawComponent)) {
+    return null;
+  }
+  try {
+    const decoded = decodeURIComponent(rawComponent);
+    return containsControlCharacter(decoded) ? null : decoded;
+  } catch {
+    return null;
+  }
+}
+
+function isHostWindowsDriveAbsolute(value: string): boolean {
+  return path.sep === "\\" && /^[A-Za-z]:[\\/]/u.test(value);
+}
+
+function hostFileUriPath(decodedPath: string): string | typeof NOT_LOCAL_FILE_URI | null {
+  if (decodedPath.includes("\\")) return null;
+  if (path.sep === "\\") {
+    if (!/^\/[A-Za-z]:\//u.test(decodedPath)) return NOT_LOCAL_FILE_URI;
+    return path.normalize(decodedPath.slice(1));
+  }
+  if (/^\/[A-Za-z]:\//u.test(decodedPath)) return NOT_LOCAL_FILE_URI;
+  return path.isAbsolute(decodedPath) ? decodedPath : null;
+}
+
+function hasUriQuery(uriPathAndFragment: string): boolean {
+  const queryIndex = uriPathAndFragment.indexOf("?");
+  if (queryIndex < 0) return false;
+  const fragmentIndex = uriPathAndFragment.indexOf("#");
+  return fragmentIndex < 0 || queryIndex < fragmentIndex;
+}
+
+export function anchorResolution(
+  headings: readonly MarkdownHeading[],
+  fragment: string,
+  target: MarkdownSafeTargetDescriptor
+): MarkdownLocalResolution {
+  return headings.some((heading) => heading.slug === fragment)
+    ? valid(target)
+    : finding("missing-anchor", target);
+}
+
+export function isRootRelativePath(
+  canonicalProjectRoot: string,
+  rootRelativePath: string
+): boolean {
+  return (
+    !path.isAbsolute(rootRelativePath) &&
+    isWithinRoot(canonicalProjectRoot, path.resolve(canonicalProjectRoot, rootRelativePath))
+  );
+}
+
+export function isWithinRoot(root: string, candidate: string): boolean {
+  const relativePath = path.relative(root, candidate);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith(`..${path.sep}`) &&
+      relativePath !== ".." &&
+      !path.isAbsolute(relativePath))
+  );
+}
+
+export function relativeSegments(root: string, candidate: string): string[] {
+  const relativePath = path.relative(root, candidate);
+  return relativePath === ""
+    ? []
+    : relativePath.split(path.sep).filter((segment) => segment !== "");
+}
+
+export function sameRootRelativePath(
+  rootRelativePath: string,
+  targetPath: string,
+  canonicalProjectRoot: string
+): boolean {
+  return toSlashPath(path.relative(canonicalProjectRoot, targetPath)) === rootRelativePath;
+}
+
+export function isMarkdownPath(targetPath: string): boolean {
+  const extension = path.extname(targetPath).toLowerCase();
+  return extension === ".md" || extension === ".markdown";
+}
+
+export function toSlashPath(filePath: string): string {
+  return filePath.split(path.sep).join("/");
+}
+
+function containsUnsafeRawFileCharacter(value: string): boolean {
+  return value.includes("\\") || containsControlCharacter(value) || /\s/u.test(value);
+}
+
+function containsControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (
+      codePoint !== undefined &&
+      (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+export function sourceUnavailable(): MarkdownSourceReadResult {
+  return Object.freeze({ ok: false as const, reason: "source-unavailable" as const });
+}
+
+export function valid(target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution {
+  return Object.freeze({ kind: "valid" as const, target });
+}
+
+export function finding(
+  reason: MarkdownLinkFindingReason,
+  target: MarkdownSafeTargetDescriptor
+): MarkdownLocalResolution {
+  return Object.freeze({ kind: "finding" as const, reason, target });
+}
+
+export function unavailable(reason: MarkdownLocalResolutionReason): MarkdownLocalResolution {
+  return Object.freeze({ kind: "unavailable" as const, reason });
+}
+
+export type {
+  MarkdownLinkSource,
+  MarkdownLocalResolution,
+  MarkdownLocalResolutionReason,
+  MarkdownLocalResolver,
+  MarkdownLocalResolverCreation,
+  MarkdownLocalResolutionRequest,
+  MarkdownSafeTargetDescriptor,
+  MarkdownSourceReadResult,
+  MarkdownSourceReadFailureReason,
+  RootProbe,
+  EndpointProbe,
+  RootExternalTargetMode
+};

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

@@ -0,0 +1,51 @@
+import { realpath } from "node:fs/promises";
+
+import { LinkLocalResolver } from "./resolver-engine.ts";
+import type { MarkdownLocalResolverCreation } from "./local-resolution.ts";
+
+/** Link-private, per-invocation state for source reads and direct local targets. */
+export async function createMarkdownLocalResolver(
+  projectRoot: string,
+  maxTargetReads: number
+): Promise<MarkdownLocalResolverCreation> {
+  try {
+    const canonicalProjectRoot = await realpath(projectRoot);
+    return Object.freeze({
+      ok: true as const,
+      resolver: new LinkLocalResolver(canonicalProjectRoot, maxTargetReads)
+    });
+  } catch {
+    return Object.freeze({ ok: false as const, reason: "project-root-unavailable" as const });
+  }
+}
+
+export {
+  anchorResolution,
+  finding,
+  isMarkdownPath,
+  isNotFound,
+  isRootRelativePath,
+  isWithinRoot,
+  parseLocalDestination,
+  relativeSegments,
+  sameRootRelativePath,
+  sourceUnavailable,
+  toSlashPath,
+  unavailable,
+  valid
+} from "./local-resolution.ts";
+export type {
+  EndpointProbe,
+  MarkdownLinkFindingReason,
+  MarkdownLinkSource,
+  MarkdownLocalResolution,
+  MarkdownLocalResolutionReason,
+  MarkdownLocalResolutionRequest,
+  MarkdownLocalResolver,
+  MarkdownLocalResolverCreation,
+  MarkdownSafeTargetDescriptor,
+  MarkdownSourceReadFailureReason,
+  MarkdownSourceReadResult,
+  RootExternalTargetMode,
+  RootProbe
+} from "./local-resolution.ts";

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

@@ -0,0 +1,302 @@
+import GithubSlugger from "github-slugger";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { frontmatter } from "micromark-extension-frontmatter";
+import { gfm } from "micromark-extension-gfm";
+
+interface MarkdownAstPoint {
+  readonly line: number;
+  readonly column: number;
+  readonly offset?: number;
+}
+
+interface MarkdownAstPosition {
+  readonly start: MarkdownAstPoint;
+  readonly end: MarkdownAstPoint;
+}
+
+interface MarkdownAstNode {
+  readonly type: string;
+  readonly position?: MarkdownAstPosition;
+  readonly children?: readonly MarkdownAstNode[];
+  readonly value?: string;
+  readonly url?: string;
+  readonly identifier?: string;
+  readonly alt?: string | null;
+}
+
+type MarkdownOccurrenceKind = "image" | "link";
+
+interface MarkdownSourcePosition {
+  readonly line: number;
+  readonly column: number;
+}
+
+interface MarkdownSourceRange {
+  readonly startOffset: number;
+  readonly endOffset: number;
+  readonly start: MarkdownSourcePosition;
+  readonly end: MarkdownSourcePosition;
+}
+
+interface MarkdownLinkOccurrence {
+  readonly kind: MarkdownOccurrenceKind;
+  readonly rawDestination: string;
+  readonly range: MarkdownSourceRange;
+}
+
+interface MarkdownHeading {
+  readonly slug: string;
+  readonly range: MarkdownSourceRange;
+}
+
+interface ParsedMarkdownLinkFacts {
+  readonly occurrences: readonly MarkdownLinkOccurrence[];
+  readonly headings: readonly MarkdownHeading[];
+}
+
+type MarkdownLinkParseResult =
+  | Readonly<{
+      readonly ok: true;
+      readonly facts: ParsedMarkdownLinkFacts;
+    }>
+  | Readonly<{
+      readonly ok: false;
+      readonly reason: "markdown-parse-failure";
+    }>;
+
+/**
+ * Link-private Markdown grammar adapter. It deliberately exposes facts rather
+ * than the dependency AST, so resolver ownership starts after parsing.
+ */
+export function parseMarkdownLinkFacts(markdown: string): MarkdownLinkParseResult {
+  if (hasUnpairedSurrogate(markdown)) {
+    return parseFailure();
+  }
+
+  try {
+    const tree: unknown = fromMarkdown(markdown, {
+      extensions: [gfm(), frontmatter(["yaml"])],
+      mdastExtensions: [gfmFromMarkdown(), frontmatterFromMarkdown(["yaml"])]
+    });
+    if (!isMarkdownAstNode(tree)) {
+      return parseFailure();
+    }
+    return collectMarkdownLinkFacts(tree);
+  } catch {
+    return parseFailure();
+  }
+}
+
+function collectMarkdownLinkFacts(tree: MarkdownAstNode): MarkdownLinkParseResult {
+  const definitions = definitionsByIdentifier(tree);
+  const occurrences: MarkdownLinkOccurrence[] = [];
+  const headings: MarkdownHeading[] = [];
+  const slugger = new GithubSlugger();
+
+  forEachNode(tree, (node) => {
+    const occurrence = occurrenceFromNode(node, definitions);
+    if (occurrence !== null) {
+      occurrences.push(occurrence);
+    }
+
+    if (node.type === "heading") {
+      const heading = headingFromNode(node, slugger);
+      if (heading === null) {
+        throw new Error("Markdown heading did not include a source range.");
+      }
+      headings.push(heading);
+    }
+  });
+
+  return Object.freeze({
+    ok: true as const,
+    facts: Object.freeze({
+      occurrences: Object.freeze(occurrences),
+      headings: Object.freeze(headings)
+    })
+  });
+}
+
+function definitionsByIdentifier(tree: MarkdownAstNode): ReadonlyMap<string, string> {
+  const definitions = new Map<string, string>();
+
+  forEachNode(tree, (node) => {
+    if (node.type !== "definition") {
+      return;
+    }
+    if (node.identifier === undefined || node.url === undefined) {
+      throw new Error("Markdown definition was missing a destination.");
+    }
+    if (!definitions.has(node.identifier)) {
+      definitions.set(node.identifier, node.url);
+    }
+  });
+
+  return definitions;
+}
+
+function occurrenceFromNode(
+  node: MarkdownAstNode,
+  definitions: ReadonlyMap<string, string>
+): MarkdownLinkOccurrence | null {
+  if (node.type === "link") {
+    return occurrenceFromResource(node, "link");
+  }
+  if (node.type === "image") {
+    return occurrenceFromResource(node, "image");
+  }
+  if (node.type === "linkReference") {
+    return occurrenceFromReference(node, "link", definitions);
+  }
+  if (node.type === "imageReference") {
+    return occurrenceFromReference(node, "image", definitions);
+  }
+  return null;
+}
+
+function occurrenceFromResource(
+  node: MarkdownAstNode,
+  kind: MarkdownOccurrenceKind
+): MarkdownLinkOccurrence | null {
+  if (node.url === undefined) {
+    throw new Error("Markdown occurrence was missing a destination.");
+  }
+  return occurrenceWithDestination(node, kind, node.url);
+}
+
+function occurrenceWithDestination(
+  node: MarkdownAstNode,
+  kind: MarkdownOccurrenceKind,
+  rawDestination: string
+): MarkdownLinkOccurrence | null {
+  const range = sourceRangeFromPosition(node.position);
+  if (range === null) {
+    throw new Error("Markdown occurrence did not include a source range.");
+  }
+  return Object.freeze({ kind, rawDestination, range });
+}
+
+function occurrenceFromReference(
+  node: MarkdownAstNode,
+  kind: MarkdownOccurrenceKind,
+  definitions: ReadonlyMap<string, string>
+): MarkdownLinkOccurrence | null {
+  if (node.identifier === undefined) {
+    throw new Error("Markdown reference was missing an identifier.");
+  }
+  const rawDestination = definitions.get(node.identifier);
+  if (rawDestination === undefined) {
+    return null;
+  }
+  return occurrenceWithDestination(node, kind, rawDestination);
+}
+
+function headingFromNode(node: MarkdownAstNode, slugger: GithubSlugger): MarkdownHeading | null {
+  const range = sourceRangeFromPosition(node.position);
+  if (range === null) {
+    return null;
+  }
+  return Object.freeze({
+    slug: slugger.slug(markdownText(node)),
+    range
+  });
+}
+
+function markdownText(node: MarkdownAstNode): string {
+  if (node.value !== undefined) {
+    return node.value;
+  }
+  if (node.children !== undefined) {
+    return node.children.map(markdownText).join("");
+  }
+  if (node.type === "image" || node.type === "imageReference") {
+    return node.alt ?? "";
+  }
+  return "";
+}
+
+function isMarkdownAstNode(value: unknown): value is MarkdownAstNode {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("type" in value) ||
+    !("children" in value) ||
+    !Array.isArray(value.children)
+  ) {
+    return false;
+  }
+  return typeof value.type === "string";
+}
+
+function sourceRangeFromPosition(
+  position: MarkdownAstPosition | undefined
+): MarkdownSourceRange | null {
+  if (
+    position === undefined ||
+    position.start.offset === undefined ||
+    position.end.offset === undefined
+  ) {
+    return null;
+  }
+
+  return Object.freeze({
+    startOffset: position.start.offset,
+    endOffset: position.end.offset,
+    start: Object.freeze({ line: position.start.line, column: position.start.column }),
+    end: Object.freeze({ line: position.end.line, column: position.end.column })
+  });
+}
+
+function forEachNode(root: MarkdownAstNode, visitor: (node: MarkdownAstNode) => void): void {
+  const nodes: MarkdownAstNode[] = [root];
+
+  while (nodes.length > 0) {
+    const node = nodes.pop();
+    if (node === undefined) {
+      return;
+    }
+    visitor(node);
+    if (node.children !== undefined) {
+      for (let index = node.children.length - 1; index >= 0; index -= 1) {
+        const child = node.children[index];
+        if (child !== undefined) {
+          nodes.push(child);
+        }
+      }
+    }
+  }
+}
+
+function hasUnpairedSurrogate(markdown: string): boolean {
+  for (let index = 0; index < markdown.length; index += 1) {
+    const codeUnit = markdown.charCodeAt(index);
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const nextCodeUnit = markdown.charCodeAt(index + 1);
+      if (!(nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff)) {
+        return true;
+      }
+      index += 1;
+      continue;
+    }
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseFailure(): MarkdownLinkParseResult {
+  return Object.freeze({ ok: false as const, reason: "markdown-parse-failure" as const });
+}
+
+export type {
+  MarkdownHeading,
+  MarkdownLinkOccurrence,
+  MarkdownLinkParseResult,
+  MarkdownOccurrenceKind,
+  MarkdownSourcePosition,
+  MarkdownSourceRange,
+  ParsedMarkdownLinkFacts
+};