book-kit 0.0.0-stage → 0.6.0

package/toolchain.json

@@ -0,0 +1,42 @@
+{
+  "$comment": "Single source of truth for tool versions. pandoc and WeasyPrint drive print pagination: bumping either can reflow a locked page count (print.page_count), so bump deliberately (the same goes for the upstream font releases in `fonts`) and re-run every book's page-count check. tests/toolchain.test.js keeps requirements.txt, the Dockerfile, and the actions in sync with this file.",
+  "pandoc": "3.12.1",
+  "node": "24.21.0",
+  "just": "1.58.0",
+  "vale": "3.15.1",
+  "java": "21",
+  "epubcheck": {
+    "4.2.6": "3f73c1265cc92e3b53ffda6cd5bbeb58505b2b0c43411c26e74d8df1b193b2c0",
+    "5.3.0": "6c07e68584b2e2ce2f89fe06e1246dfead3eb36b46b340e7d93524f29dcff6c5"
+  },
+  "python": {
+    "weasyprint": "70.0",
+    "pikepdf": "10.10.0",
+    "Pillow": "12.3.0",
+    "python-docx": "1.2.0",
+    "fonttools": "4.67.0",
+    "brotli": "1.2.0"
+  },
+  "fonts": {
+    "source-serif": {
+      "url": "https://github.com/adobe-fonts/source-serif/releases/download/4.005R/source-serif-4.005_Desktop.zip",
+      "sha256": "549fdb8f9a682bd06944298621404969f6de77c2e422ff3b8244a1dcd6a0c425"
+    },
+    "source-sans-3": {
+      "url": "https://raw.githubusercontent.com/google/fonts/4591e3457ab8be6d70167aa6818922b91e78ab2d/ofl/sourcesans3/SourceSans3%5Bwght%5D.ttf",
+      "sha256": "042fe2cc0b933e328410d7acbd0aa6a1873dca5aef81875f4bc214b08825c7b9"
+    },
+    "source-sans-3-italic": {
+      "url": "https://raw.githubusercontent.com/google/fonts/4591e3457ab8be6d70167aa6818922b91e78ab2d/ofl/sourcesans3/SourceSans3-Italic%5Bwght%5D.ttf",
+      "sha256": "39e3ab05ccd7cb94907c31005bb5bec1d5432f0b096a2b782976e217a540eb6c"
+    },
+    "source-code-pro": {
+      "url": "https://raw.githubusercontent.com/google/fonts/b6ba0c72868dd42746f8a0a7dd12754663e55a0f/ofl/sourcecodepro/SourceCodePro%5Bwght%5D.ttf",
+      "sha256": "b400fc584e10aff25d0e775ce181b4fc1c5ea1b5dc37b81aeb2084375b945790"
+    },
+    "source-code-pro-italic": {
+      "url": "https://raw.githubusercontent.com/google/fonts/b6ba0c72868dd42746f8a0a7dd12754663e55a0f/ofl/sourcecodepro/SourceCodePro-Italic%5Bwght%5D.ttf",
+      "sha256": "6db77d25aa7b30eff449305b5c998e475694c74d398421127ea5a60f536413cd"
+    }
+  }
+}

