@brandon_m_behring/book-scaffold-astro 4.26.2 → 4.27.0

package/scripts/validate.mjs

@@ -14,7 +14,8 @@
  *   5. <CodeRef path="..." line={N} /> — when BOOK_REPO_ROOT set,
  *      path exists + line in bounds.
  *   6. <Theorem> — has a resolvable kind= (or legacy type=); else it would
- *      render an empty label and throw at build (#121).
+ *      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).
  *   8. Questions collection (#112) — each question's frontmatter `domain` is a
@@ -38,38 +39,11 @@
 import { readFile, access } from 'node:fs/promises';
 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 { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
-
-/**
- * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
- * here because scripts/ is shipped as plain JS without compiling src/.
- *
- * Closes #20 — validate.mjs previously skipped the .env fallback that
- * `resolveProfileWithSource` honors, so consumers who set BOOK_PROFILE in
- * .env (per the SKILL.md and scaffold's create-book defaults) saw the CLI
- * silently default to minimal, masking academic-profile errors.
- */
-function readEnvFile(path = '.env') {
-  try {
-    if (!existsSync(path)) return {};
-    const out = {};
-    for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
-      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
-      if (!m) continue;
-      let val = m[2] ?? '';
-      if (
-        (val.startsWith('"') && val.endsWith('"')) ||
-        (val.startsWith("'") && val.endsWith("'"))
-      ) {
-        val = val.slice(1, -1);
-      }
-      out[m[1]] = val;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
+import { readEnvFile } from './read-env.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold validate [--preset <name>]
@@ -78,8 +52,8 @@ Pre-flight content validator. Checks Cite keys, XRef ids, Figure srcs,
 internal markdown links, and (when BOOK_REPO_ROOT is set) CodeRef paths.
 
 Options:
-  --preset <name>    academic | tools | minimal | course-notes
-                     (overrides BOOK_PRESET / BOOK_PROFILE env)
+  --preset <name>    academic | tools | minimal | course-notes | research-portfolio
+                     Legacy override when no scaffold integration is resolved.
   --help, -h         Print this message and exit (non-mutating).
 
 Env:
@@ -113,12 +87,20 @@ const CHAPTERS_DIR = await readChaptersBase(ROOT);
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
 
-// Preset resolution (matches resolvePreset in src/types.ts):
-//   --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
+let TOOLING_CONFIG;
+try {
+  TOOLING_CONFIG = await loadResolvedBookConfig(ROOT);
+} catch (error) {
+  process.stderr.write(`validate: fatal: ${error?.message ?? error}\n`);
+  process.exit(1);
+}
+
+// Preset resolution:
+//   composed Astro-config preset > --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
 //   .env BOOK_PRESET > .env BOOK_PROFILE >
 //   defineBookSchemas({ preset }) in content.config.ts >
 //   defineBookSchemas({ profile }) in content.config.ts (alias) >
-//   'minimal'.
+//   warned v4 compatibility fallback 'minimal'.
 // .env fallback closes #20 — without it, consumers who set BOOK_PROFILE in
 // .env (the documented convenience in SKILL.md + create-book defaults) saw
 // the CLI silently default to minimal, hiding academic-profile errors.
@@ -126,16 +108,35 @@ const DATA_DIR = resolve(ROOT, 'src/data');
 // canonical v4.5+ defineBookSchemas({ preset, chaptersBase }) form had the
 // CLI silently default to minimal, hiding research-portfolio (and any
 // non-env-set) profile errors while astro build applied the correct settings.
-const dotenv = readEnvFile(resolve(ROOT, '.env'));
+const dotenv = readEnvFile(ROOT);
 const schemaConfig = await readBookSchemaConfig(ROOT);
-const PRESET =
+const PRESET_CANDIDATE =
+  TOOLING_CONFIG.preset ??
   presetFromFlag ??
   process.env.BOOK_PRESET ??
   process.env.BOOK_PROFILE ??
   dotenv.BOOK_PRESET ??
   dotenv.BOOK_PROFILE ??
-  schemaConfig.preset ??
-  'minimal';
+  schemaConfig.preset;
+const PRESETS = ['academic', 'tools', 'minimal', 'course-notes', 'research-portfolio'];
+if (presetFlagIdx >= 0 && !presetFromFlag) {
+  process.stderr.write('validate: --preset requires a value.\n');
+  process.exit(2);
+}
+if (PRESET_CANDIDATE && !PRESETS.includes(PRESET_CANDIDATE)) {
+  process.stderr.write(
+    `validate: preset must be one of ${PRESETS.join(' | ')} ` +
+      `(got ${JSON.stringify(PRESET_CANDIDATE)}).\n`,
+  );
+  process.exit(1);
+}
+const PRESET = PRESET_CANDIDATE ?? 'minimal';
+if (!PRESET_CANDIDATE) {
+  process.stderr.write(
+    "validate: no preset resolved; falling back to 'minimal' for v4 compatibility. " +
+      'This fallback will be removed in v5; configure a built-in style or BOOK_PRESET.\n',
+  );
+}
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
@@ -213,6 +214,37 @@ const warnings = [];
 const fail = (file, line, msg) => errors.push({ file, line, msg });
 const warn = (file, line, msg) => warnings.push({ file, line, msg });
 
+// ===== Self-heal missing generated artifacts (#186) =====
+// These files are intentionally gitignored. Direct `book-scaffold validate`
+// bypasses npm's prevalidate lifecycle, so rebuild each missing artifact before
+// loading it. Existing files remain untouched; child diagnostics and failures
+// are propagated verbatim instead of becoming downstream unknown-id noise.
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+function regenerate(scriptName, artifact) {
+  process.stdout.write(`validate: ${artifact} is missing — regenerating via ${scriptName} (#186)\n`);
+  const result = spawnSync(process.execPath, [join(scriptDir, scriptName)], {
+    cwd: ROOT,
+    env: process.env,
+    encoding: 'utf8',
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.status !== 0) {
+    const detail = result.error ? `: ${result.error.message}` : '';
+    process.stderr.write(
+      `validate: ${scriptName} failed (exit ${result.status ?? 1})${detail} — cannot self-heal.\n`,
+    );
+    process.exit(result.status ?? 1);
+  }
+}
+
+if (!existsSync(join(DATA_DIR, 'labels.json'))) {
+  regenerate('build-labels.mjs', 'src/data/labels.json');
+}
+if (!existsSync(join(DATA_DIR, 'references.json'))) {
+  regenerate('build-bib.mjs', 'src/data/references.json');
+}
+
 // ===== Load reference data (graceful when missing) =====
 async function loadJson(path) {
   try {
@@ -267,6 +299,29 @@ function lineOf(content, idx) {
   return content.slice(0, idx).split('\n').length;
 }
 
+/**
+ * Return a statically knowable n= value. Quoted strings and braced
+ * string/numeric literals are safe to compare; identifiers, calls,
+ * interpolation, and all other expressions are deliberately skipped.
+ */
+function literalTheoremNumber(attrs) {
+  const quoted = attrs.match(/\bn\s*=\s*(["'])(.*?)\1/);
+  if (quoted) return quoted[2];
+
+  const braced = attrs.match(/\bn\s*=\s*\{\s*([^}]*?)\s*\}/);
+  if (!braced) return null;
+  const expression = braced[1].trim();
+  const stringLiteral = expression.match(/^(["'`])([\s\S]*)\1$/);
+  if (stringLiteral) {
+    if (stringLiteral[1] === '`' && stringLiteral[2].includes('${')) return null;
+    return stringLiteral[2];
+  }
+  if (/^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/.test(expression)) {
+    return String(Number(expression));
+  }
+  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
@@ -359,13 +414,33 @@ for (const rel of chapterFiles) {
       );
     }
     const thmId = attrs.match(/\bid=["']([^"']+)["']/);
-    if (thmId && !/\blabel\s*=\s*["']/.test(attrs) && !labels[thmId[1]]) {
+    const hasLabelOverride = /\blabel\s*=/.test(attrs);
+    if (thmId && !hasLabelOverride && !labels[thmId[1]]) {
       fail(
         rel,
         lineOf(content, m.index),
         `<Theorem id="${thmId[1]}"> — not in labels.json; heading silently renders unnumbered. Run build:labels, or fix the id.`,
       );
     }
+    // #176: compare only literal n= values. Dynamic expressions cannot be
+    // evaluated reliably by this intentionally regex-based validator, and a
+    // label= override explicitly opts out of labels.json auto-numbering.
+    const explicitNumber = hasLabelOverride ? null : literalTheoremNumber(attrs);
+    const indexedNumber = thmId ? labels[thmId[1]]?.number : null;
+    if (
+      thmId &&
+      explicitNumber !== null &&
+      indexedNumber != null &&
+      explicitNumber !== String(indexedNumber)
+    ) {
+      fail(
+        rel,
+        lineOf(content, m.index),
+        `<Theorem id="${thmId[1]}" n="${explicitNumber}"> — labels.json numbers it ` +
+          `${indexedNumber}, and the rendered heading + every XRef use the index. ` +
+          'Drop the stale n= (auto-numbering wins) or re-run build:labels.',
+      );
+    }
   }
 
   // 7. BookLink (#96): structural (book= + to=) + best-effort registry membership.
@@ -544,46 +619,6 @@ let questionsChecked = 0;
   }
 }
 
-// ===== v4.6.0 (issue #77): missing-prereq re-framing =====
-//
-// When errors are downstream symptoms of a missing artifact (references.json
-// or labels.json), abort with ONE leading error pointing at the prereq
-// instead of printing 25 "Unknown bibkey" / "Unknown XRef" symptoms. Single
-// clean signal: fix the prereq. Per D12 of the v4.6.0 plan.
-{
-  if (PROFILE === 'academic') {
-    const refsPath = join(DATA_DIR, 'references.json');
-    const hasBibkeyErrors = errors.some((e) => /Unknown bibkey/.test(e.msg));
-    if (hasBibkeyErrors && !existsSync(refsPath)) {
-      console.error(
-        `\n✗ Validate cannot run: src/data/references.json is missing.\n\n` +
-          `This file is generated from bibliography.bib by 'npm run build:bib'.\n` +
-          `Run that first, OR adopt the prevalidate npm hook convention so\n` +
-          `'npm run validate' regenerates it automatically:\n\n` +
-          `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n` +
-          `  "validate": "book-scaffold validate"\n\n` +
-          `See package/recipes/19-prevalidate-hook.md.\n`,
-      );
-      process.exit(1);
-    }
-  }
-  const labelsPath = join(DATA_DIR, 'labels.json');
-  // #126: also collapse <Theorem id> not-in-labels errors (they share the
-  // "not in labels.json" phrase) under the same missing-prereq message.
-  const hasXrefErrors = errors.some((e) => /not in labels\.json/.test(e.msg));
-  if (hasXrefErrors && !existsSync(labelsPath)) {
-    console.error(
-      `\n✗ Validate cannot run: src/data/labels.json is missing.\n\n` +
-        `This file is generated from <Theorem id="..."> and <Figure id="..."> markers\n` +
-        `in chapter MDX by 'npm run build:labels'. Run that first, OR adopt the\n` +
-        `prevalidate npm hook convention so 'npm run validate' regenerates it:\n\n` +
-        `  "prevalidate": "npm run build:bib && npm run build:labels --if-present"\n\n` +
-        `See package/recipes/19-prevalidate-hook.md.\n`,
-    );
-    process.exit(1);
-  }
-}
-
 // ===== Report =====
 const format = ({ file, line, msg }) => `  ${file}:${line}  ${msg}`;
 if (warnings.length > 0) {
@@ -592,9 +627,15 @@ if (warnings.length > 0) {
 }
 if (errors.length === 0) {
   const qNote = questionsChecked > 0 ? ` + ${questionsChecked} question(s)` : '';
-  console.log(`validate: ✓ ${chapterFiles.length} chapter(s)${qNote} checked (profile=${PROFILE}); no errors.`);
+  console.log(
+    `validate: ✓ ${chapterFiles.length} chapter(s)${qNote} checked ` +
+      `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}); no errors.`,
+  );
   process.exit(0);
 }
-console.error(`validate: ✗ ${errors.length} error(s) in ${chapterFiles.length} chapter(s) (profile=${PROFILE}):`);
+console.error(
+  `validate: ✗ ${errors.length} error(s) in ${chapterFiles.length} chapter(s) ` +
+    `(profile=${PROFILE}, number-style=${TOOLING_CONFIG.numberStyle}):`,
+);
 errors.forEach((e) => console.error(format(e)));
 process.exit(errors.length);

package/src/lib/define-style.ts

@@ -27,7 +27,12 @@
  * for migration from the v3 `preset:` shorthand.
  */
 import type { AstroIntegration, AstroUserConfig } from 'astro';
-import type { BookPreset, RouteToggles } from '../types.js';
+import type {
+  BookPreset,
+  NumberStyle,
+  ReleaseStatusConfig,
+  RouteToggles,
+} from '../types.js';
 
 // ===== Branded nominal type =====
 
@@ -90,6 +95,9 @@ export interface Style {
   /** Profile that backs this style — determines schema + default routes + styles + KaTeX wiring. */
   readonly preset?: BookPreset;
 
+  /** Theorem-family numbering strategy; shallow override (last wins). */
+  readonly numberStyle?: NumberStyle;
+
   /** Book's deployed origin (sitemap, canonical, Pagefind). Required at composition end;
    *  optional inside a Style (so styles can omit it and consumers can provide per-book). */
   readonly site?: string;
@@ -118,13 +126,17 @@ export interface Style {
    *  scalar fields override. */
   readonly markdown?: AstroUserConfig['markdown'];
 
-  /** Deploy target — drives create-book's wrangler.toml shape.
-   *  - `'workers'`: Cloudflare Workers + Static Assets (default for academic/tools/minimal)
-   *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
-   *  Closes #50. */
+  /** Reserved legacy metadata. It is composed but has no runtime or
+   *  create-book effect: create-book chooses wrangler.toml from its CLI
+   *  preset before a consumer Style exists (#180).
+   *  @deprecated Inert in v4; scheduled for removal in v5. */
   readonly deploy?: 'pages' | 'workers';
-  /** v4.27.0 (#149): release-state banner; shallow override (last wins). */
-  readonly releaseStatus?: { state: 'alpha' | 'beta' | 'rc' | 'locked'; dismissAt?: string; message?: string };
+  /**
+   * v4.26.2 (#149; style inheritance fixed in v4.26.3): release-state
+   * banner. Shallow override (last defined wins); `false` suppresses a
+   * banner inherited from an earlier style.
+   */
+  readonly releaseStatus?: ReleaseStatusConfig | false;
 
   /**
    * Scoped consumer-side metadata. Ignored by the toolkit; survives composition
@@ -195,7 +207,8 @@ export function defineStyle(opts: StyleInput): Style {
  *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
  *
  * Per-key merge strategy:
- *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name` → shallow override (last wins)
+ *   - `preset`, `numberStyle`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
+ *     → shallow override (last defined wins; `releaseStatus: false` suppresses)
  *   - `routes` → per-route spread (each route key independently overridable)
  *   - `katexMacros` → per-macro spread (each macro key independently overridable)
  *   - `extra` → per-key spread (consumer metadata accumulates across the chain)
@@ -216,8 +229,12 @@ export function composeStyles(styles: readonly Style[]): Style {
     // Shallow override for primitives + readonly-scalar fields.
     if (style.name !== undefined) merged.name = style.name;
     if (style.preset !== undefined) merged.preset = style.preset;
+    if (style.numberStyle !== undefined) merged.numberStyle = style.numberStyle;
     if (style.site !== undefined) merged.site = style.site;
     if (style.deploy !== undefined) merged.deploy = style.deploy;
+    if (style.releaseStatus !== undefined) {
+      merged.releaseStatus = style.releaseStatus;
+    }
     if (style.mdxComponentsModule !== undefined) {
       merged.mdxComponentsModule = style.mdxComponentsModule;
     }

package/src/lib/nav-href.ts

@@ -29,11 +29,33 @@ export interface ChapterLike {
   data: Record<string, unknown>;
 }
 
-/** Normalize a base URL to exactly one trailing slash (`''` → `'/'`). */
-function normBase(baseUrl: string): string {
+/**
+ * Normalize a base URL to exactly one trailing slash (`''`/`undefined` → `'/'`).
+ *
+ * v4.27.0 (#182): promoted from this module's private helper to THE shared
+ * normalizer — 18 `.astro` files previously inlined the same normalization in
+ * three regex idioms. Astro does not guarantee a trailing slash on `base`
+ * (`'/foo'` is a documented form), so every `import.meta.env.BASE_URL` read
+ * must pass through here before href composition: `${normalizeBase(...)}chapters/`.
+ * Takes the base as a PARAMETER because src/lib ships pre-compiled in dist/,
+ * where Vite's import.meta.env replacement cannot reach (see exam-manifest.ts).
+ */
+export function normalizeBase(baseUrl: string | undefined): string {
   return (baseUrl || '/').replace(/\/*$/, '/');
 }
 
+/**
+ * The composing variant (#182): strip ALL trailing slashes (`'/'` → `''`,
+ * `'/foo/'` → `'/foo'`) for `${baseNoSlash(...)}/answers`-style templates
+ * where the literal supplies the slash (Rationale.astro's route detection).
+ */
+export function baseNoSlash(baseUrl: string | undefined): string {
+  return (baseUrl || '/').replace(/\/+$/, '');
+}
+
+/** Internal alias for the pre-#182 name. */
+const normBase = normalizeBase;
+
 /** Replace `:book` / `:slug` / `:route` / `:id` tokens; `\b` keeps each token
  *  whole, so order is irrelevant and `:id` never matches inside `:identifier`. */
 function fillTokens(pattern: string, tokens: Record<string, string>): string {

package/styles/layout.css

@@ -4,10 +4,10 @@
  *
  * 1. Page chrome at very top: theme toggle (top-right, position: fixed).
  *
- * 2. Optional left sidebar (Sidebar.astro). At ≥64rem (1024px), grid
- *    pins it to the left edge; below 1024px it's hidden (mobile pages
- *    don't carry the nav). Toggle per-page via Base.astro's `showSidebar`
- *    prop — default true; the landing page sets false.
+ * 2. Optional left sidebar (Sidebar.astro). At ≥80rem (1280px), grid
+ *    pins it to the left edge; below 1280px it's hidden and the mobile
+ *    nav drawer is the chapter nav (v4.26.0, #80). Toggle per-page via
+ *    Base.astro's `showSidebar` prop — default true; landing sets false.
  *
  * 3. Main content (.prose) — Tufte 2-column with sidenotes in right
  *    margin on desktop (≥48rem), inline on mobile (<48rem). See
@@ -225,15 +225,21 @@
 }
 
 /* ===== Mobile/tablet nav drawer (v4.26.0, #80) =====
- * Below the sidebar breakpoint (64rem) the left Sidebar is display:none — this
+ * Below the sidebar breakpoint (80rem — matching .layout-with-sidebar above and
+ * the controller's desktop auto-close) the left Sidebar is display:none — this
  * is the navigation in that range: a hamburger in the chrome row toggles a
  * slide-in drawer reusing NavContent (the same book-scoped nav source as the
  * sidebar). No-JS baseline: `:target` opens it (the toggle is <a href="#nav-drawer">);
  * the inline controller in Base.astro enhances it with focus-trap + ESC + body
- * scroll-lock. Hidden at ≥64rem, where the persistent sidebar is the nav. The
- * ≥64rem gutter-fit (sidenote/section-map overflow) is a separate fix. */
+ * scroll-lock. Hidden at ≥80rem, where the persistent sidebar is the nav. The
+ * ≥64rem gutter tier (sidenote/section-map floats) is a separate, lower breakpoint. */
 @media (min-width: 80rem) {
-  .nav-toggle,
+  /* #183: `.chrome-buttons .nav-toggle` (0,2,0), not bare `.nav-toggle` —
+   * Base.astro's global `.chrome-button { display: inline-flex }` ties a
+   * (0,1,0) selector and wins on cascade order, leaving the hamburger
+   * visible at desktop where it opens an invisible drawer and strands the
+   * body scroll-lock. Caught by drawer-interaction.spec.ts. */
+  .chrome-buttons .nav-toggle,
   .nav-drawer {
     display: none;
   }

package/styles/tokens.css

@@ -85,19 +85,17 @@
    * Three-tier responsive measure tuned via Playwright comparison at
    * 375 / 1280 / 1440 / 1920px viewports (post_transformers commit d9d085b).
    *
-   * The classic 65ch Tufte measure feels narrow on wide desktops (≥1440px)
-   * where ~38% of the viewport sits as empty margin. The tiered approach
-   * keeps 65ch where it's typographically right (laptop) and expands to
-   * 80ch / 90ch on wider monitors without crossing the 90ch upper limit
-   * of comfortable line length.
+   * The tiered measures leave room for the book-aware left sidebar and the
+   * Tufte right gutter at every desktop width. v4.26.0 tightened the older
+   * 65/80/90ch values after the responsive audit found horizontal overflow.
    *
    * Tier values + utilization (verified):
-   *   default (≤1440px): 65ch + 28ch  → 70% at 1280px
-   *   1440px tier:       80ch + 24ch  → 69% (with sidebar: 89%)
-   *   1920px tier:       90ch + 26ch  → 57% (with sidebar: 72%)
+   *   default:      60ch + 20ch
+   *   1440px tier:  66ch + 20ch
+   *   1920px tier:  78ch + 24ch
    *
-   * Sidenote column shrinks slightly at wider tiers (24ch / 26ch) to give
-   * main column more room while staying readable for short notes.
+   * These values keep `main + gutter ≤ layout-main` after subtracting the
+   * sidebar, while preserving readable line length and short-note width.
    *
    * Mobile (<48rem) handled separately in layout.css — sidenotes reflow
    * inline; the tokens here don't apply below 48rem.