book-kit 0.0.0-stage → 0.6.0

package/validators/em-dashes.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that em-dashes are used instead of spaced hyphens.
+ * Detects patterns like "word - word" which should be "word—word" or "word — word".
+ * Skips code blocks, YAML frontmatter, and markdown list markers.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateEmDashes(indexFiles) {
+  const warnings = [];
+
+  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];
+
+      // Track YAML frontmatter
+      if (i === 0 && line.trim() === '---') {
+        inFrontmatter = true;
+        continue;
+      }
+      if (inFrontmatter && line.trim() === '---') {
+        inFrontmatter = false;
+        continue;
+      }
+      if (inFrontmatter) continue;
+
+      // Track code blocks
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Skip list markers (- item), horizontal rules (---), and table separators
+      if (/^\s*[-*+]\s/.test(line)) continue;
+      if (/^-{3,}$/.test(line.trim())) continue;
+      if (/^\|/.test(line.trim())) continue;
+
+      // Detect spaced hyphens: "word - word" (not "e.g. - " list continuation)
+      // Match: letter/closing-paren/quote, space(s), single hyphen, space(s), letter/opening-quote
+      const spacedHyphen = /(?<=[a-zA-Z)'""])\s+-\s+(?=[a-zA-Z('""])/g;
+      let m;
+      while ((m = spacedHyphen.exec(line)) !== null) {
+        // Skip if inside inline code
+        const before = line.slice(0, m.index);
+        if ((before.match(/`/g) || []).length % 2 === 1) continue;
+
+        // Skip if inside a URL
+        if (/https?:\/\/\S*$/.test(before)) continue;
+
+        warnings.push(
+          `Spaced hyphen (should be em-dash?) 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: 'em-dashes',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateEmDashes(ctx.indexFiles),
+};

package/validators/escaped-smallcaps.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that no smallcaps spans have escaped brackets.
+ * A backslash before the opening bracket (e.g., \[AM]{.smallcaps}) prevents
+ * pandoc from rendering the span, producing raw markup in the output.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateEscapedSmallcaps(indexFiles) {
+  const errors = [];
+  const pattern = /\\\[[^\]]*?\]\{\.smallcaps\}/g;
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(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;
+
+      let m;
+      while ((m = pattern.exec(line)) !== null) {
+        errors.push(
+          `Escaped smallcaps ${m[0]} in ${file}:${i + 1} — remove the backslash`
+        );
+      }
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'escaped-smallcaps',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateEscapedSmallcaps(ctx.indexFiles),
+};

package/validators/footnotes.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that footnote references and definitions match.
+ * Every [^label] reference must have a [^label]: definition, and vice versa.
+ * Mismatches break footnote rendering in PDF and EPUB.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateFootnotes(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;
+    const refs = new Map();  // label -> first line number
+    const defs = new Map();  // label -> line number
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (/^```/.test(line.trim())) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Footnote definitions: [^label]: at start of line
+      const defMatch = line.match(/^\[\^([^\]]+)\]:/);
+      if (defMatch) {
+        defs.set(defMatch[1], i + 1);
+      }
+
+      // Footnote references: [^label] not followed by :
+      // Must be careful not to match definitions
+      const refPattern = /\[\^([^\]]+)\](?!:)/g;
+      let m;
+      while ((m = refPattern.exec(line)) !== null) {
+        // Skip if this is actually a definition line (starts with [^)
+        if (/^\[\^/.test(line)) continue;
+
+        const label = m[1];
+        if (!refs.has(label)) {
+          refs.set(label, i + 1);
+        }
+      }
+    }
+
+    // Check for references without definitions
+    for (const [label, lineNum] of refs) {
+      if (!defs.has(label)) {
+        errors.push(
+          `Footnote reference [^${label}] without definition in ${file}:${lineNum}`
+        );
+      }
+    }
+
+    // Check for definitions without references (orphaned footnotes)
+    for (const [label, lineNum] of defs) {
+      if (!refs.has(label)) {
+        errors.push(
+          `Orphaned footnote definition [^${label}]: without reference in ${file}:${lineNum}`
+        );
+      }
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'footnotes',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateFootnotes(ctx.indexFiles),
+};

package/validators/heading-hierarchy.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+
+/**
+ * Validate heading hierarchy — no skipping levels (e.g., H2 → H4 without H3).
+ * Skipped heading levels break document outline and PDF/EPUB table of contents.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateHeadingHierarchy(indexFiles) {
+  const warnings = [];
+
+  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 prevLevel = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (/^```/.test(line.trim())) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      const headingMatch = line.match(/^(#{1,6})\s+/);
+      if (!headingMatch) continue;
+
+      const level = headingMatch[1].length;
+
+      // First heading in file sets the baseline
+      if (prevLevel === 0) {
+        prevLevel = level;
+        continue;
+      }
+
+      // Going deeper by more than one level is a hierarchy violation
+      if (level > prevLevel + 1) {
+        warnings.push(
+          `Heading hierarchy skip: H${prevLevel} → H${level} in ${file}:${i + 1}`
+        );
+      }
+
+      prevLevel = level;
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'heading-hierarchy',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateHeadingHierarchy(ctx.indexFiles),
+};

package/validators/hypothetical-hooks.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import { allowFor, optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // More openers to flag: regular-expression sources, matched case-insensitively
+  // against each paragraph line (anchor with ^ to match only at its start).
+  // The warning quotes the source.
+  extra_patterns: [],
+};
+
+// An extra_patterns entry as a case-insensitive RegExp, naming the config key
+// when the source doesn't parse.
+function compilePattern(source) {
+  try {
+    return new RegExp(source, 'i');
+  } catch (error) {
+    throw new Error(`validators.options.hypothetical-hooks.extra_patterns: ${error.message}`, { cause: error });
+  }
+}
+
+/**
+ * Validate that paragraphs don't start with formulaic hypothetical-scenario
+ * openers ("Picture this:", "Imagine...", etc.) that sound AI-generated.
+ * Reports warnings for any matches found.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @param {{extra_patterns?: string[]}} [options]
+ * @param {Set<string>} [allowed] - "file:line" openers exempt (validators.allow)
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateHypotheticalHooks(
+  indexFiles,
+  options = optionsFor('hypothetical-hooks', defaults),
+  allowed = allowFor('hypothetical-hooks'),
+) {
+  const warnings = [];
+  // Patterns that flag formulaic hypothetical openers
+  const patterns = [
+    { regex: /^Picture this:/i, label: 'Picture this:' },
+    { regex: /^Imagine\b/i, label: 'Imagine...' },
+    { regex: /^Consider a\b/i, label: 'Consider a...' },
+    { regex: /^Here'?s a scenario/i, label: "Here's a scenario..." },
+    { regex: /^Now picture\b/i, label: 'Now picture...' },
+    { regex: /^Let'?s say\b/i, label: "Let's say..." },
+    ...(options.extra_patterns ?? []).map((source) => ({ regex: compilePattern(source), label: source })),
+  ];
+
+  // Allowlist for intentional uses (analogies, non-workplace metaphors).
+  // To exempt a flagged opener, add its "src/chapter.md:line" (the paragraph
+  // start line the checker reports). Prune entries when chapters are renamed or
+  // removed so the set can't silently drift (cf. the RHETORICAL_ALLOWLIST).
+  const HOOK_ALLOWLIST = allowed;
+
+  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;
+      }
+
+      // Skip headings, blank lines, list items, and HTML comments
+      if (!line.trim() || line.startsWith('#') || line.startsWith('-') || line.startsWith('<!--')) continue;
+      if (inCallout) continue;
+
+      for (const { regex, label } of patterns) {
+        if (regex.test(line.trim())) {
+          const location = `${file}:${i + 1}`;
+          if (!HOOK_ALLOWLIST.has(location)) {
+            warnings.push(
+              `Formulaic hypothetical opener "${label}" in ${location} — rephrase to avoid AI-sounding hooks`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'hypothetical-hooks',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateHypotheticalHooks(ctx.indexFiles, ctx.options, ctx.allow),
+};

package/validators/index-integrity.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+
+/**
+ * Validate index.yml ↔ disk integrity: every file listed in index.yml must
+ * exist on disk. The reverse direction — an on-disk, non-excluded chapter that
+ * is missing from index.yml — is already caught by validateChapter, so between
+ * the two, both directions of the orphan check are covered.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateIndexIntegrity(indexFiles) {
+  const errors = [];
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) {
+      errors.push(
+        `index.yml lists a file that does not exist on disk: ${file}`
+      );
+    }
+  }
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'index-integrity',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateIndexIntegrity(ctx.indexFiles),
+};

package/validators/index.js

@@ -0,0 +1,73 @@
+// The kit's built-in validators, in run order. Each module's default export
+// has the same shape as a book's plugin: { name, tags, defaults, run(ctx) },
+// where run returns { errors, warnings }. `tags` is ['structure'] for the
+// neutral checks the kit defaults leave on, or ['style'] for the house-style
+// checks defaults/book.config.yml turns off.
+//
+// Order matters: it's the order findings print in. `chapter` runs first.
+
+import chapter from './chapter.js';
+import sectionIntros from './section-intros.js';
+import sectionIntroNoTldr from './section-intro-no-tldr.js';
+import sectionIntroHasLead from './section-intro-has-lead.js';
+import sectionIntroFinalLead from './section-intro-final-lead.js';
+import noTransitionTodos from './no-transition-todos.js';
+import noTodoMarkers from './no-todo-markers.js';
+import noBareUrlLinkText from './no-bare-url-link-text.js';
+import minOpenerLength from './min-opener-length.js';
+import chapterLengths from './chapter-lengths.js';
+import crossReferences from './cross-references.js';
+import indexIntegrity from './index-integrity.js';
+import smallcaps from './smallcaps.js';
+import escapedSmallcaps from './escaped-smallcaps.js';
+import calloutBalance from './callout-balance.js';
+import tldrLength from './tldr-length.js';
+import duplicateHeadings from './duplicate-headings.js';
+import acronymExpansion from './acronym-expansion.js';
+import emDashes from './em-dashes.js';
+import numberRangeDashes from './number-range-dashes.js';
+import quotePunctuation from './quote-punctuation.js';
+import doubledWords from './doubled-words.js';
+import calloutDivs from './callout-divs.js';
+import calloutLabels from './callout-labels.js';
+import footnotes from './footnotes.js';
+import headingHierarchy from './heading-hierarchy.js';
+import sentenceStarters from './sentence-starters.js';
+import listPunctuation from './list-punctuation.js';
+import boldKeywords from './bold-keywords.js';
+import hypotheticalHooks from './hypothetical-hooks.js';
+import paragraphLength from './paragraph-length.js';
+
+export const BUILTIN_VALIDATORS = [
+  chapter,
+  sectionIntros,
+  sectionIntroNoTldr,
+  sectionIntroHasLead,
+  sectionIntroFinalLead,
+  noTransitionTodos,
+  noTodoMarkers,
+  noBareUrlLinkText,
+  minOpenerLength,
+  chapterLengths,
+  crossReferences,
+  indexIntegrity,
+  smallcaps,
+  escapedSmallcaps,
+  calloutBalance,
+  tldrLength,
+  duplicateHeadings,
+  acronymExpansion,
+  emDashes,
+  numberRangeDashes,
+  quotePunctuation,
+  doubledWords,
+  calloutDivs,
+  calloutLabels,
+  footnotes,
+  headingHierarchy,
+  sentenceStarters,
+  listPunctuation,
+  boldKeywords,
+  hypotheticalHooks,
+  paragraphLength,
+];

package/validators/list-punctuation.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that bullet list items have consistent terminal punctuation.
+ * Within a single list, items should either all end with periods or all
+ * lack them — mixing looks unprofessional in print.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateListPunctuation(indexFiles) {
+  const warnings = [];
+
+  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 currentList = [];      // [{line, endsPeriod}]
+    let listStartLine = 0;
+    let inListContinuation = false;
+    let lastItemText;
+
+    const checkList = () => {
+      if (currentList.length < 2) {
+        currentList = [];
+        return;
+      }
+
+      const withPeriod = currentList.filter(item => item.endsPeriod).length;
+      const withoutPeriod = currentList.length - withPeriod;
+
+      // Only warn if there's a genuine mix (not all same)
+      // Exclude single-sentence continuation lists: where only the LAST item
+      // has a period (grammatically, these are one sentence broken across bullets)
+      if (withPeriod > 0 && withoutPeriod > 0) {
+        const lastHasPeriod = currentList[currentList.length - 1].endsPeriod;
+        const onlyLastHasPeriod = lastHasPeriod && withPeriod === 1;
+        if (!onlyLastHasPeriod) {
+          warnings.push(
+            `Inconsistent list punctuation in ${file}:${listStartLine} ` +
+            `(${withPeriod} items end with period, ${withoutPeriod} don't)`
+          );
+        }
+      }
+      currentList = [];
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (/^```/.test(line.trim())) {
+        inCodeBlock = !inCodeBlock;
+        checkList();
+        inListContinuation = false;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Detect bullet list items (- or * or + followed by space)
+      const bulletMatch = line.match(/^(\s*[-*+])\s+(.*)/);
+      if (bulletMatch) {
+        // If this is a new list (previous line wasn't a list item or continuation)
+        if (currentList.length === 0) {
+          listStartLine = i + 1;
+        }
+
+        lastItemText = bulletMatch[2].trim();
+        inListContinuation = true;
+
+        // Don't evaluate yet — item might continue on next line
+        currentList.push({ line: i + 1, endsPeriod: false, text: lastItemText });
+        continue;
+      }
+
+      // Continuation of a list item (indented text after a bullet)
+      if (inListContinuation && /^\s{2,}\S/.test(line)) {
+        lastItemText = line.trim();
+        // Update the last item's text
+        if (currentList.length > 0) {
+          currentList[currentList.length - 1].text = lastItemText;
+        }
+        continue;
+      }
+
+      // End of list (blank line or non-indented non-list text)
+      if (inListContinuation) {
+        // Finalize punctuation detection for all items
+        for (const item of currentList) {
+          const text = item.text;
+          // Check if text ends with sentence-ending punctuation (period, !, ?)
+          // Strip trailing markdown formatting (**, `, etc.) and quotes first
+          const cleaned = text.replace(/[*_`\]}\s"'"')\]]+$/, '');
+          item.endsPeriod = /[.!?]$/.test(cleaned);
+        }
+        checkList();
+        inListContinuation = false;
+      }
+
+      // Non-list content: reset
+      if (line.trim() === '' && !inListContinuation) {
+        continue;
+      }
+    }
+
+    // Finalize any remaining list
+    if (inListContinuation && currentList.length > 0) {
+      for (const item of currentList) {
+        const cleaned = item.text.replace(/[*_`\]}\s"'"')\]]+$/, '');
+        item.endsPeriod = /[.!?]$/.test(cleaned);
+      }
+      checkList();
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'list-punctuation',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateListPunctuation(ctx.indexFiles),
+};

package/validators/min-opener-length.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import { isNonChapter } from '../lib/structure.js';
+import { config, getIndexFiles, isExcluded, optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // Minimum words in the first two paragraphs after the TL;DR, combined.
+  min_words: 60,
+};
+
+/**
+ * Validate that every production chapter's opening (first two paragraphs
+ * after the TL;DR block, combined) is at least `min_words` (60) words. Short punchy
+ * hook-then-context patterns are fine — what we're guarding against is
+ * accidentally truncated or skeletal openers.
+ * @param {string[]} [chapters] - Files listed in index.yml (read from it by default)
+ * @param {{min_words?: number}} [options]
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateMinOpenerLength(chapters = getIndexFiles(), options = optionsFor('min-opener-length', defaults)) {
+  const errors = [];
+  const warnings = [];
+  const MIN_WORDS = options.min_words;
+
+  for (const file of chapters) {
+    if (!fs.existsSync(file)) continue;
+    if (isExcluded(file)) continue;
+    // Skip key-takeaway aggregator chapters (they're all-takeaways, no prose).
+    // Skip structural pages, takeaways collections, and drafts: not narrative.
+    if (isNonChapter(file, config)) continue;
+
+    const content = fs.readFileSync(file, 'utf8');
+    // Find the end of the TL;DR block (if any) and then the first two non-blank
+    // prose paragraphs after it.
+    const tldrEnd = content.search(/^:::\s*$/m);
+    let rest;
+    if (tldrEnd !== -1 && /:::\s*\{\.tldr/m.test(content.slice(0, tldrEnd))) {
+      rest = content.slice(tldrEnd).replace(/^:::\s*$/m, '').trimStart();
+    } else {
+      // No TL;DR: use the whole body below the first heading.
+      const afterHeading = content.replace(/^#+[^\n]*\n/m, '');
+      rest = afterHeading.trimStart();
+    }
+
+    const isProse = (t) => {
+      if (!t) return false;
+      if (/^#/.test(t)) return false;
+      if (/^:::/.test(t)) return false;
+      if (/^```/.test(t)) return false;
+      if (/^\|/.test(t)) return false;
+      if (/^[-*+]\s/.test(t)) return false;
+      // HTML linter-control comments (<!-- vale ... -->, <!-- textlint-... -->)
+      // sit between paragraphs but aren't prose — don't let them occupy an
+      // opener slot and crowd out the real hook.
+      if (/^<!--/.test(t)) return false;
+      // A leading blockquote is a valid hook device (e.g. a quoted email the
+      // chapter then reacts to), so it counts as opener content — see the word
+      // cleanup below, which strips the `>` markers before counting.
+      return true;
+    };
+
+    const paragraphs = rest.split(/\n{2,}/).map((p) => p.trim()).filter(isProse);
+    const opener = paragraphs.slice(0, 2).join(' ');
+    if (!opener) continue;
+
+    const words = opener
+      .replace(/\[[^\]]*\]\([^)]*\)/g, '$1') // strip link URLs
+      .replace(/^\s*>\s?/gm, '') // strip blockquote markers
+      .replace(/[*_`]/g, '')
+      .split(/\s+/)
+      .filter(Boolean);
+    if (words.length < MIN_WORDS) {
+      warnings.push(
+        `${file}: first two post-TL;DR paragraphs total only ${words.length} words ` +
+        `(minimum ${MIN_WORDS}). Chapter may have a truncated or skeletal opener.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'min-opener-length',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateMinOpenerLength(ctx.indexFiles, ctx.options),
+};