@brandon_m_behring/book-scaffold-astro 4.31.0 → 5.0.0

package/scripts/build-bib.mjs

@@ -40,6 +40,8 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readEnvFile } from './read-env.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import { mergeCorpusArtifact, resolveBookSelection } from './corpus-tooling.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
@@ -54,6 +56,7 @@ Env:
                      .env; default: ./bibliography.bib).
 
 Options:
+  --book <id>        In corpus mode, rebuild only one registered book.
   --help, -h         Print this message and exit (non-mutating).
 `;
 
@@ -77,8 +80,13 @@ const BIB_PATH = configuredBibPath
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
 const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');
 const SOURCES_OUT = resolve(PROJECT_ROOT, 'src/data/sources.json');
+let DIAGNOSTIC_SCOPE = null;
 
-async function buildReferences() {
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function buildReferences(selection) {
   // Graceful skip when the .bib file is absent (minimal/tools profile, or
   // an academic book that hasn't authored citations yet). Emits an empty
   // references.json so consumers can still `import refs from '...'`.
@@ -87,15 +95,10 @@ async function buildReferences() {
     bibText = await readFile(BIB_PATH, 'utf8');
   } catch (err) {
     if (err.code === 'ENOENT') {
-      console.log(
-        `build-bib: ${BIB_PATH.replace(PROJECT_ROOT + '/', '')} not found — ` +
-          `emitting empty references.json (no citations to process).`,
-      );
-      await mkdir(dirname(OUT_PATH), { recursive: true });
-      await writeFile(OUT_PATH, '{}\n', 'utf8');
-      return;
+      bibText = null;
+    } else {
+      throw err;
     }
-    throw err;
   }
   // v4.0.0 (closes #54): strip `%`-comment lines before passing to citation-js.
   // The plugin-bibtex lexer doesn't honor BibTeX's %-line-comment semantics —
@@ -107,13 +110,14 @@ async function buildReferences() {
   // BibTeX's real comment grammar is "% at the start of a line (after optional
   // whitespace) to end of line". Mid-line `%` (e.g., `note = {50% confidence}`)
   // is NOT a comment and is preserved.
-  const sanitizedBib = bibText
-    .split(/\r?\n/)
-    .map((line) => (line.trimStart().startsWith('%') ? '' : line))
-    .join('\n');
-
-  const cite = new Cite(sanitizedBib);
-  const data = cite.data;
+  const data = bibText === null
+    ? []
+    : new Cite(
+        bibText
+          .split(/\r?\n/)
+          .map((line) => (line.trimStart().startsWith('%') ? '' : line))
+          .join('\n'),
+      ).data;
 
   // Detect duplicates the way biber would (citation-js silently
   // overwrites the earlier entry, which is the opposite of what we want).
@@ -124,19 +128,53 @@ async function buildReferences() {
     seen.add(entry.id);
   }
   if (dupes.length > 0) {
-    console.error(`build-bib: ${dupes.length} duplicate bibkeys:`);
-    for (const id of dupes) console.error(`  - ${id}`);
+    const prefix = selection.corpus ? '[book:corpus] ' : '';
+    console.error(`${prefix}build-bib: ${dupes.length} duplicate bibkeys:`);
+    for (const id of dupes) console.error(`${prefix}build-bib:   - ${id}`);
     process.exit(1);
   }
 
   const byKey = Object.fromEntries(data.map((entry) => [entry.id, entry]));
 
+  if (selection.corpus) {
+    DIAGNOSTIC_SCOPE = 'corpus';
+  }
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: OUT_PATH,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values: new Map(selection.books.map((book) => [book.id, byKey])),
+        emptyValue: () => ({}),
+        artifact: 'src/data/references.json',
+        validateValue: isRecord,
+      })
+    : byKey;
   await mkdir(dirname(OUT_PATH), { recursive: true });
-  await writeFile(OUT_PATH, JSON.stringify(byKey, null, 2) + '\n', 'utf8');
+  await writeFile(OUT_PATH, JSON.stringify(output, null, 2) + '\n', 'utf8');
 
-  console.log(
-    `build-bib: ${data.length} entries -> ${OUT_PATH.replace(PROJECT_ROOT + '/', '')}`,
-  );
+  if (selection.corpus) {
+    for (const book of selection.books) {
+      console.log(
+        `[book:${book.id}] build-bib: ${data.length} entries -> ` +
+          OUT_PATH.replace(PROJECT_ROOT + '/', ''),
+      );
+    }
+    console.log(
+      `[book:corpus] build-bib: ${data.length * selection.books.length} namespaced entries ` +
+        `across ${selection.books.length} book${selection.books.length === 1 ? '' : 's'} -> ` +
+        OUT_PATH.replace(PROJECT_ROOT + '/', ''),
+    );
+  } else if (bibText === null) {
+    console.log(
+      `build-bib: ${BIB_PATH.replace(PROJECT_ROOT + '/', '')} not found — ` +
+        `emitting empty references.json (no citations to process).`,
+    );
+  } else {
+    console.log(
+      `build-bib: ${data.length} entries -> ${OUT_PATH.replace(PROJECT_ROOT + '/', '')}`,
+    );
+  }
 }
 
 // v4.10.0 (closes #85): tools-profile books keep their sources in
@@ -147,17 +185,24 @@ async function buildReferences() {
 // references.json. Absent manifest -> no file written (academic/minimal books
 // degrade to empty, exactly like a missing .bib). YAML is lazy-imported so the
 // --help / no-manifest paths stay dependency-free.
-async function buildSources() {
+async function buildSources(selection) {
   let yamlText;
   try {
     yamlText = await readFile(SOURCES_PATH, 'utf8');
   } catch (err) {
-    if (err.code === 'ENOENT') return; // no manifest — nothing to emit
-    throw err;
+    if (err.code === 'ENOENT') {
+      // A corpus artifact must be a complete, deterministic envelope. Clear
+      // stale source data when the shared manifest disappears; legacy
+      // single-book mode retains its historical no-file/no-write behavior.
+      if (!selection.corpus) return;
+      yamlText = null;
+    } else {
+      throw err;
+    }
   }
 
   const { parse } = await import('yaml');
-  const parsed = parse(yamlText);
+  const parsed = yamlText === null ? null : parse(yamlText);
   // The manifest is a YAML array of source objects. Keep only well-formed
   // entries (a string `id` is the citation key + the /references anchor target).
   // A blank or comments-only manifest parses to null/undefined/[].
@@ -165,21 +210,54 @@ async function buildSources() {
     ? parsed.filter((s) => s && typeof s.id === 'string')
     : [];
 
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: SOURCES_OUT,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values: new Map(selection.books.map((book) => [book.id, sources])),
+        emptyValue: () => [],
+        artifact: 'src/data/sources.json',
+        validateValue: Array.isArray,
+      })
+    : sources;
   await mkdir(dirname(SOURCES_OUT), { recursive: true });
-  await writeFile(SOURCES_OUT, JSON.stringify(sources, null, 2) + '\n', 'utf8');
-  console.log(
-    `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
-      `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
-  );
+  await writeFile(SOURCES_OUT, JSON.stringify(output, null, 2) + '\n', 'utf8');
+  if (selection.corpus) {
+    for (const book of selection.books) {
+      console.log(
+        `[book:${book.id}] build-bib: ${sources.length} ` +
+          `source${sources.length === 1 ? '' : 's'} -> ` +
+          SOURCES_OUT.replace(PROJECT_ROOT + '/', ''),
+      );
+    }
+    console.log(
+      `[book:corpus] build-bib: ${sources.length * selection.books.length} namespaced ` +
+        `source${sources.length * selection.books.length === 1 ? '' : 's'} across ` +
+        `${selection.books.length} book${selection.books.length === 1 ? '' : 's'} -> ` +
+        SOURCES_OUT.replace(PROJECT_ROOT + '/', ''),
+    );
+  } else {
+    console.log(
+      `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
+        `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
+    );
+  }
 }
 
 async function main() {
-  await buildReferences();
-  await buildSources();
+  const toolingConfig = await loadResolvedBookConfig(PROJECT_ROOT);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const selection = resolveBookSelection(toolingConfig, process.argv.slice(2), 'build-bib');
+  await buildReferences(selection);
+  await buildSources(selection);
 }
 
 main().catch((err) => {
-  console.error(`build-bib: failed`);
-  console.error(err);
+  const message = String(err?.message ?? err);
+  const prefix = DIAGNOSTIC_SCOPE ? `[book:${DIAGNOSTIC_SCOPE}] ` : '';
+  console.error(
+    message.startsWith('[book:') ? message : `${prefix}build-bib: failed: ${message}`,
+  );
   process.exit(1);
 });

package/scripts/build-exercises.mjs

@@ -24,6 +24,13 @@
 import { writeFile, mkdir, readFile } from 'node:fs/promises';
 import { resolve, dirname, basename } from 'node:path';
 import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+import {
+  assertLegacyBookMatches,
+  frontmatterSlug,
+  mergeCorpusArtifact,
+  resolveBookSelection,
+} from './corpus-tooling.mjs';
 
 const USAGE = `Usage: book-scaffold build-exercises
 
