@brandon_m_behring/book-scaffold-astro 4.6.1 → 4.7.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.6.1",
+  "version": "4.7.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/09-validation.md

@@ -49,8 +49,25 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Environment variables
 
-- `BOOK_PROFILE` — `academic` enables Cite-key checking; otherwise skipped.
+- `BOOK_PRESET` (canonical) / `BOOK_PROFILE` (alias) — which preset to validate against. `academic` enables Cite-key checking.
 - `BOOK_REPO_ROOT` — absolute path to the paired code repo for CodeRef checks. Unset → skipped (the scaffold default; minimal/tools books rarely have a paired code repo).
+- `BOOK_CHAPTERS_DIR` — override the chapters directory (default: read from `content.config.ts`, fallback `src/content/chapters`).
+
+## Preset / chaptersBase resolution (v4.7.0+, #75)
+
+The validator resolves both `preset` and `chaptersBase` by consulting multiple sources in a documented order. Notable v4.7.0 addition: the v4.5+ canonical form
+
+```ts
+// src/content.config.ts
+export const { collections } = defineBookSchemas({
+  preset: 'research-portfolio',
+  chaptersBase: './src/content/textbook',
+});
+```
+
+is now read by the CLI (previously it was silently ignored — the CLI defaulted to `profile=minimal` and walked `./src/content/chapters/` while `astro build` applied the correct settings, masking real schema drift).
+
+Full precedence chain documented in [`PACKAGE_DESIGN.md §8 — Preset + chaptersBase resolution`](../../PACKAGE_DESIGN.md#preset--chaptersbase-resolution-v470-closes-75).
 
 ## Output
 

package/scripts/validate.mjs

@@ -28,7 +28,7 @@
 import { readFile, access } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
-import { walkMdx, readChaptersBase } from './walk-mdx.mjs';
+import { walkMdx, readChaptersBase, readBookSchemaConfig } from './walk-mdx.mjs';
 
 /**
  * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
@@ -105,17 +105,26 @@ const DATA_DIR = resolve(ROOT, 'src/data');
 
 // Preset resolution (matches resolvePreset in src/types.ts):
 //   --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
-//   .env BOOK_PRESET > .env BOOK_PROFILE > 'minimal'.
+//   .env BOOK_PRESET > .env BOOK_PROFILE >
+//   defineBookSchemas({ preset }) in content.config.ts >
+//   defineBookSchemas({ profile }) in content.config.ts (alias) >
+//   '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.
+// content.config.ts fallback closes #75 — without it, consumers using the
+// 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 schemaConfig = await readBookSchemaConfig(ROOT);
 const PRESET =
   presetFromFlag ??
   process.env.BOOK_PRESET ??
   process.env.BOOK_PROFILE ??
   dotenv.BOOK_PRESET ??
   dotenv.BOOK_PROFILE ??
+  schemaConfig.preset ??
   'minimal';
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;

package/scripts/walk-mdx.mjs

@@ -34,6 +34,79 @@ export async function* walkMdx(dir, baseDir = dir) {
   }
 }
 
+/**
+ * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
+ * `defineBookSchemas({ preset?, profile?, chaptersBase? })` options.
+ *
+ * v4.7.0 (closes #75): consumers using the v4.5+ canonical form
+ *
+ *   export const { collections } = defineBookSchemas({
+ *     preset: 'research-portfolio',
+ *     chaptersBase: './src/content/textbook',
+ *   });
+ *
+ * previously had BOTH options ignored by the CLI scripts. `validate` and
+ * `build-labels` resolved preset only from env vars and walked the default
+ * chapters dir, silently checking the wrong directory under the wrong
+ * profile while astro build applied the correct settings — a divergence
+ * masking real schema drift.
+ *
+ * Strategy: regex-parse the source file (avoid runtime import; the file
+ * imports from `astro:content` / `astro/loaders` which don't resolve in
+ * plain Node). Captures the entire `defineBookSchemas({ ... })` options
+ * object, then field-by-field regex within that scope for `preset:`,
+ * `profile:` (alias), and `chaptersBase:`.
+ *
+ * Returns `{ preset, chaptersBase }` — both nullable. Returns `null` for
+ * either field when:
+ *   - content.config.{ts,mjs,js} doesn't exist
+ *   - no `defineBookSchemas(...)` call found
+ *   - the field is absent or uses a dynamic form (variable, template literal)
+ *
+ * `preset` and `profile` are aliases (canonical name flipped in v3.7+);
+ * `preset` wins when both are present.
+ */
+export async function readBookSchemaConfig(projectRoot) {
+  const result = { preset: null, chaptersBase: null };
+  for (const ext of ['ts', 'mjs', 'js']) {
+    const configPath = join(projectRoot, `src/content.config.${ext}`);
+    if (!existsSync(configPath)) continue;
+    let source;
+    try {
+      source = await readFile(configPath, 'utf8');
+    } catch {
+      return result;
+    }
+    // Match `defineBookSchemas({ ... })` — capture the options object body.
+    // Non-greedy `[\s\S]*?` matches the smallest balanced-enough scope; for
+    // typical configs the options object is small (≤200 chars) and any
+    // nested braces (uncommon in this API) would terminate the match early.
+    // Acceptable trade-off: simple regex over a real parser.
+    const callMatch = source.match(
+      /\bdefineBookSchemas\s*\(\s*\{([\s\S]*?)\}\s*\)/,
+    );
+    if (callMatch) {
+      const optsBody = callMatch[1];
+      // preset is canonical (v3.7+); profile is backward-compat alias.
+      const presetMatch =
+        optsBody.match(/\bpreset\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bpreset\s*:\s*"([^"]+)"/);
+      const profileMatch =
+        optsBody.match(/\bprofile\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bprofile\s*:\s*"([^"]+)"/);
+      result.preset = presetMatch?.[1] ?? profileMatch?.[1] ?? null;
+      const chaptersBaseMatch =
+        optsBody.match(/\bchaptersBase\s*:\s*'([^']+)'/) ||
+        optsBody.match(/\bchaptersBase\s*:\s*"([^"]+)"/);
+      result.chaptersBase = chaptersBaseMatch?.[1] ?? null;
+    }
+    // First existing file wins (priority: .ts > .mjs > .js).
+    return result;
+  }
+  // No content.config.{ts,mjs,js} at all.
+  return result;
+}
+
 /**
  * Read the consumer's `content.config.ts` (or `.mjs` / `.js`) and extract
  * the `loader.base` path for the `chapters` content collection.
@@ -46,6 +119,9 @@ export async function* walkMdx(dir, baseDir = dir) {
  * consumer's config file and returns the actual base path so both scripts
  * discover the consumer's chapter files.
  *
+ * v4.7.0 (closes #75): when the raw Astro form isn't present, also consult
+ * `readBookSchemaConfig()` for `defineBookSchemas({ chaptersBase })`.
+ *
  * Strategy: regex-parse the source file (avoid runtime import; the file
  * imports from `astro:content` / `astro/loaders` which don't resolve in
  * plain Node). Matches both single- and double-quoted string literals;
@@ -55,6 +131,7 @@ export async function* walkMdx(dir, baseDir = dir) {
  * `${projectRoot}/src/content/chapters` when:
  *   - content.config.{ts,mjs,js} doesn't exist
  *   - the file exists but no `chapters` collection or `loader.base` found
+ *     AND no `defineBookSchemas({ chaptersBase: ... })` form found
  *   - the matched base path uses dynamic forms (variables, template literals)
  *     instead of a string literal
  *
@@ -91,6 +168,12 @@ export async function readChaptersBase(projectRoot) {
     if (captured) {
       return resolve(projectRoot, captured);
     }
+    // v4.7.0 (closes #75): no raw Astro form match — try the v4.5+ form
+    // `defineBookSchemas({ chaptersBase: '...' })`.
+    const schemaConfig = await readBookSchemaConfig(projectRoot);
+    if (schemaConfig.chaptersBase) {
+      return resolve(projectRoot, schemaConfig.chaptersBase);
+    }
     // File exists but no override found — assume the consumer uses the
     // scaffold's defineBookSchemas() default.
     return DEFAULT_BASE;