@brandon_m_behring/book-scaffold-astro 4.28.0 → 4.29.0

package/scripts/build-labels.mjs

@@ -2,9 +2,9 @@
 /**
  * build-labels.mjs — emit src/data/labels.json for <XRef> resolution.
  *
- * Walks the consumer's `src/content/chapters/**\/*.mdx`, extracts each
- * labelable component invocation (Theorem, Figure, Section, … — see
- * `LABELABLE_TYPES` below), and assigns it an entry of the form
+ * Walks the consumer's `src/content/chapters/**\/*.mdx`, extracts every h2–h6
+ * Markdown heading plus each labelable component invocation (Theorem, Figure,
+ * Section, … — see `LABELABLE_TYPES` below), and assigns it an entry of the form
  *   { href, display: "Theorem 4.2", number: "4.2" }
  * matching the LaTeX `\cref` convention. The map is consumed by XRef.astro
  * (display + href) AND Theorem.astro (#126: `number`, so a heading auto-
@@ -25,11 +25,15 @@
  *   - tools profile: `chapter` field (number).
  *   - academic profile: `week` field (number).
  *
- * Slug used for the href: the chapter's frontmatter `slug:` if set,
- * else filename minus `.mdx`. The href shape mirrors the consumer's pages
- * router: `/chapters/<slug>#<id>`. Academic books using `[...slug].astro`
- * get the same shape since Astro slugifies filenames identically when no
- * frontmatter override is present.
+ * Chapter IDs use frontmatter `slug:` when set, else the chapter-relative path
+ * minus `.md`/`.mdx` (so nested content IDs preserve their directory). Hrefs
+ * are resolved through the evaluated defineBookConfig `chapterRoute` and
+ * `bookField`; the default remains `chapters/<id>#<label>`.
+ *
+ * Heading anchors come from Astro's own Markdown processor, including its
+ * smartypants text normalization and GitHubSlugger duplicate suffixes. h1 is
+ * intentionally excluded because it is the chapter title, not an in-chapter
+ * BookLink target.
  *
  * Optional override:
  *   <Theorem id="…" label="Custom display" />
@@ -45,7 +49,9 @@
  * Designed to run in <2 s on a medium book.
  */
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
-import { resolve, relative, join, basename, dirname } from 'node:path';
+import { resolve, relative, join, dirname, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createMarkdownProcessor } from '@astrojs/markdown-remark';
 import { readChaptersBase } from './walk-mdx.mjs';
 import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 // #126: reuse the ONE kind vocabulary (theorem-label.ts → its own lean tsup
@@ -54,13 +60,16 @@ import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 // throw as the render path, #121) one build step earlier. Requires `dist/`
 // (run `npm run build` first; the published tarball ships dist + scripts).
 import { theoremLabel } from '../dist/lib/theorem-label.mjs';
+// #147: reuse the same route-token resolver as Sidebar/ChapterNav rather than
+// maintaining a second, hardcoded `chapters/<slug>` interpretation here.
+import { chapterHref } from '../dist/lib/nav-href.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-labels
 
-Emit src/data/labels.json for <XRef> resolution. Walks chapter MDX files,
-extracts labelable components (Theorem, Figure, ...), assigns display strings
-like "Theorem 4.2" matching LaTeX \\cref.
+Emit src/data/labels.json for <XRef> and <BookLink> resolution. Walks chapter
+Markdown/MDX files, indexes h2–h6 anchors, and extracts labelable components
+(Theorem, Figure, ...) with display strings like "Theorem 4.2".
 
 Env:
   BOOK_CHAPTERS_DIR   Override chapters dir (default: src/content/chapters).
@@ -69,8 +78,8 @@ Env:
 Options:
   --help, -h          Print this message and exit (non-mutating).
 
-Numbering is read from defineBookConfig / defineStyle numberStyle. It defaults
-to shared when no scaffold integration can be resolved.
+Numbering and chapter hrefs are read from evaluated defineBookConfig metadata.
+Defaults are shared numbering and /chapters/:id/ when no integration resolves.
 `;
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -111,12 +120,14 @@ const TYPE_DISPLAY = {
 
 // ===== Frontmatter parsing =====
 
-function parseFrontmatter(source) {
+function splitFrontmatter(source) {
   // Standard MDX/YAML frontmatter: `---\n…\n---`.
-  const m = source.match(/^---\n([\s\S]*?)\n---/);
-  if (!m) return {};
+  // Remove it before Markdown processing: YAML comments beginning with `#`
+  // must not become phantom headings.
+  const m = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) return { frontmatter: {}, body: source };
   const fm = {};