@@ -36,6 +43,7 @@ Env:
   BOOK_EXERCISES_OUT       Override output path (default: src/data/exercises.json).
 
 Options:
+  --book <id>              In corpus mode, rebuild only one registered book.
   --help, -h               Print this message and exit (non-mutating).
 `;
 
@@ -45,8 +53,8 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 }
 
 const CWD = process.cwd();
-const CHAPTERS_DIR = await readChaptersBase(CWD);
 const OUTPUT_PATH = process.env.BOOK_EXERCISES_OUT ?? 'src/data/exercises.json';
+let DIAGNOSTIC_SCOPE = null;
 
 /**
  * Extract <Exercise id="..."> tags and their body content from MDX.
@@ -85,39 +93,108 @@ function extractExercises(source) {
 }
 
 async function main() {
-  const byChapter = {};
-  let totalExercises = 0;
-  let chaptersWithExercises = 0;
+  const toolingConfig = await loadResolvedBookConfig(CWD);
+  if (toolingConfig.corpus) DIAGNOSTIC_SCOPE = 'corpus';
+  const selection = resolveBookSelection(
+    toolingConfig,
+    process.argv.slice(2),
+    'build-exercises',
+  );
+  DIAGNOSTIC_SCOPE = selection.corpus ? 'corpus' : null;
+  const chaptersRoot = await readChaptersBase(CWD, { corpus: selection.corpus });
+  const runs = selection.corpus
+    ? selection.books.map((book) => ({ book, dir: resolve(chaptersRoot, book.id) }))
+    : [{ book: null, dir: chaptersRoot }];
+  const values = new Map();
+  let corpusExercises = 0;
+  let corpusChapters = 0;
+
+  for (const run of runs) {
+    const byChapter = {};
+    let totalExercises = 0;
+    let chaptersWithExercises = 0;
 
-  for await (const rel of walkMdx(CHAPTERS_DIR)) {
-    const chapterPath = resolve(CHAPTERS_DIR, rel);
-    const chapterSlug = basename(rel).replace(/\.mdx?$/, '');
-    let source;
-    try {
-      source = await readFile(chapterPath, 'utf8');
-    } catch {
-      continue;
+    for await (const rel of walkMdx(run.dir)) {
+      const chapterPath = resolve(run.dir, rel);
+      let source;
+      try {
+        source = await readFile(chapterPath, 'utf8');
+      } catch {
+        continue;
+      }
+      if (run.book) {
+        assertLegacyBookMatches(
+          source,
+          run.book,
+          `[book:${run.book.id}] ${chapterPath.replace(`${CWD}/`, '')}`,
+        );
+      }
+      const fileLabel = run.book
+        ? `[book:${run.book.id}] ${chapterPath.replace(`${CWD}/`, '')}`
+        : chapterPath.replace(`${CWD}/`, '');
+      const chapterSlug = run.book
+        ? frontmatterSlug(source, fileLabel) ?? rel.replace(/\.mdx?$/, '')
+        : basename(rel).replace(/\.mdx?$/, '');
+      const exercises = extractExercises(source);
+      if (exercises.length > 0) {
+        byChapter[chapterSlug] = exercises;
+        totalExercises += exercises.length;
+        chaptersWithExercises += 1;
+      }
     }
-    const exercises = extractExercises(source);
-    if (exercises.length > 0) {
-      byChapter[chapterSlug] = exercises;
-      totalExercises += exercises.length;
-      chaptersWithExercises += 1;
+
+    if (run.book) {
+      values.set(run.book.id, byChapter);
+      corpusExercises += totalExercises;
+      corpusChapters += chaptersWithExercises;
+      process.stdout.write(
+        `[book:${run.book.id}] build-exercises: ${totalExercises} ` +
+          `exercise${totalExercises === 1 ? '' : 's'} across ${chaptersWithExercises} ` +
+          `chapter${chaptersWithExercises === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+      );
+    } else {
+      values.set('', byChapter);
+      corpusExercises = totalExercises;
+      corpusChapters = chaptersWithExercises;
     }
   }
 
   const outPath = resolve(CWD, OUTPUT_PATH);
