@brandon_m_behring/book-scaffold-astro 5.0.0 → 5.1.0

package/CLAUDE.md

@@ -50,9 +50,11 @@ those directories belong to scaffold content collections, not chapter owners.
 Keep every lookup book-scoped: navigation/previous-next, labels, references,
 tips, exercises, questions, and glossary entries must select the current
 manifest book. Corpus JSON is `{ schemaVersion: 1, books: { [id]: payload } }`;
-single-book JSON remains flat. Use `--book <id>` only with the content-derived
-`build-labels`, `build-bib`, `build-tips`, `build-exercises`, and `validate`
-commands. Figures and notebooks remain application-wide.
+single-book JSON remains flat. The content-derived `build-labels`, `build-bib`,
+`build-tips`, `build-exercises`, and `validate` commands accept `--book <id>`
+in corpus mode. `qa` defaults to all manifest books, accepts either one exact
+`--book <id>` or `--all`, and rejects `--book` in single-book mode. Figures and
+notebooks remain application-wide.
 
 Convergence collateral lives at `changelog/<book>/patterns.yaml` and
 `changelog/<book>/tools/*.yaml`; root-level v4 collateral is single-book only.
@@ -201,6 +203,7 @@ npm install                  # once after clone
 npm run dev                  # localhost:4321
 npm run build                # astro build + pagefind index → dist/
 npm run validate             # pre-flight check (recipe 09)
