create-zudo-circuit-doc 0.1.0

package/templates/default/doc/scripts/check-links.js

@@ -0,0 +1,969 @@
+#!/usr/bin/env node
+
+/**
+ * Check links in a generated zudo-doc project.
+ *
+ * The source scan is intentionally useful before a build: generated projects
+ * do not need a dist/ directory for anchor validation. When dist/ exists, its
+ * HTML is checked as an additional pass.
+ */
+
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { extractAllHeadingIds } from "@takazudo/zudo-doc/extract-headings";
+
+const CLI_USAGE = `Usage: pnpm check:links -- [options]
+
+Options:
+  -h, --help           Show this help
+  --strict-broken      Fail when broken links remain after the allowlist
+  --strict-absolute    Fail when absolute MDX links remain after the allowlist
+  --strict-anchors     Fail when invalid anchors remain after the allowlist
+  --strict-trailing    Fail when trailing-slash warnings remain after the allowlist
+  --allowlist=PATH     Exclude exact <file>:<line>:<href> entries from failure counts`;
+
+class CliArgumentError extends Error {}
+
+function parseCliArgs(argv) {
+  const result = {
+    help: false,
+    strictBroken: false,
+    strictAbsolute: false,
+    strictAnchors: false,
+    strictTrailing: false,
+    allowlistPath: null,
+  };
+
+  for (const arg of argv) {
+    if (arg === "--") continue;
+    if (arg === "-h" || arg === "--help") result.help = true;
+    else if (arg === "--strict-broken") result.strictBroken = true;
+    else if (arg === "--strict-absolute") result.strictAbsolute = true;
+    else if (arg === "--strict-anchors") result.strictAnchors = true;
+    else if (arg === "--strict-trailing") result.strictTrailing = true;
+    else if (arg.startsWith("--allowlist=")) {
+      result.allowlistPath = arg.slice("--allowlist=".length);
+      if (!result.allowlistPath) {
+        throw new CliArgumentError("--allowlist requires a non-empty path");
+      }
+    } else {
+      throw new CliArgumentError(`Unknown option: ${arg}\n\n${CLI_USAGE}`);
+    }
+  }
+  return result;
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isDirectory(dirPath) {
+  try {
+    return (await stat(dirPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function collectFiles(dir, extensions) {
+  const files = [];
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) await walk(full);
+      else if (extensions.some((extension) => entry.name.endsWith(extension))) {
+        files.push(full);
+      }
+    }
+  }
+  await walk(dir);
+  return files.sort();
+}
+
+// ---------------------------------------------------------------------------
+// zfb.config.ts literal extraction
+// ---------------------------------------------------------------------------
+
+function skipTrivia(source, index, end = source.length) {
+  let cursor = index;
+  while (cursor < end) {
+    if (/\s/.test(source[cursor])) {
+      cursor += 1;
+      continue;
+    }
+    if (source.startsWith("//", cursor)) {
+      const newline = source.indexOf("\n", cursor + 2);
+      cursor = newline === -1 || newline >= end ? end : newline + 1;
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      const close = source.indexOf("*/", cursor + 2);
+      if (close === -1 || close + 2 > end) {
+        throw new Error("unterminated block comment");
+      }
+      cursor = close + 2;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
+function readStringEnd(source, start, end = source.length) {
+  const quote = source[start];
+  if (quote !== "\"" && quote !== "'") return null;
+  let cursor = start + 1;
+  while (cursor < end) {
+    if (source[cursor] === "\\") {
+      cursor += 2;
+      continue;
+    }
+    if (source[cursor] === quote) return cursor + 1;
+    cursor += 1;
+  }
+  throw new Error("unterminated string literal");
+}
+
+function readStringValue(source, start, end, fieldName) {
+  const valueStart = skipTrivia(source, start, end);
+  const valueEnd = readStringEnd(source, valueStart, end);
+  if (valueEnd === null || skipTrivia(source, valueEnd, end) !== end) {
+    throw new Error(
+      `zfb.config.ts field ${fieldName} must be a literal string (dynamic expressions are not supported)`,
+    );
+  }
+  const raw = source.slice(valueStart, valueEnd);
+  try {
+    if (raw[0] === '"') return JSON.parse(raw);
+    // Generated configs use JSON strings, but accepting ordinary single-
+    // quoted TypeScript literals makes the extractor useful for hand edits.
+    let result = "";
+    for (let i = 1; i < raw.length - 1; i += 1) {
+      if (raw[i] !== "\\") {
+        result += raw[i];
+        continue;
+      }
+      const escaped = raw[++i];
+      const escapes = {
+        n: "\n",
+        r: "\r",
+        t: "\t",
+        b: "\b",
+        f: "\f",
+        v: "\v",
+        "0": "\0",
+        "\\": "\\",
+        "'": "'",
+        '"': '"',
+      };
+      if (escaped === "u") {
+        const hex = raw.slice(i + 1, i + 5);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new Error("invalid unicode escape");
+        result += String.fromCharCode(Number.parseInt(hex, 16));
+        i += 4;
+      } else if (escaped === "x") {
+        const hex = raw.slice(i + 1, i + 3);
+        if (!/^[0-9a-fA-F]{2}$/.test(hex)) throw new Error("invalid hex escape");
+        result += String.fromCharCode(Number.parseInt(hex, 16));
+        i += 2;
+      } else if (escaped in escapes) result += escapes[escaped];
+      else throw new Error(`unsupported escape \\${escaped}`);
+    }
+    return result;
+  } catch (error) {
+    throw new Error(`zfb.config.ts field ${fieldName} has an invalid string literal: ${error.message}`);
+  }
+}
+
+function matchingDelimiter(source, start, end = source.length) {
+  const opening = source[start];
+  const pairs = { "{": "}", "[": "]", "(": ")" };
+  if (!(opening in pairs)) throw new Error(`expected an object/array/call at offset ${start}`);
+  const stack = [pairs[opening]];
+  let cursor = start + 1;
+  while (cursor < end) {
+    if (source[cursor] === "\"" || source[cursor] === "'") {
+      cursor = readStringEnd(source, cursor, end);
+      continue;
+    }
+    if (source.startsWith("//", cursor)) {
+      const newline = source.indexOf("\n", cursor + 2);
+      cursor = newline === -1 || newline >= end ? end : newline + 1;
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      const close = source.indexOf("*/", cursor + 2);
+      if (close === -1 || close + 2 > end) throw new Error("unterminated block comment");
+      cursor = close + 2;
+      continue;
+    }
+    if (source[cursor] in pairs) stack.push(pairs[source[cursor]]);
+    else if (source[cursor] === stack.at(-1)) stack.pop();
+    else if (source[cursor] === "}" || source[cursor] === "]" || source[cursor] === ")") {
+      throw new Error(`unexpected delimiter ${source[cursor]} in zfb.config.ts`);
+    }
+    if (stack.length === 0) return cursor;
+    cursor += 1;
+  }
+  throw new Error("unterminated literal in zfb.config.ts");
+}
+
+function valueEndAtComma(source, start, end) {
+  const stack = [];
+  let cursor = start;
+  while (cursor < end) {
+    if (source[cursor] === "\"" || source[cursor] === "'") {
+      cursor = readStringEnd(source, cursor, end);
+      continue;
+    }
+    if (source.startsWith("//", cursor)) {
+      const newline = source.indexOf("\n", cursor + 2);
+      cursor = newline === -1 || newline >= end ? end : newline + 1;
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      const close = source.indexOf("*/", cursor + 2);
+      if (close === -1 || close + 2 > end) throw new Error("unterminated block comment");
+      cursor = close + 2;
+      continue;
+    }
+    if (source[cursor] === "{" || source[cursor] === "[" || source[cursor] === "(") {
+      stack.push(source[cursor]);
+      cursor += 1;
+      continue;
+    }
+    if (source[cursor] === "}" || source[cursor] === "]" || source[cursor] === ")") {
+      if (stack.length === 0) return cursor;
+      stack.pop();
+      cursor += 1;
+      continue;
+    }
+    if (source[cursor] === "," && stack.length === 0) return cursor;
+    cursor += 1;
+  }
+  return end;
+}
+
+function parseObjectEntries(source, open, close, context) {
+  const entries = new Map();
+  let cursor = open + 1;
+  while (true) {
+    cursor = skipTrivia(source, cursor, close);
+    if (cursor >= close) break;
+    if (source.startsWith("...", cursor)) {
+      throw new Error(
+        `zfb.config.ts ${context} contains a spread; config fields must be literal values`,
+      );
+    }
+    let key;
+    if (source[cursor] === "\"" || source[cursor] === "'") {
+      const keyEnd = readStringEnd(source, cursor, close);
+      key = readStringValue(source, cursor, keyEnd, `${context} key`);
+      cursor = keyEnd;
+    } else {
+      const match = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(source.slice(cursor, close));
+      if (!match) throw new Error(`zfb.config.ts ${context} has an invalid property name`);
+      key = match[0];
+      cursor += key.length;
+    }
+    cursor = skipTrivia(source, cursor, close);
+    if (source[cursor] !== ":") {
+      const literalKind = key === "base" || key === "docsDir" ? "literal string" : "literal value";
+      throw new Error(`zfb.config.ts field ${key} must be a ${literalKind} (dynamic expressions are not supported)`);
+    }
+    const valueStart = cursor + 1;
+    const comma = valueEndAtComma(source, valueStart, close);
+    const previous = entries.get(key);
+    if (previous !== undefined) throw new Error(`zfb.config.ts declares ${context}.${key} more than once`);
+    entries.set(key, { start: valueStart, end: comma });
+    cursor = comma;
+    if (cursor < close && source[cursor] === ",") cursor += 1;
+    else if (cursor < close) throw new Error(`zfb.config.ts ${context} has an invalid separator`);
+  }
+  return entries;
+}
+
+function readLiteralBoolean(source, start, end, fieldName) {
+  const valueStart = skipTrivia(source, start, end);
+  for (const [literal, value] of [["true", true], ["false", false]]) {
+    const literalEnd = valueStart + literal.length;
+    if (source.slice(valueStart, literalEnd) === literal && skipTrivia(source, literalEnd, end) === end) {
+      return value;
+    }
+  }
+  throw new Error(
+    `zfb.config.ts field ${fieldName} must be the literal true or false (dynamic expressions are not supported)`,
+  );
+}
+
+function readObjectValue(source, start, end, fieldName) {
+  const valueStart = skipTrivia(source, start, end);
+  if (source[valueStart] !== "{") {
+    throw new Error(`zfb.config.ts field ${fieldName} must be a literal object`);
+  }
+  const valueClose = matchingDelimiter(source, valueStart, end);
+  if (skipTrivia(source, valueClose + 1, end) !== end) {
+    throw new Error(`zfb.config.ts field ${fieldName} must be a literal object (dynamic expressions are not supported)`);
+  }
+  return { open: valueStart, close: valueClose };
+}
+
+function findZudoDocCall(source) {
+  let cursor = 0;
+  let found = null;
+  while (cursor < source.length) {
+    if (source[cursor] === "\"" || source[cursor] === "'") {
+      cursor = readStringEnd(source, cursor);
+      continue;
+    }
+    if (source.startsWith("//", cursor)) {
+      const newline = source.indexOf("\n", cursor + 2);
+      cursor = newline === -1 ? source.length : newline + 1;
+      continue;
+    }
+    if (source.startsWith("/*", cursor)) {
+      const close = source.indexOf("*/", cursor + 2);
+      if (close === -1) throw new Error("unterminated block comment in zfb.config.ts");
+      cursor = close + 2;
+      continue;
+    }
+    if (source.startsWith("zudoDoc", cursor) && !/[A-Za-z0-9_$]/.test(source[cursor - 1] ?? "")) {
+      const afterName = cursor + "zudoDoc".length;
+      if (!/[A-Za-z0-9_$]/.test(source[afterName] ?? "")) {
+        const openParen = skipTrivia(source, afterName);
+        if (source[openParen] === "(") {
+          if (found !== null) throw new Error("zfb.config.ts must contain exactly one zudoDoc({...}) call");
+          found = openParen;
+          cursor = openParen + 1;
+          continue;
+        }
+      }
+    }
+    cursor += 1;
+  }
+  return found;
+}
+
+export async function parseZfbConfig(configPath) {
+  const source = await readFile(configPath, "utf-8");
+  const openParen = findZudoDocCall(source);
+  if (openParen === null) throw new Error("zfb.config.ts does not contain a zudoDoc({...}) call");
+  const closeParen = matchingDelimiter(source, openParen);
+  const objectOpen = skipTrivia(source, openParen + 1, closeParen);
+  if (source[objectOpen] !== "{") {
+    throw new Error("zfb.config.ts zudoDoc() argument must be a literal object (imports and spreads are not supported)");
+  }
+  const objectClose = matchingDelimiter(source, objectOpen, closeParen);
+  if (skipTrivia(source, objectClose + 1, closeParen) !== closeParen) {
+    throw new Error("zfb.config.ts zudoDoc() accepts one literal object argument");
+  }
+
+  const entries = parseObjectEntries(source, objectOpen, objectClose, "zudoDoc({...})");
+  const result = {
+    basePath: "/",
+    trailingSlash: false,
+    docsDir: "src/content/docs",
+    localeDirs: [],
+    localeKeys: [],
+  };
+
+  const base = entries.get("base");
+  if (base) result.basePath = readStringValue(source, base.start, base.end, "base");
+  const trailing = entries.get("trailingSlash");
+  if (trailing) result.trailingSlash = readLiteralBoolean(source, trailing.start, trailing.end, "trailingSlash");
+  const docsDir = entries.get("docsDir");
+  if (docsDir) result.docsDir = readStringValue(source, docsDir.start, docsDir.end, "docsDir");
+
+  const locales = entries.get("locales");
+  if (locales) {
+    const localeObject = readObjectValue(source, locales.start, locales.end, "locales");
+    const localeEntries = parseObjectEntries(source, localeObject.open, localeObject.close, "locales");
+    for (const [key, value] of localeEntries) {
+      const localeConfig = readObjectValue(source, value.start, value.end, `locales.${key}`);
+      const localeFields = parseObjectEntries(source, localeConfig.open, localeConfig.close, `locales.${key}`);
+      const dir = localeFields.get("dir");
+      if (!dir) {
+        throw new Error(`zfb.config.ts field locales.${key}.dir is required for link checking`);
+      }
+      result.localeKeys.push(key);
+      result.localeDirs.push(readStringValue(source, dir.start, dir.end, `locales.${key}.dir`));
+    }
+  }
+  return result;
+}
+
+export async function parseBasePath(configPath) {
+  return (await parseZfbConfig(configPath)).basePath;
+}
+
+export async function parseTrailingSlash(configPath) {
+  return (await parseZfbConfig(configPath)).trailingSlash;
+}
+
+export async function parseContentDirs(configPath) {
+  const config = await parseZfbConfig(configPath);
+  return {
+    docsDir: config.docsDir,
+    localeDirs: config.localeDirs,
+    localeKeys: config.localeKeys,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared link and anchor logic
+// ---------------------------------------------------------------------------
+
+const HTML_NAMED_CHARACTER_REFERENCES = {
+  amp: "&",
+  apos: "'",
+  gt: ">",
+  lt: "<",
+  quot: '"',
+};
+
+function decodeHtmlAttributeValue(value) {
+  return value.replace(
+    /&(?:#([0-9]+)|#x([0-9a-f]+)|(amp|apos|gt|lt|quot));/gi,
+    (_reference, decimal, hexadecimal, named) => {
+      if (named !== undefined) return HTML_NAMED_CHARACTER_REFERENCES[named.toLowerCase()];
+      const codePoint = Number.parseInt(hexadecimal ?? decimal, hexadecimal === undefined ? 10 : 16);
+      if (codePoint === 0 || codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return "\uFFFD";
+      return String.fromCodePoint(codePoint);
+    },
+  );
+}
+
+// Attribute-scan grammar shared by the anchor and id scans below. A quoted
+// attribute value may legally contain ">" (title="a > b"), so bounding an
+// attribute scan with [^>] silently drops the whole tag: a lost id is a noisy
+// false STRICT FAIL, while a lost href means the link is never checked at all
+// (#4046). This run crosses ">" only inside quotes, and a decoy `href=`/`id=`
+// written as text inside another attribute's value stays unreachable because a
+// quoted span is consumed whole. Each alternative starts with a distinct
+// character, so the repetition backtracks linearly.
+const HTML_ATTRIBUTE_RUN = /(?:"[^"]*"|'[^']*'|[^>"'])/.source;
+const HTML_ATTRIBUTE_VALUE = /(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))/.source;
+
+// Single shared anchor scan. Its one consumer, `classifyHtmlAnchorHrefs`,
+// splits these matches into disjoint buckets, so the grammar and the
+// incremental line counting live here once and every bucket sees a fix to the
+// anchor regex.
+function* iterateHtmlAnchorHrefs(html) {
+  const regex = new RegExp(
+    `<a(?=\\s)${HTML_ATTRIBUTE_RUN}*?\\shref\\s*=\\s*${HTML_ATTRIBUTE_VALUE}${HTML_ATTRIBUTE_RUN}*>`,
+    "gi",
+  );
+  let match;
+  let lastIndex = 0;
+  let line = 1;
+  while ((match = regex.exec(html)) !== null) {
+    for (let i = lastIndex; i < match.index; i += 1) if (html[i] === "\n") line += 1;
+    lastIndex = match.index;
+    yield { href: decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]), line };
+  }
+}
+
+// One anchor pass, two disjoint buckets: internal links to resolve, and the
+// protocol-relative hrefs that are external for resolution purposes but worth
+// reporting informationally (see #3921/#3930). The dist walk calls this once
+// per page; `extractHtmlLinks` / `extractProtocolRelativeHtmlLinks` below are
+// single-bucket views for callers that want only one of the two.
+export function classifyHtmlAnchorHrefs(html) {
+  const links = [];
+  const protocolRelative = [];
+  for (const { href, line } of iterateHtmlAnchorHrefs(html)) {
+    if (/^\/\//.test(href)) {
+      protocolRelative.push({ href, line });
+      continue;
+    }
+    if (/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
+    links.push({ href, line });
+  }
+  return { links, protocolRelative };
+}
+
+export function extractHtmlLinks(html) {
+  return classifyHtmlAnchorHrefs(html).links;
+}
+
+export function extractProtocolRelativeHtmlLinks(html) {
+  return classifyHtmlAnchorHrefs(html).protocolRelative;
+}
+
+export function extractHtmlIds(html) {
+  const ids = [];
+  const regex = new RegExp(
+    `<[A-Za-z]${HTML_ATTRIBUTE_RUN}*?\\sid\\s*=\\s*${HTML_ATTRIBUTE_VALUE}${HTML_ATTRIBUTE_RUN}*>`,
+    "gi",
+  );
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    ids.push(decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]));
+  }
+  return ids;
+}
+
+function safeDecodePath(path) {
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return path;
+  }
+}
+
+function parseHref(href) {
+  const hashAt = href.indexOf("#");
+  const beforeFragment = hashAt === -1 ? href : href.slice(0, hashAt);
+  const queryAt = beforeFragment.indexOf("?");
+  const rawPath = queryAt === -1 ? beforeFragment : beforeFragment.slice(0, queryAt);
+  const rawFragment = hashAt === -1 ? null : href.slice(hashAt + 1);
+  if (rawFragment === null) return { path: safeDecodePath(rawPath), rawPath, fragment: null, fragmentError: null };
+  if (rawFragment === "") return { path: safeDecodePath(rawPath), rawPath, fragment: "", fragmentError: "empty fragment" };
+  try {
+    return { path: safeDecodePath(rawPath), rawPath, fragment: decodeURIComponent(rawFragment), fragmentError: null };
+  } catch {
+    return { path: safeDecodePath(rawPath), rawPath, fragment: rawFragment, fragmentError: "malformed percent-encoding" };
+  }
+}
+
+function stripInlineCode(line) {
+  let result = line.replace(/(?<!\\)``[^`]*(?:``|$)/g, (match) => " ".repeat(match.length));
+  return result.replace(/(?<!\\)`[^`]*(?:`|$)/g, (match) => " ".repeat(match.length));
+}
+
+function assertLocaleList(locales) {
+  if (!Array.isArray(locales) || !locales.every((locale) => typeof locale === "string")) {
+    throw new TypeError("locales must be passed explicitly as an array of locale keys");
+  }
+}
+
+export function extractMdxAbsoluteLinks(content, locales) {
+  assertLocaleList(locales);
+  const localeAlternation = locales.length > 0
+    ? `(?:${locales.map((key) => `${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`).join("|")})?`
+    : "";
+  const issues = [];
+  const lines = content.split("\n");
+  let inCodeBlock = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^```/.test(line.trimStart())) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) continue;
+    const searchLine = stripInlineCode(line);
+    const mdRegex = new RegExp(`\\]\\((\\/${localeAlternation}docs\\/[^)]*)\\)`, "g");
+    let match;
+    while ((match = mdRegex.exec(searchLine)) !== null) issues.push({ href: match[1], line: i + 1 });
+    const jsxRegex = new RegExp(`href="(\\/${localeAlternation}docs\\/[^"]*)"`, "g");
+    while ((match = jsxRegex.exec(searchLine)) !== null) issues.push({ href: match[1], line: i + 1 });
+  }
+  return issues;
+}
+
+export function extractMdxFragmentLinks(content) {
+  const links = [];
+  const lines = content.split("\n");
+  let codeFenceOpener = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const fence = /^([`~]{3,})/.exec(line.trimStart())?.[1];
+    if (fence !== undefined) {
+      if (codeFenceOpener === null) codeFenceOpener = fence;
+      else if (fence[0] === codeFenceOpener[0] && fence.length >= codeFenceOpener.length) codeFenceOpener = null;
+      continue;
+    }
+    if (codeFenceOpener !== null) continue;
+    const searchLine = stripInlineCode(line);
+    let match;
+    const markdownLink = /\]\(\s*([^\s)#]*#[^\s)]*)(?:\s+[^)]*)?\)/g;
+    while ((match = markdownLink.exec(searchLine)) !== null) {
+      if (!/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(match[1])) links.push({ href: match[1], line: i + 1 });
+    }
+    const jsxHref = /\bhref\s*=\s*(?:"([^"]*#[^"]*)"|'([^']*#[^']*)')/g;
+    while ((match = jsxHref.exec(searchLine)) !== null) {
+      const href = match[1] ?? match[2];
+      if (!/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(href)) links.push({ href, line: i + 1 });
+    }
+  }
+  return links;
+}
+
+/** Include h5/h6 targets and use the same text extraction as rendered TOC IDs. */
+function allHierarchicalHeadingIds(body) {
+  return new Set(extractAllHeadingIds(body));
+}
+
+function extractStaticMdxIds(body) {
+  const ids = new Set();
+  let codeFenceOpener = null;
+  const visibleLines = [];
+  for (const line of body.split("\n")) {
+    const fence = /^([`~]{3,})/.exec(line.trimStart())?.[1];
+    if (fence !== undefined) {
+      if (codeFenceOpener === null) codeFenceOpener = fence;
+      else if (fence[0] === codeFenceOpener[0] && fence.length >= codeFenceOpener.length) codeFenceOpener = null;
+      visibleLines.push("");
+      continue;
+    }
+    visibleLines.push(codeFenceOpener === null ? stripInlineCode(line) : "");
+  }
+  const elements = visibleLines.join("\n");
+  // Same tokenising run as the built-HTML scans: a ">" inside a quoted MDX/JSX
+  // attribute value (title="a > b") must not truncate the tag and lose the id
+  // (#4048). The rest of this pattern keeps its own semantics — `\bid` also
+  // accepts `data-id`, and only non-empty quoted values count, unlike the
+  // built-HTML id scan.
+  //
+  // Two extra guards, scoped to this MDX scan only (the shared
+  // HTML_ATTRIBUTE_RUN above is untouched — the built-HTML scans still rely on
+  // multi-line quoted attributes):
+  //
+  // - MDX_UNESCAPED_LT_LOOKBEHIND: an escaped `\<` in prose is valid MDX and
+  //   must not start a fake tag. Parity matters, not just "preceded by a
+  //   backslash" — `\\<` is an escaped backslash followed by an active `<`.
+  //   The lookbehind is anchored at the run's start (`(?<!\\)`) so it judges
+  //   the whole contiguous backslash run, not a suffix of it.
+  // - MDX_ID_ATTRIBUTE_RUN: without this, a fake tag opened by an escaped `<`
+  //   can have prose apostrophes read as a `'...'` quoted value that crosses
+  //   a real `>` and swallows a real element's id on a later line (#4218).
+  //   Disallowing a blank line inside a quoted value bounds the damage to a
+  //   single paragraph while still letting a real JSX tag — including a
+  //   quoted value spanning one newline — match.
+  const MDX_UNESCAPED_LT_LOOKBEHIND = /(?<!(?<!\\)(?:\\\\)*\\)/.source;
+  const MDX_ID_ATTRIBUTE_RUN =
+    /(?:"(?:(?!\r?\n[ \t]*\r?\n)[^"])*"|'(?:(?!\r?\n[ \t]*\r?\n)[^'])*'|[^>"'])/.source;
+  const regex = new RegExp(
+    `${MDX_UNESCAPED_LT_LOOKBEHIND}<[A-Za-z]${MDX_ID_ATTRIBUTE_RUN}*?\\bid\\s*=\\s*(?:"([^"]+)"|'([^']+)')${MDX_ID_ATTRIBUTE_RUN}*>`,
+    "gs",
+  );
+  let match;
+  while ((match = regex.exec(elements)) !== null) ids.add(match[1] ?? match[2]);
+  return ids;
+}
+
+async function resolveMdxTarget(sourceFile, href, contentDirs, locales, basePath) {
+  const { path: decodedPath } = parseHref(href);
+  let rawPath = decodedPath;
+  if (basePath !== "/" && rawPath.startsWith(basePath)) rawPath = "/" + rawPath.slice(basePath.length);
+  let target;
+  if (rawPath === "") target = sourceFile;
+  else if (rawPath.startsWith("/docs/")) target = resolve(contentDirs[0], rawPath.slice("/docs/".length));
+  else {
+    const locale = locales.find((key) => rawPath.startsWith(`/${key}/docs/`));
+    if (locale !== undefined) {
+      const localeDir = contentDirs[locales.indexOf(locale) + 1];
+      if (localeDir === undefined) return null;
+      target = resolve(localeDir, rawPath.slice(`/${locale}/docs/`.length));
+    } else if (rawPath.startsWith("/")) return null;
+    else target = resolve(dirname(sourceFile), rawPath);
+  }
+  const candidates = extname(target)
+    ? [target]
+    : [target, `${target}.mdx`, `${target}.md`, resolve(target, "index.mdx"), resolve(target, "index.md")];
+  for (const candidate of candidates) {
+    if (await fileExists(candidate) && (await stat(candidate)).isFile()) return candidate;
+  }
+  return null;
+}
+
+export async function checkMdxAnchors(contentDirs, rootDir, basePath = "/", locales, excludePatterns = []) {
+  assertLocaleList(locales);
+  const anchors = [];
+  const idCache = new Map();
+  for (const dir of contentDirs) {
+    if (!(await fileExists(dir))) continue;
+    for (const file of await collectFiles(dir, [".mdx", ".md"])) {
+      const content = await readFile(file, "utf-8");
+      for (const { href, line } of extractMdxFragmentLinks(content)) {
+        if (excludePatterns.some((pattern) => pattern.test(href))) continue;
+        const parsed = parseHref(href);
+        if (parsed.fragmentError !== null) {
+          anchors.push({ file: relative(rootDir, file), line, href, fragment: parsed.fragment, reason: parsed.fragmentError });
+          continue;
+        }
+        const target = await resolveMdxTarget(file, href, contentDirs, locales, basePath);
+        if (target === null) continue;
+        let ids = idCache.get(target);
+        if (ids === undefined) {
+          const targetBody = await readFile(target, "utf-8");
+          ids = allHierarchicalHeadingIds(targetBody);
+          for (const id of extractStaticMdxIds(targetBody)) ids.add(id);
+          idCache.set(target, ids);
+        }
+        if (!ids.has(parsed.fragment)) anchors.push({ file: relative(rootDir, file), line, href, fragment: parsed.fragment, reason: "missing target id" });
+      }
+    }
+  }
+  return anchors;
+}
+
+async function resolveBuiltPath(path, distDir, basePath, fileDir) {
+  let absolute = path;
+  if (!path.startsWith("/")) absolute = "/" + join(fileDir ? relative(distDir, fileDir) : "", path);
+  let stripped = absolute;
+  if (basePath !== "/" && stripped.startsWith(basePath)) stripped = "/" + stripped.slice(basePath.length);
+  const relPath = stripped.startsWith("/") ? stripped.slice(1) : stripped;
+  if (!relPath) return { type: "root", targetFile: join(distDir, "index.html") };
+  // A terminal slash is an explicit directory request, even when the
+  // directory name contains a dot (for example, /files/demo/x.js/). Check it
+  // before extname() so viewer pages can keep their trailing-slash route and
+  // still receive fragment validation against index.html.
+  if (relPath.endsWith("/")) {
+    const indexFile = join(distDir, relPath, "index.html");
+    return (await fileExists(indexFile)) ? { type: "directoryIndex", targetFile: indexFile } : { type: "missing", targetFile: null };
+  }
+  if (extname(relPath)) {
+    const targetFile = join(distDir, relPath);
+    return (await fileExists(targetFile)) ? { type: "file", targetFile } : { type: "missing", targetFile: null };
+  }
+  const indexFile = join(distDir, relPath, "index.html");
+  if (await fileExists(indexFile)) return { type: "directoryIndex", targetFile: indexFile };
+  const htmlFile = join(distDir, relPath + ".html");
+  if (await fileExists(htmlFile)) return { type: "file", targetFile: htmlFile };
+  return { type: "missing", targetFile: null };
+}
+
+async function resolveDistTarget(href, distDir, basePath = "/", fileDir = "", sourceFile = null) {
+  const { path: decodedPath, rawPath, fragment, fragmentError } = parseHref(href);
+  if (!rawPath) return { type: "root", targetFile: sourceFile ?? join(distDir, "index.html"), fragment, fragmentError };
+  const pathCandidates = rawPath === decodedPath ? [rawPath] : [rawPath, decodedPath];
+  for (const path of pathCandidates) {
+    const detail = await resolveBuiltPath(path, distDir, basePath, fileDir);
+    if (detail.type !== "missing") return { ...detail, fragment, fragmentError };
+  }
+  return { type: "missing", targetFile: null, fragment, fragmentError };
+}
+
+export async function resolveLinkDetail(href, distDir, basePath = "/", fileDir = "") {
+  return (await resolveDistTarget(href, distDir, basePath, fileDir)).type;
+}
+
+export async function resolveLink(href, distDir, basePath = "/", fileDir = "") {
+  return (await resolveDistTarget(href, distDir, basePath, fileDir)).type !== "missing";
+}
+
+/**
+ * Scan budget: exactly ONE anchor pass per page, and at most ONE id extraction
+ * per HTML target some fragment actually references. Ids are deliberately not
+ * extracted eagerly — most pages are never the target of a fragment link, and
+ * scanning them costs a full regex pass for a set nothing reads.
+ */
+export async function checkHtmlLinksAndTrailing(
+  distDir,
+  rootDir,
+  basePath = "/",
+  excludePatterns = [],
+  checkTrailing = false,
+) {
+  const broken = [];
+  const anchors = [];
+  const trailingSlash = [];
+  const protocolRelative = [];
+  const idCache = new Map();
+  const cache = new Map();
+  const scanned = { links: 0, ids: 0 };
+  for (const file of await collectFiles(distDir, [".html"])) {
+    const content = await readFile(file, "utf-8");
+    const relFile = relative(rootDir, file);
+    // One anchor pass per page: internal links and the informational
+    // protocol-relative notices are disjoint buckets of the same match set.
+    const { links, protocolRelative: pageProtocolRelative } = classifyHtmlAnchorHrefs(content);
+    scanned.links += links.length;
+
+    // Filtered on the HREF, exactly like every other category below — an
+    // `excludePatterns` entry suppresses `//host/v/1.2/x` because the href
+    // matches, not because the page the href sits on is itself versioned.
+    // Without this the section had no off switch and consumers stopped
+    // reading it.
+    for (const { href, line } of pageProtocolRelative) {
+      if (excludePatterns.some((pattern) => pattern.test(href))) continue;
+      protocolRelative.push({ file: relFile, line, href });
+    }
+
+    for (const { href, line } of links) {
+      if (excludePatterns.some((pattern) => pattern.test(href))) continue;
+      const cacheKey = href.startsWith("/") ? href : `${file}:${href}`;
+      let detail = cache.get(cacheKey);
+      if (detail === undefined) {
+        detail = await resolveDistTarget(href, distDir, basePath, dirname(file), file);
+        cache.set(cacheKey, detail);
+      }
+      if (detail.type === "missing") broken.push({ file: relFile, line, href });
+      if (detail.fragment !== null) {
+        let reason = detail.fragmentError;
+        if (reason === null && detail.type !== "missing" && detail.targetFile !== null && extname(detail.targetFile) === ".html") {
+          let ids = idCache.get(detail.targetFile);
+          if (ids === undefined) {
+            // The page being walked is already in memory; any other target is
+            // re-read here rather than retained, so the walk never holds more
+            // than one page's HTML no matter how large dist/ is.
+            const targetHtml = detail.targetFile === file ? content : await readFile(detail.targetFile, "utf-8");
+            const targetIds = extractHtmlIds(targetHtml);
+            scanned.ids += targetIds.length;
+            ids = new Set(targetIds);
+            idCache.set(detail.targetFile, ids);
+          }
+          if (!ids.has(detail.fragment)) reason = "missing target id";
+        }
+        if (reason !== null) anchors.push({ file: relFile, line, href, fragment: detail.fragment, reason });
+      }
+      if (checkTrailing) {
+        const pathPart = href.split("#")[0].split("?")[0];
+        if (pathPart && pathPart !== "/" && pathPart !== "." && pathPart !== "./" && !pathPart.endsWith("/") && !extname(pathPart) && detail.type === "directoryIndex") {
+          trailingSlash.push({ file: relFile, line, href });
+        }
+      }
+    }
+  }
+  return { broken, anchors, trailingSlash, protocolRelative, scanned };
+}
+
+export async function checkMdxLinks(
+  contentDirs,
+  rootDir,
+  distDir = null,
+  basePath = "/",
+  locales = [],
+) {
+  assertLocaleList(locales);
+  const warnings = [];
+  for (const dir of contentDirs) {
+    if (!(await fileExists(dir))) continue;
+    for (const file of await collectFiles(dir, [".mdx", ".md"])) {
+      const content = await readFile(file, "utf-8");
+      for (const { href, line } of extractMdxAbsoluteLinks(content, locales)) {
+        if (distDir && await resolveLink(href, distDir, basePath)) continue;
+        warnings.push({ file: relative(rootDir, file), line, href });
+      }
+    }
+  }
+  return warnings;
+}
+
+// The authority segment is everything after "//" up to the first "/", "?",
+// or "#". A dotless, colonless authority (no TLD-shaped or host:port-shaped
+// piece) is flagged as a likely internal-path typo — see formatReport below.
+function protocolRelativeAuthority(href) {
+  const rest = href.slice(2);
+  const end = rest.search(/[/?#]/);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+function isLikelyInternalPathTypo(href) {
+  const authority = protocolRelativeAuthority(href);
+  return !authority.includes(".") && !authority.includes(":");
+}
+
+export function formatReport(brokenLinks, mdxWarnings, trailingSlashWarnings = [], anchorWarnings = [], protocolRelative = []) {
+  const lines = [];
+  const section = (title, entries, format) => {
+    if (entries.length === 0) return;
+    lines.push(title);
+    for (const entry of entries) lines.push(`  ${format(entry)}`);
+    lines.push("");
+  };
+  section("=== Broken Links in Built HTML ===", brokenLinks, (e) => `${e.file}:${e.line}  ${e.href}`);
+  section("=== Absolute Links Bypassing Base Path (MDX Source) ===", mdxWarnings, (e) => `${e.file}:${e.line}  ${e.href}`);
+  section("=== Links Missing Trailing Slash ===", trailingSlashWarnings, (e) => `${e.file}:${e.line}  ${e.href}`);
+  section("=== Invalid Anchors ===", anchorWarnings, (e) => `${e.file}:${e.line}  ${e.href}  (fragment: #${e.fragment}; ${e.reason})`);
+  // Informational only — excluded from `total` / the ✓/✗ line / the
+  // non-strict "Issues found" note below, deliberately (see #3934).
+  section("=== Protocol-Relative Links (informational) ===", protocolRelative, (e) =>
+    `${e.file}:${e.line}  ${e.href}${isLikelyInternalPathTypo(e.href) ? `  ← authority has no dot or colon; may be an internal-path typo (e.g. ${e.href} → ${e.href.slice(1)})` : ""}`,
+  );
+  const total = brokenLinks.length + mdxWarnings.length + trailingSlashWarnings.length + anchorWarnings.length;
+  if (total === 0) lines.push("✓ No broken links, invalid anchors, or absolute path issues found");
+  else {
+    const parts = [];
+    if (brokenLinks.length) parts.push(`${brokenLinks.length} broken link${brokenLinks.length === 1 ? "" : "s"}`);
+    if (mdxWarnings.length) parts.push(`${mdxWarnings.length} absolute path warning${mdxWarnings.length === 1 ? "" : "s"}`);
+    if (trailingSlashWarnings.length) parts.push(`${trailingSlashWarnings.length} trailing slash warning${trailingSlashWarnings.length === 1 ? "" : "s"}`);
+    if (anchorWarnings.length) parts.push(`${anchorWarnings.length} invalid anchor${anchorWarnings.length === 1 ? "" : "s"}`);
+    lines.push(`✗ Found ${parts.join(" and ")}`);
+  }
+  return lines.join("\n");
+}
+
+export async function readAllowlist(allowlistPath) {
+  if (!allowlistPath || !(await fileExists(allowlistPath))) return new Set();
+  return new Set((await readFile(allowlistPath, "utf-8")).split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")));
+}
+
+function entryKey(entry) {
+  return `${entry.file}:${entry.line}:${entry.href}`;
+}
+
+async function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(CLI_USAGE);
+    return;
+  }
+  const rootDir = resolve(process.cwd());
+  const configPath = join(rootDir, "zfb.config.ts");
+  const config = await parseZfbConfig(configPath);
+  const contentDirs = [resolve(rootDir, config.docsDir), ...config.localeDirs.map((dir) => resolve(rootDir, dir))];
+  const distDir = join(rootDir, "dist");
+  const hasDist = await isDirectory(distDir);
+  const excludePatterns = [/\/v\/[^/]+\//];
+  console.log(`Checking links (base: ${config.basePath}, trailingSlash: ${config.trailingSlash})...`);
+  console.log(`Source scan: ${contentDirs.map((dir) => relative(rootDir, dir) || ".").join(", ")}${hasDist ? "; dist/ pass enabled" : "; dist/ absent (source-only)"}\n`);
+
+  const [{ broken, anchors: htmlAnchors, trailingSlash, protocolRelative, scanned }, mdxWarnings, mdxAnchors] = await Promise.all([
+    hasDist ? checkHtmlLinksAndTrailing(distDir, rootDir, config.basePath, excludePatterns, config.trailingSlash) : Promise.resolve({ broken: [], anchors: [], trailingSlash: [], protocolRelative: [], scanned: { links: 0, ids: 0 } }),
+    checkMdxLinks(contentDirs, rootDir, hasDist ? distDir : null, config.basePath, config.localeKeys),
+    checkMdxAnchors(contentDirs, rootDir, config.basePath, config.localeKeys, excludePatterns),
+  ]);
+  const anchorWarnings = [...htmlAnchors, ...mdxAnchors];
+  const allowlistPath = options.allowlistPath ? (options.allowlistPath.startsWith("/") ? options.allowlistPath : join(rootDir, options.allowlistPath)) : null;
+  const allowlist = await readAllowlist(allowlistPath);
+  const filter = (entries) => entries.filter((entry) => !allowlist.has(entryKey(entry)));
+  const realBroken = filter(broken);
+  const realAbsolute = filter(mdxWarnings);
+  const realAnchors = filter(anchorWarnings);
+  const realTrailing = filter(trailingSlash);
+  // The one category filtered BEFORE printing. It has no strict gate, so the
+  // allowlist is a consumer's only way to quiet a known-good entry, and
+  // quieting has to reach the section and the count line alike or the section
+  // keeps nagging and stops being read.
+  const shownProtocolRelative = filter(protocolRelative);
+  console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings, shownProtocolRelative));
+  if (hasDist) console.log(`\nBuilt HTML scan: ${scanned.links} internal link${scanned.links === 1 ? "" : "s"} and ${scanned.ids} ID attribute${scanned.ids === 1 ? "" : "s"} inspected.`);
+  if (shownProtocolRelative.length > 0) console.log(`Protocol-relative links: ${shownProtocolRelative.length} found (informational only — see "Protocol-Relative Links" section above; not counted as issues).`);
+  // Protocol-relative suppressions are deliberately absent from this tally:
+  // the sentence is about strict-mode counts, and that category has none.
+  const skipped = broken.length - realBroken.length + mdxWarnings.length - realAbsolute.length + anchorWarnings.length - realAnchors.length + trailingSlash.length - realTrailing.length;
+  if (skipped > 0) console.log(`\nAllowlist: ${skipped} known exception${skipped === 1 ? "" : "s"} excluded from strict-mode counts (${allowlistPath}).`);
+  let failed = false;
+  if (options.strictBroken && realBroken.length) { console.log(`\n❌ STRICT FAIL: ${realBroken.length} broken link${realBroken.length === 1 ? "" : "s"} (after allowlist).`); failed = true; }
+  if (options.strictAbsolute && realAbsolute.length) { console.log(`\n❌ STRICT FAIL: ${realAbsolute.length} absolute MDX-source link${realAbsolute.length === 1 ? "" : "s"} (after allowlist).`); failed = true; }
+  if (options.strictAnchors && realAnchors.length) { console.log(`\n❌ STRICT FAIL: ${realAnchors.length} invalid anchor${realAnchors.length === 1 ? "" : "s"} (after allowlist).`); failed = true; }
+  if (options.strictTrailing && realTrailing.length) { console.log(`\n❌ STRICT FAIL: ${realTrailing.length} trailing-slash warning${realTrailing.length === 1 ? "" : "s"} (after allowlist).`); failed = true; }
+  if (failed) process.exitCode = 1;
+  else if ((broken.length || mdxWarnings.length || anchorWarnings.length || trailingSlash.length) && !options.strictBroken && !options.strictAbsolute && !options.strictAnchors && !options.strictTrailing) {
+    console.log("\nNote: Issues found but running in non-strict mode (exit 0).");
+    console.log("Use --strict-broken / --strict-absolute / --strict-anchors / --strict-trailing to fail on selected issue categories.");
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isMain) {
+  main().catch((error) => {
+    console.error(error instanceof CliArgumentError ? error.message : error);
+    process.exitCode = 1;
+  });
+}