+  const output = selection.corpus
+    ? await mergeCorpusArtifact({
+        path: outPath,
+        corpus: selection.corpus,
+        requestedBook: selection.requestedBook,
+        values,
+        emptyValue: () => ({}),
+        artifact: OUTPUT_PATH,
+        validateValue: (value) =>
+          value !== null && typeof value === 'object' && !Array.isArray(value),
+      })
+    : values.get('');
   await mkdir(dirname(outPath), { recursive: true });
-  await writeFile(outPath, JSON.stringify(byChapter, null, 2) + '\n');
-  process.stdout.write(
-    `build-exercises: ${totalExercises} exercise${totalExercises === 1 ? '' : 's'} across ` +
-      `${chaptersWithExercises} chapter${chaptersWithExercises === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
-  );
+  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (selection.corpus) {
+    process.stdout.write(
+      `[book:corpus] build-exercises: ${corpusExercises} ` +
+        `exercise${corpusExercises === 1 ? '' : 's'} across ${corpusChapters} ` +
+        `chapter${corpusChapters === 1 ? '' : 's'} and ${selection.books.length} ` +
+        `book${selection.books.length === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `build-exercises: ${corpusExercises} exercise${corpusExercises === 1 ? '' : 's'} across ` +
+        `${corpusChapters} chapter${corpusChapters === 1 ? '' : 's'} → ${OUTPUT_PATH}\n`,
+    );
+  }
 }
 
 main().catch((err) => {
-  console.error('build-exercises: failed');
-  console.error(err.message ?? err);
+  const message = String(err?.message ?? err);
+  const prefix = DIAGNOSTIC_SCOPE ? `[book:${DIAGNOSTIC_SCOPE}] ` : '';
+  console.error(
+    message.startsWith('[book:') ? message : `${prefix}build-exercises: failed: ${message}`,
+  );
   process.exit(1);
 });