@brandon_m_behring/book-scaffold-astro 4.19.0 → 4.20.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/09-validation.md

@@ -13,6 +13,12 @@
 | `<Figure src="/...">` file exists under `public/` | all | Figure.astro emits a broken-image icon for missing files; build doesn't fail. |
 | `[text](/internal-link)` resolves to known chapter slug or top-level route | all | Astro won't fail on dead internal links. Warning, not error (regex misses dynamic routes). |
 | `<CodeRef path="..." line={N} />` path exists + line in bounds | all, if `BOOK_REPO_ROOT` set | Catches stale line numbers after code refactors in the paired experiments/ repo. |
+| `<Theorem>` has a resolvable `kind=` (or legacy `type=`); an id'd theorem resolves in `labels.json` (#121, #126) | all | An absent kind throws at build with less context; an unindexed id silently renders the heading unnumbered. |
+| `<BookLink book= to=>` both present; `book=` registered in `siblingBooks` (#96) | all | Pre-flights the component's build-time throw across all files at once. |
+| Questions collection: unique `id`s + `domain` in `examDomains` (#112) | all, when `src/content/questions/` exists | Duplicate ids break the appendix/flashcards cross-ref key; an unregistered domain throws one-at-a-time at build. |
+| `los[].anchor` ↔ `{/* anchor: <slug> */}` prose markers agree both ways (#130, v4.20.0) | all, when frontmatter has `los:` | A declared objective whose prose marker is missing/misspelled (or an orphan marker) builds green otherwise — frontmatter↔prose drift only a hand audit would catch. |
+
+Validate also emits two **non-blocking shadow-route warnings** (exit code unaffected): a consumer-owned `src/pages/chapters/[...slug].astro` without `routes: { chapters: false }` (v4.6.0, #76), and a consumer-owned `src/pages/index.astro` without `routes: { landing: false }` (v4.20.0, #129 — Astro has announced this collision becomes a hard error). See [recipe 18](./18-chapter-route-ownership.md).
 
 ## What is NOT checked (already covered elsewhere)
 

package/recipes/18-chapter-route-ownership.md

@@ -82,6 +82,18 @@ If your file has real customization, prefer State 2: keep the file and add `rout
 
 ---
 
+## The landing route (`/`) follows the same rules (v4.20.0, #129)
+
+Everything above applies verbatim to a consumer-owned `src/pages/index.astro` vs the scaffold's auto-injected `/` landing page — with one extra wrinkle: **Astro has announced that static-route collisions become a hard error in a future version**, so the State-3 shadow isn't just confusing here, it's a latent build break.
+
+- **State 1** — no consumer `src/pages/index.astro`; the scaffold's minimal landing renders from your book config.
+- **State 2** — your custom landing page exists AND `defineBookConfig({ routes: { landing: false } })` is set. No injected route, no collision, no future break.
+- **State 3** — your file exists but `routes.landing` is undefined/true. Your page wins today with a `[router]` collision WARN on every build; it stops building when Astro flips the warning to an error. `book-scaffold validate` warns about this state in v4.20.0+.
+
+**Fix**: add `routes: { landing: false }` next to your custom landing page.
+
+---
+
 ## Why this matters
 
 Layer-3 cleanup is part of [issue #76](https://github.com/brandon-behring/book-scaffold-astro/issues/76)'s v4.6 bundle. Related companion: [recipe 19 — prevalidate-hook](./19-prevalidate-hook.md), which fixes another silent-CI gap surfaced during the same first-deploy sessions.

package/recipes/21-multi-guide-single-app.md

@@ -0,0 +1,73 @@
+# Recipe 21 — Multiple guides in one app (v4.20.0, #132)
+
+**Profile**: any (proven on research-portfolio).
+
+**TL;DR**: To host more than one guide/book in a single Astro app, keep ONE `chapters` collection rooted at `src/content/` and namespace every entry id by its guide folder via a `generateId` in the glob loader. The scaffold's existing rest-param route (`/chapters/[...slug]/`) then serves `/chapters/<guide>/<slug>/` for every guide with **no scaffold changes**. This is the blessed interim pattern until multibook (#15) ships first-class support.
+
+## The pattern
+
+Author each guide under its own folder:
+
+```
+src/content/
+├── evaluation/
+│   ├── 01-why-evaluation.mdx
+│   └── ...
+├── llm-app-engineering/
+│   ├── 01-why-llm-app-engineering.mdx
+│   └── ...
+└── frontmatter/            ← shared, excluded below
+```
+
+Point the collection at the shared base and namespace ids by guide:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { researchPortfolioChapterSchema } from '@brandon_m_behring/book-scaffold-astro/schemas';
+
+const chapters = defineCollection({
+  loader: glob({
+    pattern: ['**/*.{md,mdx}', '!**/_*', '!frontmatter/**'],
+    base: './src/content',
+    generateId: ({ entry, data }) => {
+      const guide = entry.split('/')[0];
+      const slug =
+        (data && data.slug) || entry.replace(/\.[^.]+$/, '').split('/').pop();
+      return `${guide}/${slug}`; // → /chapters/<guide>/<slug>/
+    },
+  }),
+  schema: researchPortfolioChapterSchema,
+});
+
+export const collections = { chapters };
+```
+
+The scaffold's auto-injected `pages/chapters/[...slug].astro` routes on `params: { slug: entry.id }` — a namespaced id rides through unchanged, so both guides render with zero route overrides.
+
+## Gotcha 1 — the flat-slug footgun
+
+**Without** the `generateId`, Astro's glob loader keys entry ids off the frontmatter `slug` (or filename) and routes FLAT at `/chapters/<slug>/`. That silently requires slugs to be **globally unique across all guides** — two guides each having an `introduction` chapter is a route collision, surfaced as a confusing router warning rather than a clear error. The `generateId` namespacing makes slugs only need uniqueness *within* a guide, which is what authors expect.
+
+## Gotcha 2 — `validate` counts everything under the base
+
+With `base: './src/content'`, `book-scaffold validate` walks the whole base — shared folders like `frontmatter/` are counted as "chapters" (e.g. `16 chapter(s)` for 13 + 2 real chapters + an authors page). The checks still run correctly per file; only the count is inflated. Excluding non-guide folders from the *loader* pattern does not affect the validator's walk. Guide-aware validation is part of the first-class multibook design (#15).
+
+## Gotcha 3 — the `/chapters/` index mixes guides
+
+The auto-injected `/chapters/` index lists every entry in the collection — i.e. all guides interleaved. If you want per-guide landing pages, add consumer-owned pages (e.g. `src/pages/evaluation/index.astro`) that `getCollection('chapters', (e) => e.id.startsWith('evaluation/'))`. A grouped-by-guide index is also on the #15 wishlist.
+
+## When to expect first-class support
+
+This recipe is the interim, zero-scaffold-change path. Issue [#15 (multibook)](https://github.com/brandon-behring/book-scaffold-astro/issues/15) tracks a `books`/`guides` registry that would emit per-guide indexes, a guides landing, and guide-scoped `validate`. It was deferred pending 2–3 independent consumers; `guides-ai-engineering` (#132) is the second — file your use case on #15 to add weight.
+
+## Canonical files
+
+- `package/pages/chapters/[...slug].astro` — the rest-param route that makes namespaced ids "just work"
+- `package/scripts/walk-mdx.mjs` — `readChaptersBase` (how validate finds the base)
+- `package/recipes/12-where-to-file-issues.md` — multi-book corpus routing is a known scaffold-issue category
+
+## Reference implementation
+
+`guides-ai-engineering` — two guides (Evaluation + LLM Application Engineering) on `@brandon_m_behring/book-scaffold-astro@4.14.2`; both `dist/chapters/evaluation/why-evaluation/index.html` and `dist/chapters/llm-app-engineering/why-llm-app-engineering/index.html` build from the scaffold's injected route.

package/recipes/README.md

@@ -26,6 +26,7 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 18 | [Chapter route ownership](18-chapter-route-ownership.md) | any | When to override the auto-injected `/chapters/[...slug]/` route |
 | 19 | [Prevalidate hook](19-prevalidate-hook.md) | any | Wire `prevalidate` to run `build:bib` + `build:labels` before `validate` |
 | 20 | [Anki deck export (consumer-side)](20-anki-export.md) | any (esp. course-notes, research-portfolio) | Roll-your-own `<AnkiCard>` + extractor; scaffold deliberately doesn't ship this |
+| 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#15) |
 
 ## How to read recipes
 

package/scripts/validate.mjs

@@ -20,6 +20,9 @@
  *   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.
  *
  * Run from the consumer's project root. Closes #8 (was resolving paths
  * from the package's own directory inside node_modules — false negatives
@@ -177,6 +180,34 @@ const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;
   }
 }
 
+// v4.20.0 (issue #129): the same shadow warning for the landing route. A
+// consumer-owned `src/pages/index.astro` collides with the scaffold's
+// auto-injected `/` (Astro warns today and has announced a hard error in a
+// future major). The escape hatch already exists — `routes: { landing: false }`
+// — this check makes it discoverable before Astro's break lands. Same edge
+// cases + heuristic as the chapters check above.
+{
+  const consumerLanding = resolve(ROOT, 'src/pages/index.astro');
+  if (existsSync(consumerLanding)) {
+    const astroConfigPath = resolve(ROOT, 'astro.config.mjs');
+    let landingDisabled = false;
+    if (existsSync(astroConfigPath)) {
+      const astroConfig = readFileSync(astroConfigPath, 'utf8');
+      landingDisabled = /\blanding\s*:\s*false\b/.test(astroConfig);
+    }
+    if (!landingDisabled) {
+      console.warn(
+        `\n⚠ Consumer-owned landing page at src/pages/index.astro shadows the\n` +
+        `  scaffold's auto-injected "/" route. Your page wins today, but Astro\n` +
+        `  has announced route collisions become a HARD ERROR in a future\n` +
+        `  version. Set 'routes: { landing: false }' in defineBookConfig to\n` +
+        `  declare the override and silence the collision.\n` +
+        `  See: package/recipes/18-chapter-route-ownership.md\n`,
+      );
+    }
+  }
+}
+
 const errors = [];
 const warnings = [];
 const fail = (file, line, msg) => errors.push({ file, line, msg });
@@ -353,6 +384,57 @@ for (const rel of chapterFiles) {
       );
     }
   }
+
+  // 9. Learning-objective anchor binding (#130). Convention (consumer-defined
+  //    `los` frontmatter, guides-ai-engineering): each `los[].anchor` slug has
+  //    a matching MDX comment marker in the prose binding the objective to its
+  //    section. Both drift directions built + validated green before this
+  //    check, so both fail loud: a declared anchor with no marker (dangling
+  //    objective) and a marker with no declaration (orphan). Scoped to
+  //    chapters that opt into the convention (a `los:` frontmatter key) —
+  //    `los` is not a scaffold schema field, so this can't false-fire on
+  //    books that don't use it. Heuristic, like #8: any indented `anchor:`
+  //    line inside the frontmatter counts as a declaration.
+  {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const front = fmMatch ? fmMatch[1] : '';
+    if (/^los\s*:/m.test(front)) {
+      const frontOffset = content.indexOf(front);
+      const bodyOffset = fmMatch ? fmMatch[0].length : 0;
+      const body = content.slice(bodyOffset);
+      // Matches both YAML styles: block items (`- anchor: slug` / `anchor: slug`
+      // on its own indented line) and flow/inline maps (`- { text: …, anchor:
+      // slug }`), where the key follows a `{` or `,`. The prefix alternation —
+      // never a bare `.*` — keeps `my-anchor:` from matching as "anchor:".
+      const declared = [
+        ...front.matchAll(
+          /^\s+(?:-\s+|.*[{,]\s*)?anchor\s*:\s*["']?([^"',}\n]+?)["']?\s*(?:[,}].*)?$/gm,
+        ),
+      ];
+      const markers = [...body.matchAll(/\{\s*\/\*\s*anchor:\s*([^\s*]+)\s*\*\/\s*\}/g)];
+      const markerSlugs = new Set(markers.map((m) => m[1]));
+      const declaredSlugs = new Set(declared.map((m) => m[1].trim()));
+      for (const d of declared) {
+        const slug = d[1].trim();
+        if (!markerSlugs.has(slug)) {
+          fail(
+            rel,
+            lineOf(content, frontOffset + d.index),
+            `los anchor "${slug}" has no matching {/* anchor: ${slug} */} marker in the prose — dangling learning objective.`,
+          );
+        }
+      }
+      for (const m of markers) {
+        if (!declaredSlugs.has(m[1])) {
+          fail(
+            rel,
+            lineOf(content, bodyOffset + m.index),
+            `prose anchor marker "${m[1]}" has no matching los[].anchor in the frontmatter — orphan anchor.`,
+          );
+        }
+      }
+    }
+  }
 }
 
 // ===== 8. Questions collection (#112): domain membership + unique ids =====