+npm exec -- book-scaffold qa # content-readiness verdict (recipe 25)
 npm run build:bib            # rebuild references.json after .bib edit
 npm run pdf                  # render dist-pdf/book.pdf via Paged.js
 ```
@@ -227,6 +230,27 @@ A consumer `public/_headers` wins unchanged. Use
 or `securityHeaders: false` when another layer owns all headers. Recipe 05 has
 the full precedence and customization contract.
 
+## QA and content readiness
+
+Run `npm exec -- book-scaffold qa` after substantive content changes. It calls
+the same content-contract library as `validate`, then reports stable chapter,
+link, learning-objective, component, and JSON-fixture facts. Human output is
+the default. For CI use `npm --offline exec -- book-scaffold qa --format json`;
+JSON stdout contains only the schema-v1 result, while progress/fatal details go
+to stderr. Exit `0` means no blocking failure, `1` means a red selected/shared
+result, and `2` means the invocation or execution failed.
+
+In a corpus, omission checks every manifest book in order; `--book <id>` checks
+one and `--all` states the default explicitly. Schema v1 always includes a
+top-level `shared: { verdict, checks, diagnostics }` aggregate for corpus-wide
+fixture data. Its exact single-book value is
+`{ "verdict": "not_applicable", "checks": {}, "diagnostics": [] }`.
+
+Run `npm exec -- book-scaffold init-qa` only when a portfolio QA engine needs
+`guide_qa.yaml`. It emits one deterministic offline command per manifest book,
+or one implicit `book` entry without `--book`. It preserves an existing file;
+`--force` replaces that whole file and no other path. See Recipe 25.
+
 ## Validation
 
 `npm run validate` (also runs in prebuild) catches:

package/README.md

@@ -49,6 +49,40 @@ local `<BookLink>` targets, and Pagefind results remain book-scoped. See
 [Recipe 21](./recipes/21-multi-guide-single-app.md) for content layout, route
 ownership, `--book` tooling, shared sources, and migration.
 
+## Content readiness and CLI
+
+`book-scaffold qa` combines the existing validation contract with stable
+chapter, link, learning-objective, component, and JSON-fixture metrics. Human
+output is the default; schema-v1 JSON is deterministic and keeps stdout clean
+for CI:
+
+```bash
+npm exec -- book-scaffold qa
+npm --offline exec -- book-scaffold qa --format json
+npm exec -- book-scaffold init-qa
+```
+
+In corpus mode `qa` checks every manifest book by default, while `--book <id>`
+selects one exact id. `init-qa` creates the portfolio-engine interoperability
+file `guide_qa.yaml`; its generated checks use `npm --offline exec` and an
+existing file is preserved unless `--force` is explicit. See
+[Recipe 25](./recipes/25-qa-readiness.md) for verdicts, exit codes, the
+top-level `shared` aggregate, and CI wiring.
+
+The installed `book-scaffold` dispatcher owns these commands:
+
+| Command | Purpose |
+|---|---|
+| `validate` | Pre-flight authored content, references, figures, and links |
+| `qa` | Emit a human or schema-v1 readiness verdict |
+| `init-qa` | Generate deterministic `guide_qa.yaml` interoperability config |
+| `build-labels` | Build cross-reference and heading indexes |
+| `build-bib` | Build bibliography and source-manifest data |
+| `build-tips` | Build the tips index |
+| `build-exercises` | Build the exercises index |
+| `build-figures` | Convert and theme application-wide figure assets |
+| `render-notebooks` | Render application-wide notebook companions |
+
 Astro builds emit a Cloudflare-compatible `dist/_headers` with audited
 security defaults. A consumer-owned `public/_headers` wins unchanged;
 `defineBookConfig({ securityHeaders: false })` disables scaffold emission,

package/bin/book-scaffold.mjs

@@ -14,6 +14,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const handlers = {
   validate: '../scripts/validate.mjs',
+  qa: '../scripts/qa.mjs',
+  'init-qa': '../scripts/init-qa.mjs',
   'build-labels': '../scripts/build-labels.mjs',
   'build-bib': '../scripts/build-bib.mjs',
   'build-figures': '../scripts/build-figures.mjs',
@@ -26,6 +28,8 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
+  qa                 Content-health and readiness report (human or schema-v1 JSON).
+  init-qa            Generate deterministic guide_qa.yaml interoperability config.
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
   build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).

package/dist/index.mjs

@@ -1623,6 +1623,9 @@ function bookScaffoldIntegration(opts) {
     ),
     frontmatter: fmEnabled
   };
+  const enabledRouteNames = Object.freeze(
+    Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name)
+  );
   if (corpus) {
     for (const book of corpus.books) {
       for (const route of book.apparatus ?? []) {
@@ -1693,7 +1696,6 @@ function bookScaffoldIntegration(opts) {
         const resolvedGithubRepo = resolveBookGithubRepo(githubRepo, consumerRoot);
         const resolvedGithubBranch = githubBranch ?? DEFAULT_GITHUB_BRANCH;
         const presetLiteral = JSON.stringify(profile);
-        const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
           vite: {
             plugins: [
@@ -1768,7 +1770,9 @@ function bookScaffoldIntegration(opts) {
       chapterRoute: corpus ? "/chapters/:id/" : chapterRoute ?? "/chapters/:id/",
       bookField: bookField ?? "book",
       apparatusRoute: corpus ? "/:book/:route/" : apparatusRoute ?? "/:route/",
-      apparatusRoutes: corpus ? inheritedCorpusApparatusRoutes : apparatusRoutes ?? []
+      apparatusRoutes: corpus ? inheritedCorpusApparatusRoutes : apparatusRoutes ?? [],
+      enabledRoutes: enabledRouteNames,
+      frontmatterRoute: frontmatterPatternFromPrefix(fmPrefix)
     }),
     enumerable: false,
     configurable: false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -203,6 +203,7 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
+    "ajv": "^8.20.0",
     "pagefind": "^1.5.2",
     "parse5": "^7.3.0",
     "remark-math": "^6.0.0",

package/recipes/25-qa-readiness.md

@@ -0,0 +1,197 @@
+# Recipe 25 — QA and content readiness
+
+**Profile**: any, in single-book or corpus mode.
+
+**TL;DR**: `book-scaffold qa` turns the scaffold's content contract and stable
+MDX facts into one CI-safe readiness verdict. Human output is the default;
+`--format json` emits deterministic schema-v1 JSON. Use
+`book-scaffold init-qa` only when a portfolio QA engine needs a network-free
+`guide_qa.yaml` registry.
+
+## Run the readiness check
+
+Run the locally installed binary from the book root:
+
+```bash
+npm exec -- book-scaffold qa
+```
+
+This checks the implicit book in a single-book project. In a corpus, omission
+of a selector checks every manifest book in manifest order. Select one exact
+registered id or spell out the all-books default with:
+
+```bash
+npm exec -- book-scaffold qa --book evaluation
+npm exec -- book-scaffold qa --all
+```
+
+`--book` is invalid in single-book mode. `--book` and `--all` are mutually
+exclusive; an unknown book id is an invocation error rather than an empty
+report.
+
+## What QA means
+
+QA reuses the same content-contract library as `book-scaffold validate`, then
+adds deterministic readiness facts:
+
+| Check | Blocking condition |
+|---|---|
+| `content_contract` | Any validation error |
+| `chapters` | No non-draft chapter |
+| `links` | Any broken internal target or fragment |
+| `learning_objectives` | Less than 100% anchor coverage when objectives apply |
+| `components` | Never blocking; counts scaffold MDX components |
+| `demo_fixtures` | Invalid non-generated JSON or a failing referenced schema |
+
+An unavailable metric is `not_applicable`, not a fabricated zero. Component
+counts are inventory facts, not universal prose-quality scores. `qa` also does
+not replace `astro build`: rendering, content-collection Zod checks, and KaTeX
+remain build responsibilities.
+
+The traffic-light states are `green`, `amber`, `red`, and `not_applicable`.
+Amber advisories stay visible but do not fail CI. Exit status is:
+
+| Exit | Meaning |
+|---|---|
+| `0` | No blocking failure (`green` or `amber`) |
+| `1` | At least one selected book or corpus-shared check is `red` |
+| `2` | Invalid invocation, unresolved configuration, or internal failure |
+
+The link check inspects internal links authored in chapter Markdown/MDX. It
+uses the resolved scaffold route toggles, Astro page conventions, and public
+assets as its route oracle. Fragments that depend on a consumer-defined MDX
+component or a known non-chapter route are reported as amber
+`fragment_unverified` advisories instead of guessed successes or blocking
+failures.
+
+Schema-v1 fixture validation supports JSON Schema draft-07 (also the default
+when `$schema` is absent), 2019-09, and 2020-12. Recursive `$ref` resources must
+remain inside the project after symlink resolution; QA never fetches network
+schemas. The JSON Schema `format` keyword is annotation-only in v1. Unsupported
+or mixed dialects and out-of-project references make that fixture red.
+
+## Human and JSON output
+
+Human output is compact and terminal-oriented:
+
+```bash
+npm exec -- book-scaffold qa --format human
+```
+
+For automation, use the stable JSON form (`--json` is an alias):
+
+```bash
+npm --offline exec -- book-scaffold qa --format json > qa-result.json
+```
+
+JSON stdout contains only the schema-v1 document; progress and fatal
+diagnostics use stderr. The document omits timestamps and durations, preserves
+manifest/source order, and always contains `books`, `shared`, and `summary`.
+
+`books` contains only the implicit `book` result or registered manifest ids.
+`shared` is never a synthetic book. It is an always-present aggregate shaped
+like a book result:
+
+```json
+{
+  "verdict": "not_applicable",
+  "checks": {},
+  "diagnostics": []
+}
+```
+
+That exact value is used in single-book mode. In corpus mode,
+`shared.checks.demo_fixtures` holds the normal `{ state, metrics,
+diagnosticIds }` check payload for JSON under `src/data/` outside a registered
+book directory. A shared failure affects the top-level corpus verdict and
+summary, never an individual book verdict. Its diagnostics use
+`book: "corpus"` rather than borrowing a manifest id.
+
+## Generate `guide_qa.yaml`
+
+Portfolio-level QA engines can discover the scaffold check without a custom
+consumer wrapper:
+
+```bash
+npm exec -- book-scaffold init-qa
+```
+
+A single-book project gets this deterministic file:
+
+```yaml
+# Generated by book-scaffold init-qa.
+# Regenerate with: book-scaffold init-qa --force
+version: 1
+guides:
+  - id: book
+    check_cmd: npm --offline exec -- book-scaffold qa --format json
+```
+
+A corpus gets one entry per manifest book, in manifest order, with an exact
+selector:
+
+```yaml
+# Generated by book-scaffold init-qa.
+# Regenerate with: book-scaffold init-qa --force
+version: 1
+guides:
+  - id: evaluation
+    check_cmd: npm --offline exec -- book-scaffold qa --book evaluation --format json
+  - id: llm-app-engineering
+    check_cmd: npm --offline exec -- book-scaffold qa --book llm-app-engineering --format json
+```
+
+The generated `npm --offline exec --` commands can use only the installed
+toolkit; they never fetch a package. `book-scaffold qa` does not read or
+execute `guide_qa.yaml` itself.
+
+An existing file is preserved and makes `init-qa` fail. Regenerate explicitly
+with:
+
+```bash
+npm exec -- book-scaffold init-qa --force
+```
+
+`--force` replaces the whole `guide_qa.yaml` and changes no other file. A
+portfolio engine may add presentation fields, but forced regeneration removes
+those edits.
+
+## CI wiring
+
+After the dependency install, offline execution prevents a typo or missing
+local binary from becoming an implicit registry download:
+
+```yaml
+- run: npm ci
+- run: npm --offline exec -- book-scaffold qa --format json > qa-result.json
+- run: npm run build
+```
+
+Keep the build step. QA supplies a content-health verdict; the production
+build remains the render/deployment gate.
+
+## Common gotchas
+
+- **Treating N/A as zero** — unavailable profile/content metrics are explicitly
+  `not_applicable`.
+- **Expecting `components` to grade prose** — counts are informational and
+  never impose cross-preset quotas.
+- **Attributing shared corpus JSON to a book** — only files beneath
+  `src/data/<book>/` belong to that book. Other non-generated JSON is checked
+  once through the top-level `shared` result.
+- **Counting generated indexes as fixtures** — scaffold outputs including
+  `labels.json`, `references.json`, `tips.json`, and `exercises.json` are
+  excluded.
+- **Hand-editing generated commands** — use engine-owned presentation fields
+  if needed; `init-qa --force` intentionally restores canonical commands.
+- **Using `--book` for a one-book project** — the implicit id is represented as
+  `book` in results and `guide_qa.yaml`, but it is not a selectable corpus id.
+
+## Canonical files
+
+- `scripts/qa-core.mjs` — deterministic check and aggregate engine
+- `scripts/init-qa.mjs` — deterministic, overwrite-safe registry generator
+- `scripts/validate-core.mjs` — shared validation library used by QA's
+  content contract
+- `recipes/09-validation.md` — individual diagnostics and prebuild wiring
+- `../../docs/plans/active/qa-contract.md` — accepted schema and selector contract

package/recipes/README.md

@@ -30,6 +30,7 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 22 | [Responsive navigation and custom routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav and the v4-compatible consumer-owned route-token API |
 | 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
 | 24 | [Figure authoring standard](24-figure-authoring-standard.md) | any | Warm–Tol semantics, Okabe–Ito series, dual-theme exports, contrast, and accessible descriptions |
+| 25 | [QA and content readiness](25-qa-readiness.md) | any | Stable human/JSON readiness verdicts, corpus selection, CI, and `guide_qa.yaml` |
 
 ## How to read recipes
 

package/scripts/init-qa.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Generate the portfolio QA engine's deterministic guide registry.
+ *
+ * This module deliberately owns only guide_qa.yaml generation. The scaffold
+ * QA command does not execute the generated shell commands, and this script
+ * never spawns npm or performs network work itself.
+ */
+import { access, writeFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+
+export const GUIDE_QA_FILENAME = 'guide_qa.yaml';
+export const GUIDE_QA_HEADER =
+  '# Generated by book-scaffold init-qa.\n' +
+  '# Regenerate with: book-scaffold init-qa --force\n';
+
+export const INIT_QA_USAGE = `Usage: book-scaffold init-qa [--force]
+
+Create a deterministic guide_qa.yaml for the implicit single book or every
+registered corpus book. Generated checks use the locally installed scaffold
+binary in npm offline mode.
+
+Options:
+  --force       Replace an existing guide_qa.yaml. No other file is changed.
+  --help, -h    Print this message and exit without writing a file.
+`;
+
+const BOOK_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const COMMAND_PREFIX = 'npm --offline exec -- book-scaffold qa';
+
+export class InitQaUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'InitQaUsageError';
+  }
+}
+
+export class GuideQaExistsError extends Error {
+  constructor(path) {
+    super(`${GUIDE_QA_FILENAME} already exists; rerun with --force to replace it.`);
+    this.name = 'GuideQaExistsError';
+    this.code = 'EEXIST';
+    this.path = path;
+  }
+}
+
+/** Parse only the flags owned by init-qa. */
+export function parseInitQaArgs(argv) {
+  if (!Array.isArray(argv)) {
+    throw new TypeError('init-qa arguments must be an array.');
+  }
+
+  let force = false;
+  let help = false;
+  for (const arg of argv) {
+    if (arg === '--force') {
+      if (force) throw new InitQaUsageError('--force may be specified only once.');
+      force = true;
+    } else if (arg === '--help' || arg === '-h') {
+      help = true;
+    } else {
+      throw new InitQaUsageError(`unknown argument ${JSON.stringify(arg)}.`);
+    }
+  }
+  return Object.freeze({ force, help });
+}
+
+function guideIds(toolingConfig) {
+  if (toolingConfig === null || typeof toolingConfig !== 'object' || Array.isArray(toolingConfig)) {
+    throw new TypeError('init-qa requires resolved book tooling configuration.');
+  }
+
+  if (toolingConfig.corpus == null) return Object.freeze(['book']);
+  const books = toolingConfig.corpus.books;
+  if (!Array.isArray(books) || books.length === 0) {
+    throw new TypeError('init-qa requires a non-empty resolved corpus book list.');
+  }
+
+  const ids = [];
+  const seen = new Set();
+  for (const [index, book] of books.entries()) {
+    const id = book?.id;
+    if (typeof id !== 'string' || !BOOK_ID_PATTERN.test(id)) {
+      throw new TypeError(`init-qa received an invalid corpus book id at index ${index}.`);
+    }
+    if (seen.has(id)) {
+      throw new TypeError(`init-qa received duplicate corpus book id ${JSON.stringify(id)}.`);
+    }
+    seen.add(id);
+    ids.push(id);
+  }
+  return Object.freeze(ids);
+}
+
+/** Render the exact, stable interoperability document for resolved config. */
+export function renderGuideQa(toolingConfig) {
+  const ids = guideIds(toolingConfig);
+  const corpus = toolingConfig.corpus != null;
+  const lines = [GUIDE_QA_HEADER.trimEnd(), 'version: 1', 'guides:'];
+
+  for (const id of ids) {
+    lines.push(`  - id: ${id}`);
+    const selector = corpus ? ` --book ${id}` : '';
+    lines.push(`    check_cmd: ${COMMAND_PREFIX}${selector} --format json`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function pathExists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/**
+ * Resolve the consumer config and write only guide_qa.yaml.
+ *
+ * `loadConfig` is injectable so callers and tests can reuse this filesystem
+ * boundary without evaluating an Astro config more than once.
+ */
+export async function initGuideQa({
+  projectRoot = process.cwd(),
+  force = false,
+  loadConfig = loadResolvedBookConfig,
+} = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('init-qa projectRoot must be a non-empty string.');
+  }
+  if (typeof force !== 'boolean') {
+    throw new TypeError('init-qa force must be a boolean.');
+  }
+  if (typeof loadConfig !== 'function') {
+    throw new TypeError('init-qa loadConfig must be a function.');
+  }
+
+  const root = resolve(projectRoot);
+  const outputPath = resolve(root, GUIDE_QA_FILENAME);
+  if (!force && (await pathExists(outputPath))) {
+    throw new GuideQaExistsError(outputPath);
+  }
+
+  const toolingConfig = await loadConfig(root);
+  const contents = renderGuideQa(toolingConfig);
+  try {
+    await writeFile(outputPath, contents, {
+      encoding: 'utf8',
+      flag: force ? 'w' : 'wx',
+    });
+  } catch (error) {
+    if (!force && error?.code === 'EEXIST') throw new GuideQaExistsError(outputPath);
+    throw error;
+  }
+
+  return Object.freeze({
+    path: outputPath,
+    contents,
+    guideIds: guideIds(toolingConfig),
+  });
+}
+
+/** Run the command with injectable streams and return its contract exit code. */
+export async function runInitQaCli({
+  argv = process.argv.slice(2),
+  projectRoot = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  loadConfig = loadResolvedBookConfig,
+} = {}) {
+  let options;
+  try {
+    options = parseInitQaArgs(argv);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    stderr.write(`init-qa: ${detail}\n\n${INIT_QA_USAGE}`);
+    return 2;
+  }
+
+  if (options.help) {
+    stdout.write(INIT_QA_USAGE);
+    return 0;
+  }
+
+  try {
+    const result = await initGuideQa({ projectRoot, force: options.force, loadConfig });
+    const label = relative(resolve(projectRoot), result.path) || GUIDE_QA_FILENAME;
+    stdout.write(`init-qa: wrote ${label}\n`);
+    return 0;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof GuideQaExistsError || error?.code === 'EEXIST') {
+      stderr.write(`init-qa: ${detail}\n`);
+      return 1;
+    }
+    stderr.write(`init-qa: fatal: ${detail}\n`);
+    return 2;
+  }
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runInitQaCli();
+}