book-kit 0.0.0-stage → 0.6.0

package/lib/validate.js

@@ -0,0 +1,202 @@
+// Helpers shared by the built-in validators (validators/) and the runner
+// (commands/validate.js).
+//
+// Validators read the book's conventions from book.config.yml. Paths (here,
+// in lint.exclude, and in validators.allow) are relative to the book root,
+// which is the working directory when run through `book-kit validate`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import * as yaml from 'js-yaml';
+import { deepMerge, loadConfig } from './config.js';
+import { smallcapsAcronyms, universalAcronyms } from './acronyms.js';
+
+export const config = loadConfig();
+const SRC_DIR = config.paths.src;
+const INDEX_PATH = config.paths.index;
+// How a chapter entry under paths.src starts in index.yml ("- src/").
+const SRC_ENTRY_PREFIX = `- ${path.normalize(SRC_DIR).replace(/\/+$/, '')}/`;
+export const TAKEAWAYS_SUFFIX = config.structure.takeaways_suffix;
+export const REQUIRED_CALLOUT = config.structure.required_callout;
+
+// Files to exclude from validation (index.yml presence, TODO checks, and the
+// required callout): lint.exclude in book.config.yml.
+export const EXCLUDE_PATTERNS = config.lint.exclude;
+
+// Machine-generated pages (lint.generated) whose text is derived from
+// already-validated sources. Skip prose-level lexical validators that would
+// misfire on them, e.g. acronyms locked inside link text that can't be
+// smallcapped. List them in lint.exclude too for the per-chapter checks.
+export const GENERATED_FILES = new Set(config.lint.generated);
+
+// Acronyms that should always use [ACRONYM]{.smallcaps} formatting: the kit's
+// list (lib/acronyms.js, shared with the no-bare-acronyms textlint rule) plus
+// lint.acronyms. The smallcaps validator only flags acronyms it knows about.
+export const KNOWN_ACRONYMS = smallcapsAcronyms(config);
+
+// Acronyms readers know without expansion on first use: the kit's list plus
+// lint.universal_acronyms.
+export const UNIVERSALLY_KNOWN_ACRONYMS = universalAcronyms(config);
+
+/**
+ * A validator's intentional exceptions (validators.allow.<name>).
+ * @param {string} name - Validator name
+ * @returns {Set<string>}
+ */
+export function allowFor(name) {
+  return new Set(config.validators.allow?.[name] ?? []);
+}
+
+/**
+ * A validator's options: its defaults deep-merged with
+ * validators.options.<name> (maps merge; lists and scalars replace).
+ * @param {string} name - Validator name
+ * @param {object} [defaults] - The validator's own defaults
+ * @param {object} [cfg] - Resolved config (the book's, by default)
+ * @returns {object}
+ */
+export function optionsFor(name, defaults = {}, cfg = config) {
+  return deepMerge(structuredClone(defaults), cfg.validators?.options?.[name] ?? {});
+}
+
+/**
+ * Get all markdown chapters from src directory
+ * @returns {string[]} Array of chapter paths
+ */
+export function getChapters() {
+  const srcDir = SRC_DIR;
+  if (!fs.existsSync(srcDir)) {
+    return [];
+  }
+  return fs.readdirSync(srcDir)
+    .filter(file => file.endsWith('.md'))
+    .sort()
+    .map(file => path.join(srcDir, file));
+}
+
+/**
+ * Load the index.yml file and get input-files
+ * @returns {string[]} Array of chapter paths from index
+ */
+export function getIndexFiles() {
+  const indexPath = INDEX_PATH;
+  if (!fs.existsSync(indexPath)) {
+    console.error('Error: index.yml not found');
+    process.exit(1);
+  }
+
+  const indexContent = fs.readFileSync(indexPath, 'utf8');
+  const index = yaml.load(indexContent);
+  return index['input-files'] || [];
+}
+
+/**
+ * Check if a chapter should be excluded from validation
+ * @param {string} chapter - Path to chapter file
+ * @returns {boolean} True if chapter should be excluded
+ */
+export function isExcluded(chapter) {
+  return EXCLUDE_PATTERNS.includes(chapter);
+}
+
+/**
+ * Parse index.yml to find section intro files (first heading file in each section).
+ * Sections are identified by YAML comment lines (# Section name).
+ * For each section, finds the first file whose content starts with a markdown heading.
+ * @returns {{section: string, file: string}[]} Array of section intro entries
+ */
+export function getSectionIntros() {
+  const indexPath = INDEX_PATH;
+  if (!fs.existsSync(indexPath)) {
+    return [];
+  }
+
+  const lines = fs.readFileSync(indexPath, 'utf8').split('\n');
+  const intros = [];
+  let currentSection = null;
+  let foundIntro = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Detect YAML comment section headers (e.g., "# Part one")
+    if (trimmed.startsWith('#') && !trimmed.startsWith('#-')) {
+      currentSection = trimmed.replace(/^#+\s*/, '');
+      foundIntro = false;
+      continue;
+    }
+
+    // Find the first file in the section whose content starts with a heading
+    if (currentSection && !foundIntro && trimmed.startsWith(SRC_ENTRY_PREFIX)) {
+      const file = trimmed.replace(/^-\s*/, '');
+      if (fs.existsSync(file)) {
+        const content = fs.readFileSync(file, 'utf8');
+        const linesInFile = content.split('\n');
+        const firstHeadingLine = linesInFile.find((l) => /^#+\s/.test(l.trim()));
+        if (firstHeadingLine) {
+          intros.push({ section: currentSection, file });
+          foundIntro = true;
+        }
+      }
+    }
+  }
+
+  return intros;
+}
+
+/**
+ * Generate a pandoc-style anchor ID from heading text.
+ * Strips smallcaps spans, explicit IDs, inline code, and converts to kebab-case.
+ * @param {string} headingText - Raw heading line (including ## prefix)
+ * @returns {string} The anchor ID
+ */
+export function headingToAnchor(headingText) {
+  let text = headingText.replace(/^#+\s*/, '');
+
+  // Use explicit anchor ID if present: {#my-id}
+  const explicitId = text.match(/\{#([a-z0-9-]+)\}/);
+  if (explicitId) return explicitId[1];
+
+  // Strip smallcaps spans: [ACRONYM]{.smallcaps} -> ACRONYM
+  text = text.replace(/\\?\[([^\]]*?)\\?\]\{\.smallcaps[^}]*\}/g, '$1');
+
+  // Strip other pandoc attributes: {epub:type=...} etc.
+  text = text.replace(/\{[^}]*\}/g, '');
+
+  // Strip inline code backticks
+  text = text.replace(/`([^`]*)`/g, '$1');
+
+  // Strip links: [text](url) -> text
+  text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+
+  // Strip bold/italic markers
+  text = text.replace(/[*_]+/g, '');
+
+  // Convert to pandoc-style ID
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')  // Remove non-word chars except spaces and hyphens
+    .replace(/\s+/g, '-')       // Spaces to hyphens
+    .replace(/-+/g, '-')        // Collapse multiple hyphens
+    .replace(/^-|-$/g, '');     // Trim leading/trailing hyphens
+}
+
+/**
+ * Collect all heading anchors from production chapters.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {Set<string>} Set of all anchor IDs
+ */
+export function collectAllAnchors(indexFiles) {
+  const anchors = new Set();
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    for (const line of content.split('\n')) {
+      if (/^#{1,6}\s/.test(line)) {
+        anchors.add(headingToAnchor(line));
+      }
+    }
+  }
+  return anchors;
+}

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "book-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Build and quality tooling for Markdown books: EPUB 3, Kindle, print-ready PDF and PDF/X-1a, HTML, and DOCX from one source, via pandoc, WeasyPrint, and Tailwind CSS.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benbalter/book-kit.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "book-kit": "bin/book-kit.js"
+  },
+  "exports": {
+    "./css/theme.css": "./css/theme.css",
+    "./css/theme/*": "./css/theme/*",
+    "./lib/*": "./lib/*",
+    "./presets/*": "./presets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "NOTICE.md",
+    "bin/",
+    "commands/",
+    "configs/",
+    "css/",
+    "defaults/",
+    "emoji/",
+    "filters/",
+    "fonts/*.md",
+    "fonts/recipe.json",
+    "just/",
+    "lib/",
+    "presets/",
+    "profiles/",
+    "requirements.txt",
+    "rules/",
+    "templates/",
+    "toolchain.json",
+    "validators/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint .",
+    "setup:python": "python3 -m pip install -r requirements.txt"
+  },
+  "dependencies": {
+    "@tailwindcss/cli": "^4.3.3",
+    "@tailwindcss/typography": "^0.5.20",
+    "@textlint-rule/textlint-rule-no-duplicate-abbr": "1.0.2",
+    "@textlint-rule/textlint-rule-no-unmatched-pair": "2.0.4",
+    "cssnano": "^9.1.0",
+    "js-yaml": "^5.4.1",
+    "markdownlint-cli2": "0.23.3",
+    "postcss": "^8.5.26",
+    "postcss-preset-env": "11.6.1",
+    "sharp": "^0.35.5",
+    "tailwindcss": "^4.3.3",
+    "textlint": "15.8.0",
+    "textlint-filter-rule-comments": "1.3.0",
+    "textlint-rule-abbr-within-parentheses": "1.0.2",
+    "textlint-rule-alex": "5.0.0",
+    "textlint-rule-common-misspellings": "1.0.1",
+    "textlint-rule-diacritics": "2.1.4",
+    "textlint-rule-doubled-spaces": "1.0.2",
+    "textlint-rule-en-capitalization": "2.0.3",
+    "textlint-rule-en-max-word-count": "2.0.1",
+    "textlint-rule-max-comma": "4.0.0",
+    "textlint-rule-no-start-duplicated-conjunction": "2.0.2",
+    "textlint-rule-sentence-length": "5.2.1",
+    "textlint-rule-stop-words": "5.2.0",
+    "textlint-rule-terminology": "5.2.16",
+    "textlint-rule-write-good": "2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "eslint": "10.13.0",
+    "globals": "17.13.0",
+    "vitest": "^5.0.2"
+  },
+  "overrides": {
+    "@tailwindcss/typography": {
+      "postcss-selector-parser": "^7.1.6"
+    },
+    "markdownlint-cli2": {
+      "smol-toml": "^1.9.0"
+    },
+    "micromark-extension-math": {
+      "katex": "^0.18.2"
+    }
+  }
+}

package/presets/business-nonfiction/CONVENTIONS.md

@@ -0,0 +1,35 @@
+## business-nonfiction house style
+
+These are the preset's conventions. `book-kit validate` and `just prose` enforce most of them; the rest are judgment calls for the writer and editor.
+
+### TL;DRs and takeaways
+
+- Every chapter opens with `::: {.tldr custom-style="tldr"}` right after its H2. It has one or two sentences that state the chapter's argument, not its topic.
+- Section `*-key-takeaways.md` chapters collect the TL;DRs. After adding or editing a TL;DR, or changing `index.yml`, run `just key-takeaways`.
+
+### Section openers
+
+- A section's first file is an H1 with `{.section-opener}`, followed by a short `.lead` paragraph. It has no TL;DR.
+
+### Role callouts
+
+- Use `.for-managers` and `.for-ics` only where the advice genuinely differs by role, and give a chapter that has one the other as well.
+- `.pro-tip` is for a concrete, actionable tip; `.common-objection` states a reader's pushback and answers it.
+
+### Mechanics
+
+- Acronyms: write them as `[API]{.smallcaps}`, and plurals as `[API]{.smallcaps}s`. Expand each one on first use, in book order.
+- Dashes: em dashes (`—`) with no spaces for asides; en dashes (`–`) for number ranges.
+- Quotes: periods and commas go inside quotation marks; colons and semicolons go outside. Use the serial comma.
+- Footnotes get chapter-specific names (`[^style-guide]`, not `[^1]`), since chapters build into one document.
+
+### Openings
+
+- The first paragraph after the TL;DR shows the problem in action, states a provocative truth, asks the reader's question, or grounds the chapter in a specific experience.
+- No throat-clearing ("In this chapter, we will explore…"), and no manufactured hypotheticals ("Picture this," "Imagine…," "Let's say…"). The hypothetical-hooks validator flags those.
+- If the TL;DR already makes the point, skip the hook and start with the substance.
+
+### Prose
+
+- The kit's prose rules flag clichés, buzzwords, vague intensifiers, cultural idioms, assumptive phrasing ("simply," "of course"), and AI-sounding patterns. Read each finding in context: quoted bad examples and deliberate repetition aren't errors.
+- Vary paragraph length and section shape. Bold-label bullet lists shouldn't stand in for an argument.

package/presets/business-nonfiction/preset.yml

@@ -0,0 +1,128 @@
+# business-nonfiction: the house style book-kit grew up with, for practical
+# nonfiction aimed at managers and individual contributors. A book opts in with
+#
+#   extends: business-nonfiction
+#
+# in book.config.yml. Keys here override the kit defaults; the book's own keys
+# override these. Every key is documented in defaults/book.config.yml.
+#
+# Through 0.3 this was the kit default. Extending it reproduces that default
+# exactly (tests/presets.test.js checks), so a book upgrading from 0.3 keeps
+# its output by adding the line above.
+
+# Six callouts: a TL;DR that opens every chapter, role-specific guidance for
+# managers and individual contributors, and section takeaways. The two role
+# callouts pair both ways: a chapter with one should have the other
+# (the callout-balance validator).
+callouts:
+  - class: tldr
+    label: "TL;DR:"
+    aria: Summary
+  - class: pro-tip
+    label: "Pro-Tip:"
+    aria: Pro tip
+    emoji: "💡"
+    emoji_cp: 1f4a1
+    emoji_alt: light bulb
+  - class: for-managers
+    label: "For managers:"
+    aria: Guidance for managers
+    pair_with: for-ics
+    emoji: "👔"
+    emoji_cp: 1f454
+    emoji_alt: necktie
+  - class: for-ics
+    label: "For individual contributors:"
+    aria: Guidance for individual contributors
+    pair_with: for-managers
+    emoji: "💻"
+    emoji_cp: 1f4bb
+    emoji_alt: laptop
+  - class: common-objection
+    label: "Common objection:"
+    aria: Common objection
+    emoji: "🤔"
+    emoji_cp: 1f914
+    emoji_alt: thinking
+  - class: takeaways
+    aria: Key takeaways
+
+structure:
+  # Every chapter opens with a TL;DR.
+  required_callout: tldr
+  # Each section ends with a generated chapter collecting its TL;DRs
+  # (`just key-takeaways`).
+  takeaways_suffix: -key-takeaways
+  takeaways_skip_sections: [Front matter, Appendix, Conclusion, Back cover]
+
+validators:
+  options:
+    # The short name callout-balance warnings use for .for-ics.
+    callout-balance:
+      names: { for-ics: For ICs }
+  # The house-style checks the kit defaults turn off, back on at each
+  # validator's own severity.
+  severity:
+    section-intros: "on"
+    section-intro-no-tldr: "on"
+    section-intro-has-lead: "on"
+    section-intro-final-lead: "on"
+    no-transition-todos: "on"
+    min-opener-length: "on"
+    chapter-lengths: "on"
+    smallcaps: "on"
+    escaped-smallcaps: "on"
+    callout-balance: "on"
+    tldr-length: "on"
+    acronym-expansion: "on"
+    em-dashes: "on"
+    number-range-dashes: "on"
+    quote-punctuation: "on"
+    sentence-starters: "on"
+    list-punctuation: "on"
+    bold-keywords: "on"
+    hypothetical-hooks: "on"
+    paragraph-length: "on"
+
+lint:
+  # Prose-style textlint settings on top of the kit's mechanical base.
+  textlint:
+    rules:
+      write-good:
+        passive: false
+        so: false
+        weasel: false
+        thereIs: true
+        tooWordy: false
+        adverb: false
+        cliches: true
+        eprime: false
+      terminology:
+        defaultTerms: false
+        exclude: [HTML, ID, URL, URLs]
+        terms: [[Github, GitHub], [Javascript, JavaScript], [Typescript, TypeScript], [e-mail, email], [on-line, online], [web site, website]]
+      sentence-length:
+        max: 350
+      en-max-word-count:
+        max: 80
+      stop-words:
+        defaultWords: false
+      # Inclusive-language checks, with words that are fine in business prose
+      # (and in this style's own advice) allowed.
+      alex:
+        allow: [actors-actresses, adult, adults, amateur, angry, attack, baby, ball, bigger, blind, bomb, burn, burns, buried, clearly, crack, cracks, dad-mom, damn, daughter-son, daughters-sons, dead, deposit, desire, destroys, devil, die, dirty, dive, doom, easy, enemy, everyone-knows, failed, failure, failures, faith, fear, fellowship, fight, fire, firing, gal-guy, god, hang, harder, he-she, her-him, hero-heroine, hijacking, hole, host-hostess, just, kids, kill, kills, lie, lies, master, master-key, newsman-newswoman, nuts, obvious, of-course, period, premature, radical, reject, remains, shoot, sick, simple, special, straightforward, suck, sucks, trap, traps, tribe]
+        profanitySureness: 2
+      max-comma:
+        max: 6
+  # All six of the kit's house-style textlint rules.
+  rules:
+    no-ai-like-patterns: true
+    no-assumptive: true
+    no-bare-acronyms: true
+    no-cliches: true
+    no-cultural-idioms: true
+    no-vague-intensifiers: true
+  markdownlint:
+    proper-names:
+      names: [GitHub, JavaScript, TypeScript, Markdown, README]
+      code_blocks: false

package/profiles/pdfx-def.ps

@@ -0,0 +1,42 @@
+%!PS-Adobe-3.0
+% PDF/X-1a:2001 output intent definition for Ghostscript
+%
+% This file defines the output intent metadata required by the PDF/X-1a:2001
+% standard. It references the USWebCoatedSWOP.icc CMYK ICC profile, which is
+% the standard profile for U.S. web offset printing.
+%
+% Used by: commands/convert-pdfx.sh via Ghostscript
+% See also: commands/download-icc-profile.sh for obtaining the ICC profile
+%
+% The pdfmark sequence follows Ghostscript's PDFX_def.ps example (see
+% NOTICE.md).
+%
+% The __ICC_PROFILE_PATH__ and __TITLE__ placeholders are replaced at runtime by
+% convert-pdfx.sh (the title is PostScript-escaped there).
+
+% Document info dictionary
+[ /GTS_PDFXVersion (PDF/X-1a:2001)
+  /Title (__TITLE__)
+  /Trapped /False
+/DOCINFO pdfmark
+
+% ICC profile path (placeholder substituted at build time)
+/ICCProfile (__ICC_PROFILE_PATH__) def
+
+% Create a stream object for the ICC profile
+[/_objdef {icc_PDFX} /type /stream /OBJ pdfmark
+[{icc_PDFX} << /N 4 >> /PUT pdfmark
+[{icc_PDFX} ICCProfile (r) file /PUT pdfmark
+
+% Output intent dictionary
+[/_objdef {OutputIntent_PDFX} /type /dict /OBJ pdfmark
+[{OutputIntent_PDFX} <<
+  /Type /OutputIntent
+  /S /GTS_PDFX
+  /OutputCondition (U.S. Web Coated \(SWOP\) v2)
+  /OutputConditionIdentifier (CGATS TR 001)
+  /RegistryName (http://www.color.org)
+  /Info (U.S. Web Coated \(SWOP\) v2)
+  /DestOutputProfile {icc_PDFX}
+>> /PUT pdfmark
+[{Catalog} << /OutputIntents [ {OutputIntent_PDFX} ] >> /PUT pdfmark

package/requirements.txt

@@ -0,0 +1,14 @@
+# Python build dependencies. Versions must match toolchain.json (the single
+# source of truth); tests/toolchain.test.js enforces it.
+#   weasyprint  - renders the print PDF (drives pagination: bump deliberately)
+#   pikepdf     - PDF/X-1a conversion (convert-pdfx)
+#   Pillow      - emoji compositing (composite-*-emoji)
+#   python-docx - DOCX reference template (generate-reference-docx)
+#   fonttools   - subsets the upstream fonts at build time (book-kit fonts)
+#   brotli      - WOFF2 compression for fonttools
+weasyprint==70.0
+pikepdf==10.10.0
+Pillow==12.3.0
+python-docx==1.2.0
+fonttools==4.67.0
+brotli==1.2.0