-  for (const line of m[1].split('\n')) {
+  for (const line of m[1].split(/\r?\n/)) {
     const kv = line.match(/^(\w+)\s*:\s*(.+?)\s*$/);
     if (!kv) continue;
     const [, key, raw] = kv;
@@ -125,7 +136,7 @@ function parseFrontmatter(source) {
     if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
     fm[key] = val;
   }
-  return fm;
+  return { frontmatter: fm, body: source.slice(m[0].length) };
 }
 
 function chapterNumberOf(frontmatter) {
@@ -187,9 +198,13 @@ async function walkChapters(dir) {
 
 async function main() {
   const cwd = process.cwd();
-  const { numberStyle } = await loadResolvedBookConfig(cwd);
+  const { numberStyle, chapterRoute, bookField } = await loadResolvedBookConfig(cwd);
   const chaptersDir = resolve(cwd, CHAPTERS_DIR);
   const files = await walkChapters(chaptersDir);
+  // Syntax highlighting cannot affect heading metadata and is expensive to
+  // initialize. Everything that does affect Astro heading text/IDs (GFM,
+  // smartypants, rehypeHeadingIds/GitHubSlugger) retains Astro's defaults.
+  const headingProcessor = await createMarkdownProcessor({ syntaxHighlight: false });
 
   const labels = {};
   const tagRegex = buildTagRegex();
@@ -198,16 +213,63 @@ async function main() {
 
   for (const file of files) {
     const source = await readFile(file, 'utf8');
-    const fm = parseFrontmatter(source);
+    const { frontmatter: fm, body } = splitFrontmatter(source);
     const chapterNum = chapterNumberOf(fm);
-    const slug = (typeof fm.slug === 'string' && fm.slug.length > 0)
+    const contentId = relative(chaptersDir, file)
+      .split(sep)
+      .join('/')
+      .replace(/\.mdx?$/, '');
+    const entryId = (typeof fm.slug === 'string' && fm.slug.length > 0)
       ? fm.slug
-      : basename(file).replace(/\.mdx?$/, '');
+      : contentId;
+    const chapterPath = chapterHref(
+      { id: entryId, data: fm },
+      chapterRoute,
+      '/',
+      bookField,
+    ).replace(/^\/+|\/+$/g, '');
+
+    const addLabel = (id, value) => {
+      if (labels[id]) {
+        // Duplicate id — surface but don't fail; consumer's validator catches
+        // collisions with full diagnostic context. Component IDs retain their
+        // historical precedence over an identically named heading anchor.
+        process.stderr.write(
+          `build-labels: WARN duplicate id "${id}" (first in ` +
+            `${labels[id].href.split('#')[0]}, now in ${entryId})\n`,
+        );
+      }
+      labels[id] = value;
+    };
 
     // Per-chapter counters reset for each file.
     const counters = {};
     let foundInChapter = 0;
 
+    // #147: BookLink fragments normally target prose sections rather than
+    // labelable components. Astro owns both text extraction and GitHub-style
+    // slug collision behavior, so consume its heading metadata directly.
+    const rendered = await headingProcessor.render(body, {
+      fileURL: pathToFileURL(file),
+      frontmatter: fm,
+    });
+    for (const heading of rendered.metadata.headings) {
+      if (heading.depth < 2 || heading.depth > 6) continue;
+      foundInChapter += 1;
+      totalIds += 1;
+      const href = `${chapterPath}#${heading.slug}`;
+      // Heading fragments are only document-local: many chapters legitimately
+      // contain `#summary`. A path-qualified, opaque key preserves every one
+      // without colliding with component IDs or another chapter. BookLink
+      // validation resolves the exact href VALUE; consumers must not derive
+      // heading semantics from this internal key.
+      addLabel(`heading:${href}`, {
+        href,
+        display: heading.text,
+        number: null,
+      });
+    }
+
     for (const match of source.matchAll(tagRegex)) {
       const [, componentName, attrs] = match;
       const id = extractAttr(attrs, 'id');
@@ -267,21 +329,13 @@ async function main() {
           : String(counters[counterKey]);
       const display = labelOverride ?? `${word} ${number}`;
 
-      if (labels[id]) {
-        // Duplicate id — surface but don't fail; consumer's validator
-        // catches collisions with full diagnostic context.
-        process.stderr.write(
-          `build-labels: WARN duplicate id "${id}" (first in ` +
-            `${labels[id].href.split('#')[0]}, now in ${slug})\n`,
-        );
-      }
-      labels[id] = {
+      addLabel(id, {
         // #142: base-less ref — XRef.astro prefixes BASE_URL at render so one
         // labels.json serves any deploy base (root or path-proxied series).
-        href: `chapters/${slug}#${id}`,
+        href: `${chapterPath}#${id}`,
         display,
         number,
-      };
+      });
     }
 
     if (foundInChapter > 0) chaptersWithIds += 1;

package/scripts/resolve-book-config.mjs

@@ -5,6 +5,9 @@ import { loadConfigFromFile } from 'vite';
 export const DEFAULT_TOOLING_CONFIG = Object.freeze({
   preset: null,
   numberStyle: 'shared',
+  siblingBooks: Object.freeze({}),
+  chapterRoute: '/chapters/:id/',
+  bookField: 'book',
   integrationFound: false,
 });
 
@@ -42,6 +45,64 @@ function assertPreset(value, configPath) {
   }
 }
 
+function resolveNonEmptyString(value, fallback, field, configPath) {
+  if (value == null) return fallback;
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid ${field} ` +
+        `${JSON.stringify(value)}; expected a non-empty string.`,
+    );
+  }
+  return value;
+}
+
+function resolveSiblingBooks(value, configPath) {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid siblingBooks ` +
+        `${JSON.stringify(value)}; expected an object registry.`,
+    );
+  }
+
+  const resolved = [];
+  for (const [book, entry] of Object.entries(value)) {
+    if (typeof entry === 'string') {
+      if (entry.length === 0) {
+        throw new Error(
+          `book-scaffold tooling: ${configPath} resolved invalid siblingBooks.${book}; ` +
+            'URL strings must not be empty.',
+        );
+      }
+      resolved.push([book, entry]);
+      continue;
+    }
+
+    if (
+      entry === null ||
+      typeof entry !== 'object' ||
+      Array.isArray(entry) ||
+      typeof entry.url !== 'string' ||
+      entry.url.length === 0 ||
+      (entry.labels !== undefined &&
+        (typeof entry.labels !== 'string' || entry.labels.length === 0))
+    ) {
+      throw new Error(
+        `book-scaffold tooling: ${configPath} resolved invalid siblingBooks.${book}; ` +
+          'expected a URL string or { url: string, labels?: string }.',
+      );
+    }
+    resolved.push([
+      book,
+      {
+        url: entry.url,
+        ...(entry.labels === undefined ? {} : { labels: entry.labels }),
+      },
+    ]);
+  }
+  return Object.fromEntries(resolved);
+}
+
 /**
  * Evaluate the consumer's actual Astro config and read the scaffold
  * integration's internal resolved metadata. Absence of a config/integration is
@@ -91,6 +152,19 @@ export async function loadResolvedBookConfig(projectRoot = process.cwd()) {
   return {
     preset: metadata.preset ?? null,
     numberStyle,
+    siblingBooks: resolveSiblingBooks(metadata.siblingBooks, configPath),
+    chapterRoute: resolveNonEmptyString(
+      metadata.chapterRoute,
+      DEFAULT_TOOLING_CONFIG.chapterRoute,
+      'chapterRoute',
+      configPath,
+    ),
+    bookField: resolveNonEmptyString(
+      metadata.bookField,
+      DEFAULT_TOOLING_CONFIG.bookField,
+      'bookField',
+      configPath,
+    ),
     integrationFound: true,
   };
 }

package/scripts/validate.mjs

@@ -16,8 +16,9 @@
  *   6. <Theorem> — has a resolvable kind= (or legacy type=); else it would
  *      render an empty label and throw at build (#121). An id'd theorem must
  *      resolve in labels.json, and a literal n= must agree with that index.
- *   7. <BookLink book="…" to="…"> (#96) — both props present, and book= is a
- *      key in the consumer's siblingBooks registry (best-effort).
+ *   7. <BookLink book="…" to="…"> (#96/#147) — both props present, book= is
+ *      registered, and literal fragment targets resolve in the sibling's
+ *      declared vendored labels index. Dynamic and URL-only entries warn/skip.
  *   8. Questions collection (#112) — each question's frontmatter `domain` is a
  *      member of the consumer's examDomains registry (best-effort), and question
  *      `id`s are unique (the cross-ref key for the appendix / flashcards).
@@ -41,6 +42,9 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMdx from 'remark-mdx';
 import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
 import { readEnvFile } from './read-env.mjs';
 import { loadResolvedBookConfig } from './resolve-book-config.mjs';
@@ -256,6 +260,32 @@ async function loadJson(path) {
 const refs = await loadJson(join(DATA_DIR, 'references.json'));
 const labels = await loadJson(join(DATA_DIR, 'labels.json'));
 
+// #147: eagerly load every labels index explicitly declared by the evaluated
+// siblingBooks registry. Unlike this book's generated labels.json, sibling
+// indexes are vendored inputs: never self-heal or silently replace them. A
+// missing, unreadable, malformed, or non-object index is a configuration error
+// even when no current chapter happens to reference that sibling.
+const siblingLabelIndexes = new Map();
+for (const [book, entry] of Object.entries(TOOLING_CONFIG.siblingBooks)) {
+  if (typeof entry === 'string' || entry.labels === undefined) continue;
+  const indexPath = resolve(ROOT, entry.labels);
+  try {
+    const index = JSON.parse(await readFile(indexPath, 'utf8'));
+    if (index === null || typeof index !== 'object' || Array.isArray(index)) {
+      throw new Error('top-level JSON value must be an object');
+    }
+    siblingLabelIndexes.set(book, { index, configuredPath: entry.labels });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    fail(
+      'astro.config',
+      1,
+      `siblingBooks.${book}.labels (${JSON.stringify(entry.labels)}) is missing, unreadable, or invalid: ${detail}. ` +
+        'Vendor a readable sibling labels.json at that path or remove labels to opt out with a warning.',
+    );
+  }
+}
+
 // ===== Collect chapter files =====
 // v3.7.1 (closes #52): walkMdx (in ./walk-mdx.mjs) is a recursive readdir
 // walker that replaces the previous `glob` import from `node:fs/promises`.
@@ -282,9 +312,10 @@ const RE_MD_LINK = /\[(?:[^\]]*)\]\((\/[^)\s#]+)(?:#[^)]*)?\)/g;
 // #121: a <Theorem> opening tag — capture its attributes to assert a
 // resolvable kind= (or legacy type=) is present.
 const RE_THEOREM = /<Theorem\b([^>]*)>/g;
-// #96: a <BookLink> opening tag — assert book= + to= present, and (best-effort)
-// that book= is a registered sibling.
-const RE_BOOKLINK = /<BookLink\b([^>]*)>/g;
+// #96/#147: BookLink attributes must be read structurally. An opening-tag
+// regex stops at `>` inside a quoted value or expression and can mistake text
+// inside another prop for a real book=/to= assignment.
+const mdxParser = unified().use(remarkParse).use(remarkMdx);
 
 async function fileExists(p) {
   try {
@@ -322,29 +353,107 @@ function literalTheoremNumber(attrs) {
   return null;
 }
 
-// #96: best-effort siblingBooks registry keys from astro.config.mjs, so the
-// <BookLink> check can flag an unknown book= earlier than the component's
-// build-time throw. null = couldn't determine → membership not checked (the
-// component still fails loud at build).
-let siblingBookKeys = null;
-{
-  const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
-  if (existsSync(astroConfigPath)) {
-    const block = readFileSync(astroConfigPath, 'utf8').match(/siblingBooks\s*:\s*\{([^}]*)\}/);
-    if (block) {
-      // Anchor each key to an entry boundary ({ , or start) so the `https:` in
-      // a URL value isn't mistaken for a key.
-      siblingBookKeys = new Set(
-        [...block[1].matchAll(/(?:^|[{,])\s*['"]?([\w-]+)['"]?\s*:/g)].map((x) => x[1]),
-      );
+/** Yield MDX JSX elements with an exact component name, excluding examples in
+ * fenced/inline code and strings in expressions by construction. */
+function* mdxElements(node, name) {
+  if (
+    (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+    node.name === name
+  ) {
+    yield node;
+  }
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) yield* mdxElements(child, name);
+}
+
+function expressionString(value) {
+  const program = value?.data?.estree;
+  if (program?.body?.length !== 1 || program.body[0].type !== 'ExpressionStatement') {
+    return null;
+  }
+  const expression = program.body[0].expression;
+  if (expression.type === 'Literal' && typeof expression.value === 'string') {
+    return expression.value;
+  }
+  if (expression.type === 'TemplateLiteral' && expression.expressions.length === 0) {
+    return expression.quasis[0]?.value?.cooked ?? expression.quasis[0]?.value?.raw ?? '';
+  }
+  return null;
+}
+
+/**
+ * Evaluate one JSX prop in source order. Later explicit attributes override an
+ * earlier spread; a later spread makes the value dynamic, exactly as JSX does.
+ * Literal ESTree values are already decoded, so entities and JS escapes cannot
+ * disguise the href that the component receives at runtime.
+ */
+function mdxStringProp(element, name) {
+  let result = { present: false, literal: false, value: null, source: 'absent' };
+  for (const attribute of element.attributes) {
+    if (attribute.type === 'mdxJsxExpressionAttribute') {
+      result = { present: true, literal: false, value: null, source: 'spread' };
+      continue;
+    }
+    if (attribute.type !== 'mdxJsxAttribute' || attribute.name !== name) continue;
+    if (typeof attribute.value === 'string') {
+      result = { present: true, literal: true, value: attribute.value, source: 'attribute' };
+      continue;
+    }
+    const value = expressionString(attribute.value);
+    result = value === null
+      ? { present: true, literal: false, value: null, source: 'expression' }
+      : { present: true, literal: true, value, source: 'attribute' };
+  }
+  return result;
+}
+
+/**
+ * Canonical comparison shape for a sibling labels href. The generated index
+ * intentionally omits the deployment base, so only normalize route seams:
+ * leading slashes and the optional trailing slash immediately before `#`.
+ */
+function normalizeSiblingTarget(value) {
+  const hash = value.indexOf('#');
+  if (hash < 0 || hash === value.length - 1) return null;
+  const fragment = value.slice(hash + 1);
+  const path = value.slice(0, hash).trim().replace(/^\/+/, '').replace(/\/+$/, '');
+  return { fragment, href: `${path}#${fragment}` };
+}
+
+/**
+ * Heading keys in labels.json are deliberately opaque and path-qualified so
+ * `#summary` can exist in every chapter. Resolve sibling targets from href
+ * values, while remaining compatible with historical component-id keys.
+ */
+function siblingTargetCandidates(index, fragment) {
+  const candidates = [];
+  for (const [key, entry] of Object.entries(index)) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.href !== 'string') continue;
+    const normalized = normalizeSiblingTarget(entry.href);
+    if (normalized?.fragment === fragment) {
+      candidates.push({ key, href: entry.href, normalized });
     }
   }
+  return candidates;
 }
 
 // ===== Run all checks on each chapter =====
 for (const rel of chapterFiles) {
   const abs = join(CHAPTERS_DIR, rel);
   const content = await readFile(abs, 'utf8');
+  let bookLinks = [];
+  if (content.includes('<BookLink')) {
+    try {
+      bookLinks = [...mdxElements(mdxParser.parse(content), 'BookLink')];
+    } catch (error) {
+      const line = error?.position?.start?.line ?? error?.line ?? 1;
+      fail(
+        rel,
+        line,
+        `Cannot structurally validate <BookLink>: ${error?.reason ?? error?.message ?? error}`,
+      );
+    }
+  }
 
   // 1. Cite keys (academic profile only — tools profile uses YAML manifest)
   if (PROFILE === 'academic') {
@@ -443,21 +552,122 @@ for (const rel of chapterFiles) {
     }
   }
 
-  // 7. BookLink (#96): structural (book= + to=) + best-effort registry membership.
-  for (const m of content.matchAll(RE_BOOKLINK)) {
-    const attrs = m[1];
-    const bookMatch = attrs.match(/\bbook=["']([^"']+)["']/);
-    if (!bookMatch || !/\bto=["']/.test(attrs)) {
-      fail(rel, lineOf(content, m.index), `<BookLink> requires both book="…" and to="…".`);
+  // 7. BookLink (#96/#147): structural props + evaluated registry membership,
+  //    then literal path/fragment validation against a declared vendored index.
+  //    Dynamic values and URL-only compatibility entries are explicit warnings
+  //    rather than guessed validations.
+  for (const element of bookLinks) {
+    const line = element.position?.start?.line ?? 1;
+    const bookAttr = mdxStringProp(element, 'book');
+    const toAttr = mdxStringProp(element, 'to');
+
+    if (bookAttr.source === 'spread' || toAttr.source === 'spread') {
+      warn(
+        rel,
+        line,
+        '<BookLink> validation skipped: a dynamic prop spread may supply or override book=/to=, so the target cannot be proven statically.',
+      );
       continue;
     }
-    if (siblingBookKeys && !siblingBookKeys.has(bookMatch[1])) {
+    if (!bookAttr.present || !toAttr.present) {
+      fail(rel, line, `<BookLink> requires both book="…" and to="…".`);
+      continue;
+    }
+
+    if (!bookAttr.literal) {
+      warn(
+        rel,
+        line,
+        '<BookLink> target validation skipped: dynamic book= expression cannot be evaluated statically.',
+      );
+      continue;
+    }
+
+    const book = bookAttr.value;
+    const registered = Object.prototype.hasOwnProperty.call(TOOLING_CONFIG.siblingBooks, book);
+    if (!registered) {
       fail(
         rel,
-        lineOf(content, m.index),
-        `<BookLink book="${bookMatch[1]}"> — not in defineBookConfig siblingBooks (${[...siblingBookKeys].join(', ') || 'none'}). Register it or fix the key.`,
+        line,
+        `<BookLink book="${book}"> — not in evaluated defineBookConfig siblingBooks (${Object.keys(TOOLING_CONFIG.siblingBooks).join(', ') || 'none'}). Register it or fix the key.`,
+      );
+      continue;
+    }
+    const siblingEntry = TOOLING_CONFIG.siblingBooks[book];
+
+    if (!toAttr.literal) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}"> target validation skipped: dynamic to= expression cannot be evaluated statically.`,
+      );
+      continue;
+    }
+
+    const target = normalizeSiblingTarget(toAttr.value);
+    if (!target) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> has no static #fragment; sibling labels validation skipped.`,
       );
+      continue;
     }
+
+    if (typeof siblingEntry === 'string' || siblingEntry.labels === undefined) {
+      warn(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> target validation skipped: ` +
+          'the siblingBooks entry is URL-only. Use { url, labels } to enable vendored-label validation.',
+      );
+      continue;
+    }
+
+    const loaded = siblingLabelIndexes.get(book);
+    if (!loaded) continue; // A config-level error was already recorded above.
+
+    const candidates = siblingTargetCandidates(loaded.index, target.fragment);
+    if (candidates.some((candidate) => candidate.normalized.href === target.href)) {
+      continue;
+    }
+
+    if (candidates.length === 0) {
+      // Preserve the actionable diagnostic for a malformed historical entry
+      // whose key is the literal fragment. Opaque heading keys are found by
+      // valid href values and never need to be decoded here.
+      const legacyEntry = loaded.index[target.fragment];
+      if (
+        Object.prototype.hasOwnProperty.call(loaded.index, target.fragment) &&
+        (legacyEntry === null ||
+          typeof legacyEntry !== 'object' ||
+          typeof legacyEntry.href !== 'string')
+      ) {
+        fail(
+          rel,
+          line,
+          `<BookLink book="${book}" to="${toAttr.value}"> — ${loaded.configuredPath} entry ` +
+            `"${target.fragment}" has no string href; re-vendor a valid sibling labels.json.`,
+        );
+        continue;
+      }
+      fail(
+        rel,
+        line,
+        `<BookLink book="${book}" to="${toAttr.value}"> — fragment "${target.fragment}" is not in ` +
+          `${loaded.configuredPath}. Vendor the current sibling labels.json, or fix the target id.`,
+      );
+      continue;
+    }
+
+    const indexedHrefs = candidates.map((candidate) => `"${candidate.href}"`).join(', ');
+    fail(
+      rel,
+      line,
+      `<BookLink book="${book}" to="${toAttr.value}"> — path/fragment does not match ` +
+        `${loaded.configuredPath}, which indexes "${target.fragment}" at ${indexedHrefs}. ` +
+        'Fix to= or refresh the vendored index.',
+    );
   }
 
   // <Rationale appendix> in CHAPTER bodies (v4.21.0, #114): same missing-for=