package/validators/acronym-expansion.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import { GENERATED_FILES, UNIVERSALLY_KNOWN_ACRONYMS } from '../lib/validate.js';
+
+/**
+ * Validate that acronyms are expanded on first use in the book.
+ * Reads chapters in index.yml order and checks that each acronym's first
+ * occurrence includes a parenthetical expansion nearby.
+ *
+ * Accepted patterns:
+ *   - "Full Name ([ACRONYM]{.smallcaps})" — expansion before acronym
+ *   - "[ACRONYM]{.smallcaps} (Full Name)" — expansion after acronym
+ *
+ * @param {string[]} indexFiles - Files listed in index.yml (in order)
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateAcronymExpansion(indexFiles) {
+  const warnings = [];
+  // Track which acronyms we've seen and whether they were expanded
+  const seen = new Map(); // acronym -> { file, line, expanded }
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    if (GENERATED_FILES.has(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Find all [ACRONYM]{.smallcaps} occurrences on this line
+      const pattern = /\[([A-Z][A-Za-z0-9+/.]+)\]\{\.smallcaps\}/g;
+      let m;
+      while ((m = pattern.exec(line)) !== null) {
+        const acr = m[0]; // full match e.g. [TLS]{.smallcaps}
+        const acronym = m[1]; // just the letters e.g. TLS
+
+        if (seen.has(acronym)) continue; // already tracked first use
+
+        // Skip timezone offsets (UTC+1, UTC+5), date formats (YYYY-MM-DD),
+        // and degree abbreviations (J.D., M.B.A.) — these aren't expandable acronyms
+        if (/^UTC[+-]/.test(acronym)) continue;
+        if (/^[YMD]{2,}/.test(acronym)) continue;
+        if (/^[A-Z]\.[A-Z]\./.test(acronym)) continue;
+
+        // Check if there's an expansion nearby on this line
+        // Pattern 1: "Full Name ([ACRONYM]{.smallcaps})" — open paren before
+        const beforeAcr = line.slice(0, m.index);
+        const afterAcr = line.slice(m.index + acr.length);
+        // Allow trailing punctuation in the expansion (e.g. a title that ends
+        // in "?": "What Comes Next? ([WCN]{.smallcaps})").
+        const hasExpansionBefore = /\w+[?!.…]?\s*\($/.test(beforeAcr.trimEnd());
+
+        // Pattern 2: "[ACRONYM]{.smallcaps} (Full Name)" — open paren after
+        // Also handles plurals: "[ACRONYM]{.smallcaps}s (Full Name)"
+        const hasExpansionAfter = /^s?\s*\([A-Za-z]/.test(afterAcr);
+
+        // Pattern 3: Inline expansion near the acronym on the same line
+        // e.g., "denial-of-service attack...a [DoS]{.smallcaps} attack"
+        // or book title containing expansion text before the acronym
+        const hasInlineExpansion = false; // conservative: only parenthetical counts
+
+        const expanded = hasExpansionBefore || hasExpansionAfter || hasInlineExpansion;
+
+        seen.set(acronym, { file, line: i + 1, expanded });
+      }
+    }
+  }
+
+  // Report acronyms not expanded on first use (skip universally known ones)
+  for (const [acronym, info] of seen) {
+    if (UNIVERSALLY_KNOWN_ACRONYMS.includes(acronym)) continue;
+    if (!info.expanded) {
+      warnings.push(
+        `Acronym "${acronym}" not expanded on first use in ${info.file}:${info.line}`
+      );
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'acronym-expansion',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateAcronymExpansion(ctx.indexFiles),
+};

package/validators/bold-keywords.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that bold keywords (**Keyword.** Body / **Keyword:** Body) are not
+ * used outside of callout divs. Prefer H4 headings for accessibility.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateBoldKeywords(indexFiles) {
+  const warnings = [];
+  // Matches **Text.** or **Text:** at start of line followed by body text
+  const pattern = /^\*\*[^*]+[.:]\*\*\s+\S/;
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    let inCallout = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      if (line.startsWith('::: {.')) {
+        inCallout = true;
+        continue;
+      }
+      if (line === ':::') {
+        inCallout = false;
+        continue;
+      }
+
+      if (!inCallout && pattern.test(line)) {
+        const keyword = line.match(/^\*\*(.+?)[.:]\*\*/)?.[1] || '';
+        warnings.push(
+          `Bold keyword "${keyword}" should be an H4 heading in ${file}:${i + 1}`
+        );
+      }
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'bold-keywords',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateBoldKeywords(ctx.indexFiles),
+};

