@brandon_m_behring/book-scaffold-astro 4.28.0 → 4.30.0

package/scripts/validate.mjs

@@ -16,14 +16,17 @@
  *   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).
  *   9. Learning-objective anchors (#130) — when a chapter declares frontmatter
  *      `los:` entries with `anchor:` slugs, the declared set and the prose's
  *      MDX anchor-comment marker set must agree in both directions.
+ *  10. Authored root-absolute href/src targets (#190) — under a non-root Astro
+ *      base, literal Markdown, HTML, and JSX targets must stay inside that base.
  *
  * Run from the consumer's project root. Closes #8 (was resolving paths
  * from the package's own directory inside node_modules — false negatives
@@ -34,22 +37,33 @@
  *   book-scaffold validate --preset academic
  *   BOOK_REPO_ROOT=/abs/path npx book-scaffold validate
  *
- * Exit code = total failure count (0 = pass, >=1 = errors).
+ * Exit code = total failure count capped at 255 (0 = pass, >=1 = errors).
  */
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { resolve, dirname, extname, 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 remarkMath from 'remark-math';
+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';
+import {
+  findAuthoredTargets,
+  normalizeAstroBase,
+  rootTargetEscapesBase,
+  rootTargetPathname,
+  suggestBaseContainedTarget,
+} from './authored-links.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold validate [--preset <name>]
 
 Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
-internal markdown links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
+internal authored links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
 
 Options:
   --preset <name>    academic | tools | minimal | course-notes | research-portfolio
@@ -61,7 +75,7 @@ Env:
   BOOK_PROFILE       Backward-compat alias for BOOK_PRESET.
   BOOK_REPO_ROOT     Absolute path to a sibling code repo for CodeRef checks.
 
-Exit code = total failure count.
+Exit code = total failure count, capped at 255 so failures never wrap to success.
 `;
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -139,6 +153,7 @@ if (!PRESET_CANDIDATE) {
 }
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;
+const MATH_ENABLED = PROFILE === 'academic' || PROFILE === 'research-portfolio';
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
 
 // v4.6.0 (issue #76 Layer 3b): chapter-route shadow warning. Detect a
@@ -256,6 +271,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`.
@@ -273,18 +314,19 @@ const validTopLevelRoutes = new Set([
   '/', '/chapters/', '/references/', '/search/', '/print/', '/convergence/',
 ]);
 
-// ===== Pattern helpers (regex-based; cheap, good enough for MDX) =====
+// ===== Pattern helpers for component-specific checks =====
 const RE_CITE = /<Cite[^>]+key=["']([^"']+)["']/g;
 const RE_XREF = /<XRef[^>]+id=["']([^"']+)["']/g;
 const RE_FIGURE = /<Figure[^>]+src=["']([^"']+)["']/g;
 const RE_CODEREF = /<CodeRef[^>]+path=["']([^"']+)["'](?:[^>]*line=\{(\d+)\})?(?:[^>]*lineEnd=\{(\d+)\})?/g;
-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);
+if (MATH_ENABLED) mdxParser.use(remarkMath);
 
 async function fileExists(p) {
   try {
@@ -299,6 +341,62 @@ function lineOf(content, idx) {
   return content.slice(0, idx).split('\n').length;
 }
 
+const ASTRO_BASE = normalizeAstroBase(TOOLING_CONFIG.base);
+
+function authoredFormat(file) {
+  return extname(file).toLowerCase() === '.md' ? 'md' : 'mdx';
+}
+
+function collectAuthoredTargets(file, content) {
+  try {
+    return findAuthoredTargets(content, {
+      format: authoredFormat(file),
+      math: MATH_ENABLED,
+    });
+  } catch (error) {
+    const line = error?.line ?? error?.place?.start?.line ?? error?.position?.start?.line ?? 1;
+    const detail = String(error?.reason ?? error?.message ?? error).split('\n')[0];
+    fail(file, line, `Could not parse authored links as ${authoredFormat(file).toUpperCase()}: ${detail}`);
+    return [];
+  }
+}
+
+function validateAuthoredTargets(file, content, targets) {
+  for (const violation of targets) {
+    if (!rootTargetEscapesBase(violation.target, ASTRO_BASE)) continue;
+    const suggested = suggestBaseContainedTarget(violation.target, ASTRO_BASE);
+    fail(
+      file,
+      lineOf(content, violation.index),
+      `Authored ${violation.kind} ${JSON.stringify(violation.target)} escapes configured Astro base ` +
+        `${JSON.stringify(ASTRO_BASE)}. Use ${JSON.stringify(suggested)}, ` +
+        'import.meta.env.BASE_URL in JSX, or a base-aware component. ' +
+        'Validation does not rewrite authored URLs (#190).',
+    );
+  }
+}
+
+function validateInternalMarkdownLinks(file, content, targets) {
+  for (const authored of targets) {
+    if (authored.kind !== 'Markdown link destination') continue;
+    const pathname = rootTargetPathname(authored.target);
+    if (pathname === null) continue;
+    const baseRelativeTarget =
+      ASTRO_BASE !== '/' && (pathname === ASTRO_BASE || pathname.startsWith(`${ASTRO_BASE}/`))
+        ? pathname.slice(ASTRO_BASE.length) || '/'
+        : pathname;
+    const target = baseRelativeTarget.replace(/\/$/, '') || '/';
+    if (validTopLevelRoutes.has(`${target}/`) || validTopLevelRoutes.has(target)) continue;
+    const chMatch = target.match(/^\/chapters\/(.+)$/);
+    if (chMatch && validSlugs.has(chMatch[1])) continue;
+    warn(
+      file,
+      lineOf(content, authored.index),
+      `Internal link ${JSON.stringify(authored.target)} — target may not resolve (check spelling or route)`,
+    );
+  }
+}
+
 /**
  * Return a statically knowable n= value. Quoted strings and braced
  * string/numeric literals are safe to compare; identifiers, calls,
@@ -322,29 +420,114 @@ 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');
+  const authoredTargets = collectAuthoredTargets(rel, content);
+
+  // 10. Root-absolute authored targets under a non-root Astro base (#190).
+  //     Structural parsing covers Markdown link/image destinations, HTML
+  //     href/src, and decoded static JSX strings while excluding code examples.
+  validateAuthoredTargets(rel, content, authoredTargets);
+
+  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') {
@@ -368,14 +551,9 @@ for (const rel of chapterFiles) {
     }
   }
 
-  // 4. Internal markdown links resolve
-  for (const m of content.matchAll(RE_MD_LINK)) {
-    const target = m[1].replace(/\/$/, '');
-    if (validTopLevelRoutes.has(target + '/') || validTopLevelRoutes.has(target)) continue;
-    const chMatch = target.match(/^\/chapters\/(.+)$/);
-    if (chMatch && validSlugs.has(chMatch[1])) continue;
-    warn(rel, lineOf(content, m.index), `Internal link "${m[1]}" — target may not resolve (check spelling or route)`);
-  }
+  // 4. Internal Markdown links resolve. Reuse the structural authored-target
+  //    traversal so code examples and comments cannot create false warnings.
+  validateInternalMarkdownLinks(rel, content, authoredTargets);
 
   // 5. CodeRef path + line bounds (only when BOOK_REPO_ROOT set)
   if (REPO_ROOT) {
@@ -443,21 +621,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=
@@ -563,6 +842,11 @@ let questionsChecked = 0;
       const front = fm ? fm[1] : '';
       const qrel = `questions/${rel}`;
 
+      // Questions do not run the legacy link-resolution advisory, so keep the
+      // #190 root-base contract fully inert by parsing only for a non-root base.
+      const authoredTargets = ASTRO_BASE === '/' ? [] : collectAuthoredTargets(qrel, content);
+      validateAuthoredTargets(qrel, content, authoredTargets);
+
       const idMatch = front.match(/^id\s*:\s*["']?([^"'\n]+?)["']?\s*$/m);
       if (idMatch) {
         const id = idMatch[1].trim();
@@ -638,4 +922,4 @@ console.error(
     `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}):`,
 );
 errors.forEach((e) => console.error(format(e)));
-process.exit(errors.length);
+process.exit(Math.min(errors.length, 255));

package/scripts/walk-mdx.mjs

@@ -16,6 +16,111 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 
+/**
+ * Mask JS/TS comments and string/template contents with spaces while
+ * preserving offsets and newlines. Collection detection runs against this
+ * mask so prose such as "default chapters" and code examples in comments
+ * cannot bind to a later, unrelated collection's `base:` property.
+ */
+function codeMask(source) {
+  // split('') preserves UTF-16 code-unit offsets used by RegExp#index even
+  // when a preceding comment contains an emoji/non-BMP character.
+  const out = source.split('');
+  let state = 'code';
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i];
+    const next = source[i + 1];
+
+    if (state === 'line-comment') {
+      if (char === '\n') state = 'code';
+      else out[i] = ' ';
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        out[i] = ' ';
+        out[i + 1] = ' ';
+        i += 1;
+        state = 'code';
+      } else if (char !== '\n') {
+        out[i] = ' ';
+      }
+      continue;
+    }
+    if (state === 'single' || state === 'double' || state === 'template') {
+      const closing = state === 'single' ? "'" : state === 'double' ? '"' : '`';
+      if (char === '\\') {
+        out[i] = ' ';
+        if (i + 1 < source.length) {
+          if (source[i + 1] !== '\n') out[i + 1] = ' ';
+          i += 1;
+        }
+      } else {
+        if (char === closing) state = 'code';
+        if (char !== '\n') out[i] = ' ';
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      out[i] = ' ';
+      out[i + 1] = ' ';
+      i += 1;
+      state = 'line-comment';
+    } else if (char === '/' && next === '*') {
+      out[i] = ' ';
+      out[i + 1] = ' ';
+      i += 1;
+      state = 'block-comment';
+    } else if (char === "'") {
+      out[i] = ' ';
+      state = 'single';
+    } else if (char === '"') {
+      out[i] = ' ';
+      state = 'double';
+    } else if (char === '`') {
+      out[i] = ' ';
+      state = 'template';
+    }
+  }
+  return out.join('');
+}
+
+/** Find an actual `chapters = defineCollection(...)` call and return its body
+ * plus an offset-preserving code mask. Supports declaration and object-property
+ * forms without relying on a distance from any arbitrary `chapters` word. */
+function findChaptersCollectionCall(source) {
+  const mask = codeMask(source);
+  const starts = [
+    /\b(?:const|let|var)\s+chapters\s*=\s*defineCollection\s*\(/g,
+    /(?:^|[,{])\s*chapters\s*:\s*defineCollection\s*\(/gm,
+  ];
+  const matches = [];
+  for (const pattern of starts) {
+    for (const match of mask.matchAll(pattern)) {
+      matches.push({ index: match.index, open: match.index + match[0].lastIndexOf('(') });
+    }
+  }
+  matches.sort((a, b) => a.index - b.index);
+
+  for (const match of matches) {
+    let depth = 0;
+    for (let i = match.open; i < mask.length; i += 1) {
+      if (mask[i] === '(') depth += 1;
+      else if (mask[i] === ')') {
+        depth -= 1;
+        if (depth === 0) {
+          return {
+            body: source.slice(match.open + 1, i),
+            mask: mask.slice(match.open + 1, i),
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+
 export async function* walkMdx(dir, baseDir = dir) {
   let entries;
   try {
@@ -152,19 +257,28 @@ export async function readChaptersBase(projectRoot) {
     } catch {
       return DEFAULT_BASE;
     }
-    // Look for a `chapters` collection's `loader.base` string. Permissive
-    // form: match the `chapters` identifier, then within the next 500
-    // chars find `base: 'string'` or `base: "string"`. NOT template
-    // literals (which use backticks and may contain ${} interpolation —
-    // those fall back to the default since the value is dynamic).
+    // Look for an actual `chapters` collection's `loader.base` string. The
+    // older "chapters word, then any base within 500 chars" regex could start
+    // in a comment or `...scaffold.collections` and steal the following
+    // supplements collection's base (#147 handbook dogfood).
     //
     // Forms matched:
     //   - `const chapters = defineCollection({ loader: glob({ base: './foo' }) })`
     //   - `export const collections = { chapters: defineCollection({ loader: glob({ base: './foo' }) }) }`
     //   - any indentation / line break style
-    const re = /\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*'([^']+)'|\bchapters\b[\s\S]{0,500}?\bbase\s*:\s*"([^"]+)"/;
-    const m = source.match(re);
-    const captured = m && (m[1] || m[2]);
+    const collectionCall = findChaptersCollectionCall(source);
+    let captured = null;
+    if (collectionCall) {
+      const loader = /\bloader\s*:/.exec(collectionCall.mask);
+      const base = loader
+        ? /\bbase\s*:/.exec(collectionCall.mask.slice(loader.index + loader[0].length))
+        : null;
+      if (base) {
+        const valueOffset = loader.index + loader[0].length + base.index + base[0].length;
+        const literal = collectionCall.body.slice(valueOffset).match(/^\s*(?:'([^']+)'|"([^"]+)")/);
+        captured = literal && (literal[1] || literal[2]);
+      }
+    }
     if (captured) {
       return resolve(projectRoot, captured);
     }