package/validators/callout-balance.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { callouts } from '../lib/callouts.js';
+import { TAKEAWAYS_SUFFIX, allowFor, optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // The name a warning uses for each callout class. A class not listed here
+  // uses its registry label without the trailing colon, or `.class` if it has
+  // no label.
+  names: {},
+};
+
+/**
+ * The callout pairs to check, from the registry's `pair_with` fields, in
+ * registry order: [[class, partner], ...]. A symmetric pair lists both
+ * entries, so each direction is checked.
+ * @param {Array<{class: string, pair_with?: string}>} [registry]
+ * @returns {Array<[string, string]>}
+ */
+export function calloutPairs(registry = callouts) {
+  return registry.filter((c) => c.pair_with).map((c) => [c.class, c.pair_with]);
+}
+
+/**
+ * Validate that chapters using a paired callout include its partner. Pairs
+ * come from `pair_with` in the callout registry; the business-nonfiction
+ * preset pairs .for-managers and .for-ics both ways, so a chapter with one
+ * should also have the other.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @param {{names?: Object<string, string>}} [options]
+ * @param {Set<string>} [allowed] - Files exempt from the check (validators.allow)
+ * @param {Array<{class: string, label?: string, pair_with?: string}>} [registry]
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateCalloutBalance(
+  indexFiles,
+  options = optionsFor('callout-balance', defaults),
+  allowed = allowFor('callout-balance'),
+  registry = callouts,
+) {
+  const warnings = [];
+  const pairs = calloutPairs(registry);
+  if (pairs.length === 0) return { errors: [], warnings };
+
+  const nameOf = (cls) =>
+    options.names?.[cls] ?? registry.find((c) => c.class === cls)?.label?.replace(/:$/, '') ?? `.${cls}`;
+
+  // Files that legitimately use only one side of a pair (validators.allow),
+  // e.g. a chapter that introduces each callout in its own section
+  const EXEMPT_FILES = [...allowed];
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    if (EXEMPT_FILES.includes(file)) continue;
+    if (file.includes(TAKEAWAYS_SUFFIX)) continue;
+
+    const content = fs.readFileSync(file, 'utf8');
+    for (const [cls, partner] of pairs) {
+      if (content.includes(`.${cls}`) && !content.includes(`.${partner}`)) {
+        warnings.push(
+          `${file} has "${nameOf(cls)}" callout but no "${nameOf(partner)}" callout`
+        );
+      }
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'callout-balance',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateCalloutBalance(ctx.indexFiles, ctx.options, ctx.allow, ctx.config.callouts),
+};

package/validators/callout-divs.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that Pandoc fenced divs (:::) are properly balanced.
+ * Every opening ::: {.class} must have a matching closing :::.
+ * Unclosed divs silently swallow content or break rendering.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateCalloutDivs(indexFiles) {
+  const errors = [];
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    // Stack of opening div line numbers
+    const divStack = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Track code blocks (fenced divs inside code are literal text)
+      if (/^```/.test(line.trim())) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Opening div: ::: {.class ...} or ::: {custom-style="..."}
+      if (/^:::\s*\{/.test(line.trim())) {
+        divStack.push(i + 1);
+        continue;
+      }
+
+      // Closing div: ::: alone on a line (possibly with trailing whitespace)
+      if (/^:::\s*$/.test(line.trim())) {
+        if (divStack.length === 0) {
+          errors.push(
+            `Unmatched closing ::: in ${file}:${i + 1} (no opening div)`
+          );
+        } else {
+          divStack.pop();
+        }
+        continue;
+      }
+    }
+
+    // Any remaining unclosed divs
+    for (const openLine of divStack) {
+      errors.push(
+        `Unclosed fenced div (:::) opened at ${file}:${openLine}`
+      );
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'callout-divs',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateCalloutDivs(ctx.indexFiles),
+};

package/validators/callout-labels.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import { callouts } from '../lib/callouts.js';
+
+/**
+ * Validate that labeled callouts (.for-managers / .for-ics / .pro-tip) don't
+ * start with a hardcoded label like "**For managers:**" or "**Pro tip:**". The
+ * label is injected by CSS (`.for-managers::before` / `.for-ics::before` /
+ * `.pro-tip::before` in src/style.css) for HTML/PDF and by add-div-titles.lua
+ * for EPUB, so a hardcoded label inside the callout renders twice
+ * ("💡 Pro-Tip: Pro tip: ...") in HTML and PDF.
+ * Mirrors the label strings checked by add-div-titles.lua.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateRoleCalloutLabels(indexFiles) {
+  const errors = [];
+
+  // Label patterns that duplicate the CSS ::before / Lua filter labels.
+  // Matches plain or bold ("**For managers:**", "**For managers**:") forms,
+  // including the smallcaps IC variant ("For [IC]{.smallcaps}s:").
+  const LABEL_PATTERNS = {
+    'for-managers': /^\*{0,2}For managers\*{0,2}\s*:/i,
+    'for-ics': /^\*{0,2}For (?:individual contributors|ICs|\[IC\]\{\.smallcaps\}s)\*{0,2}\s*:/i,
+    'pro-tip': /^\*{0,2}Pro[ -]?tip\*{0,2}\s*:/i,
+  };
+
+  // Human-readable label per callout class, for the error message.
+  const LABEL_NAMES = {
+    'for-managers': 'For managers:',
+    'for-ics': 'For individual contributors:',
+    'pro-tip': 'Pro tip:',
+  };
+
+  // Other labelled callouts from the registry match their own label text.
+  // (The TL;DR and common-objection labels are checked elsewhere or never
+  // typed by writers, as in the original rule set.)
+  const escapeRe = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  for (const c of callouts) {
+    if (!c.label || c.class in LABEL_PATTERNS || c.class === 'tldr' || c.class === 'common-objection') continue;
+    const bare = c.label.replace(/:$/, '');
+    LABEL_PATTERNS[c.class] = new RegExp(`^\\*{0,2}${escapeRe(bare)}\\*{0,2}\\s*:`, 'i');
+    LABEL_NAMES[c.class] = c.label;
+  }
+  const checked = Object.keys(LABEL_PATTERNS).filter((cls) => callouts.some((c) => c.class === cls));
+  if (checked.length === 0) return { errors, warnings: [] };
+  const LABELLED_OPEN_RE = new RegExp(`^:::\\s*\\{[^}]*\\.(${checked.map(escapeRe).join('|')})\\b`);
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    let pendingCallout = null; // { class, line } awaiting its first content line
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      if (/^```/.test(line)) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      const openMatch = line.match(LABELLED_OPEN_RE);
+      if (openMatch) {
+        pendingCallout = { class: openMatch[1], line: i + 1 };
+        continue;
+      }
+
+      if (!pendingCallout) continue;
+
+      // Skip blanks and comments between the opening fence and first content
+      if (line === '' || /^<!--/.test(line)) continue;
+
+      // Closing fence or another div before any content
+      if (/^:::/.test(line)) {
+        pendingCallout = null;
+        continue;
+      }
+
+      // First content line of the callout
+      if (LABEL_PATTERNS[pendingCallout.class].test(line)) {
+        const label = LABEL_NAMES[pendingCallout.class];
+        errors.push(
+          `Callout .${pendingCallout.class} in ${file}:${i + 1} starts with a hardcoded "${label}" label. ` +
+          `Remove it — the label is added automatically by CSS ::before (HTML/PDF) and ` +
+          `add-div-titles.lua (EPUB), so hardcoding it renders the label twice.`
+        );
+      }
+      pendingCallout = null;
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'callout-labels',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateRoleCalloutLabels(ctx.indexFiles),
+};

package/validators/chapter-lengths.js

@@ -0,0 +1,14 @@
+import { auditChapterLengths, MAX_WORDS, MIN_WORDS } from '../commands/audit-chapter-lengths.js';
+
+// Flags content chapters outside a recommended word count range. The audit
+// itself lives in commands/audit-chapter-lengths.js, which also runs on its
+// own (`book-kit audit-chapter-lengths`) with the same defaults.
+export default {
+  name: 'chapter-lengths',
+  tags: ['style'],
+  defaults: {
+    min_words: MIN_WORDS,
+    max_words: MAX_WORDS,
+  },
+  run: (ctx) => ({ errors: [], warnings: auditChapterLengths(undefined, ctx.options).warnings }),
+};

package/validators/chapter.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import { isNonChapter } from '../lib/structure.js';
+import { config, isExcluded, REQUIRED_CALLOUT } from '../lib/validate.js';
+
+/**
+ * Validate a chapter file
+ * @param {string} chapter - Path to chapter file
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateChapter(chapter, indexFiles) {
+  const errors = [];
+  const warnings = [];
+  
+  // Check if chapter is in index.yml
+  if (!indexFiles.includes(chapter)) {
+    errors.push(`Chapter not found in index.yml: ${chapter}`);
+  }
+  
+  // Read chapter contents
+  const contents = fs.readFileSync(chapter, 'utf8');
+  
+  // Check for TODO markers
+  if (contents.includes('TODO')) {
+    errors.push(`Chapter contains TODO: ${chapter}`);
+  }
+  
+  // Check for the required opening callout (TL;DR by default). Structural
+  // pages and takeaways collections aren't chapters, so they're exempt.
+  if (REQUIRED_CALLOUT && !isNonChapter(chapter, config) && !contents.includes(`.${REQUIRED_CALLOUT}`)) {
+    errors.push(`Chapter missing ${REQUIRED_CALLOUT === 'tldr' ? 'TL;DR' : `.${REQUIRED_CALLOUT} callout`}: ${chapter}`);
+  }
+  
+  return { errors, warnings };
+}
+
+// Runs validateChapter over every chapter under paths.src that isn't in
+// lint.exclude. The per-chapter results are concatenated into one, which
+// prints in the same order as reporting each chapter separately only because
+// validateChapter emits errors and never warnings; keep it that way, or report
+// per chapter again.
+export default {
+  name: 'chapter',
+  tags: ['structure'],
+  defaults: {},
+  run(ctx) {
+    const errors = [];
+    const warnings = [];
+    for (const chapter of ctx.chapters) {
+      if (isExcluded(chapter)) continue;
+      const result = validateChapter(chapter, ctx.indexFiles);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+    return { errors, warnings };
+  },
+};

package/validators/cross-references.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import { collectAllAnchors } from '../lib/validate.js';
+
+/**
+ * Validate that internal cross-references (#anchor) resolve to actual headings.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateCrossReferences(indexFiles) {
+  const warnings = [];
+  const anchors = collectAllAnchors(indexFiles);
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Skip code blocks
+      if (line.trim().startsWith('```')) continue;
+
+      // Find all internal cross-references: [text](#anchor)
+      const refPattern = /\]\(#([a-z][a-z0-9-]*)\)/g;
+      let match;
+      while ((match = refPattern.exec(line)) !== null) {
+        const anchor = match[1];
+        if (!anchors.has(anchor)) {
+          warnings.push(
+            `Broken cross-reference "#${anchor}" in ${file}:${i + 1}`
+          );
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'cross-references',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateCrossReferences(ctx.indexFiles),
+};

package/validators/doubled-words.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import { optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // Words that are legitimately repeated in English prose and must not be
+  // flagged as accidental doubling (e.g. "the fact that that happened").
+  // Matching ignores case.
+  allowlist: ['had', 'that'],
+};
+
+/**
+ * Validate that no word is accidentally repeated back-to-back ("the the",
+ * "and and") — a classic typo that survives spellcheck. Matches a run of
+ * letters immediately followed by the same run (case-insensitive), skipping a
+ * small allowlist of legitimate repeats (the `allowlist` option). Inline code,
+ * fenced code blocks, and YAML frontmatter are skipped.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @param {{allowlist?: string[]}} [options]
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateDoubledWords(indexFiles, options = optionsFor('doubled-words', defaults)) {
+  const errors = [];
+  const DOUBLED_WORD_ALLOWLIST = new Set((options.allowlist ?? []).map((w) => String(w).toLowerCase()));
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    let inFrontmatter = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (i === 0 && line.trim() === '---') {
+        inFrontmatter = true;
+        continue;
+      }
+      if (inFrontmatter && line.trim() === '---') {
+        inFrontmatter = false;
+        continue;
+      }
+      if (inFrontmatter) continue;
+
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Same letter-run twice in a row, separated only by spaces/tabs.
+      const doubled = /\b([A-Za-z]+)([ \t]+)\1\b/gi;
+      let m;
+      while ((m = doubled.exec(line)) !== null) {
+        if (DOUBLED_WORD_ALLOWLIST.has(m[1].toLowerCase())) continue;
+
+        // Skip if inside inline code (odd number of backticks before match)
+        const before = line.slice(0, m.index);
+        if ((before.match(/`/g) || []).length % 2 === 1) continue;
+
+        errors.push(
+          `Doubled word "${m[1]} ${m[1]}" in ${file}:${i + 1}: "...${line.slice(Math.max(0, m.index - 15), m.index + m[0].length + 15).trim()}..."`
+        );
+      }
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'doubled-words',
+  tags: ['structure'],
+  defaults,
+  run: (ctx) => validateDoubledWords(ctx.indexFiles, ctx.options),
+};

package/validators/duplicate-headings.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import { headingToAnchor } from '../lib/validate.js';
+
+/**
+ * Validate no duplicate H2 headings across production chapters.
+ * Duplicate H2 headings cause anchor ID collisions in the combined output.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateDuplicateHeadings(indexFiles) {
+  const warnings = [];
+  // Map anchor -> [files where it appears]
+  const anchorSources = new Map();
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+
+    for (const line of content.split('\n')) {
+      // Only check H2 headings (chapters)
+      if (/^##\s/.test(line)) {
+        const anchor = headingToAnchor(line);
+        if (!anchor) continue;
+
+        if (!anchorSources.has(anchor)) {
+          anchorSources.set(anchor, []);
+        }
+        anchorSources.get(anchor).push(file);
+      }
+    }
+  }
+
+  // "Key takeaways" is intentionally repeated across section key-takeaways files
+  const ALLOWED_DUPLICATES = ['key-takeaways'];
+
+  for (const [anchor, files] of anchorSources) {
+    if (files.length > 1 && !ALLOWED_DUPLICATES.includes(anchor)) {
+      warnings.push(
+        `Duplicate H2 anchor "#${anchor}" in: ${files.join(', ')}`
+      );
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'duplicate-headings',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateDuplicateHeadings(ctx.indexFiles),
+};