book-kit 0.0.0-stage → 0.6.0

package/validators/no-bare-url-link-text.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import { getIndexFiles } from '../lib/validate.js';
+
+/**
+ * Validate that link text is not a bare URL. Link text should describe the
+ * target; bare-URL link text hurts screen-reader users and print rendering.
+ * @param {string[]} [chapters] - Files listed in index.yml (read from it by default)
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateNoBareUrlLinkText(chapters = getIndexFiles()) {
+  const errors = [];
+  const warnings = [];
+  // [https://example.com](https://...) — text identical to URL.
+  const bareLinkRe = /\[(https?:\/\/[^\]]+)\]\(([^)]+)\)/g;
+
+  for (const file of chapters) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(bareLinkRe)) {
+        errors.push(
+          `${file}:${i + 1} uses a bare URL as link text: "${m[0]}". ` +
+          `Describe the link's target instead; screen readers read the URL aloud, and print turns it into a footnote anyway.`
+        );
+      }
+    });
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'no-bare-url-link-text',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateNoBareUrlLinkText(ctx.indexFiles),
+};

package/validators/no-todo-markers.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import { getIndexFiles } from '../lib/validate.js';
+
+/**
+ * Validate that no production chapter contains any unresolved TODO/FIXME/XXX
+ * markers. Broader guard than validateNoTransitionTodos; catches stray
+ * drafting notes before they ship.
+ * @param {string[]} [chapters] - Files listed in index.yml (read from it by default)
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateNoTodoMarkers(chapters = getIndexFiles()) {
+  const errors = [];
+  const warnings = [];
+  // Exempt the TRANSITION variant (handled by validateNoTransitionTodos) so
+  // the two validators produce one error per marker, not two.
+  const markerRe = /\b(TODO(?!:\s*TRANSITION)|FIXME|XXX)(:|\b)/i;
+
+  for (const file of chapters) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    lines.forEach((line, i) => {
+      // Skip code blocks and inline code (rough heuristic).
+      if (/^\s{4,}/.test(line)) return;
+      if (/^\s*```/.test(line)) return;
+      // Strip {.revision} spans: deliberate placeholders the build fills in
+      // (e.g. [TODO: number]{.revision}), not unfinished writing.
+      const stripped = line
+        .replace(/\[[^\]]*\]\{\.revision\b[^}]*\}/g, '')
+        .replace(/`[^`]*`/g, '');
+      const m = stripped.match(markerRe);
+      if (m) {
+        errors.push(
+          `${file}:${i + 1} contains unresolved "${m[1]}" marker: ` +
+          `${line.trim().slice(0, 120)}`
+        );
+      }
+    });
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'no-todo-markers',
+  tags: ['structure'],
+  defaults: {},
+  run: (ctx) => validateNoTodoMarkers(ctx.indexFiles),
+};

package/validators/no-transition-todos.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { getIndexFiles } from '../lib/validate.js';
+
+/**
+ * Validate that no production chapter contains a `TODO: TRANSITION` marker.
+ * A writer (or a drafting tool) leaves one where a transition between
+ * sections is still owed; it must be resolved before production builds.
+ * @param {string[]} [chapters] - Files listed in index.yml (read from it by default)
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateNoTransitionTodos(chapters = getIndexFiles()) {
+  const errors = [];
+  const warnings = [];
+
+  for (const file of chapters) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    if (/TODO:\s*TRANSITION/i.test(content)) {
+      errors.push(
+        `${file} contains an unresolved "TODO: TRANSITION" marker. ` +
+        `Write the transition, or remove the marker, before merging.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'no-transition-todos',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateNoTransitionTodos(ctx.indexFiles),
+};

package/validators/number-range-dashes.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+
+/**
+ * Validate that numeric ranges use an en dash (–), not a hyphen (CMOS 6.78):
+ * "9–5", "25–30", "50–60%", not "9-5". A hyphenated digit-hyphen-digit run in
+ * prose is almost always a range typed with the wrong dash.
+ *
+ * Matches a standalone `\d{1,4}-\d{1,4}` — the surrounding negative look-arounds
+ * (`[\w./-]`) exclude version numbers (`1.2-3`), ISBNs (`979-8-…`), slashed
+ * sequences, and hyphenated identifiers. Inline code, fenced code blocks, URLs,
+ * and YAML frontmatter are skipped. (Comma/`$`-bearing ranges like
+ * `$10,000-$15,000` are out of scope — the digit-hyphen-digit run is broken by
+ * the comma or symbol.)
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateNumberRangeDashes(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;
+    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;
+
+      const range = /(?<![\w./-])\d{1,4}-\d{1,4}(?![\w./-])/g;
+      let m;
+      while ((m = range.exec(line)) !== null) {
+        const before = line.slice(0, m.index);
+
+        // Skip if inside inline code (odd number of backticks before match)
+        if ((before.match(/`/g) || []).length % 2 === 1) continue;
+
+        // Skip if inside a URL
+        if (/https?:\/\/\S*$/.test(before)) continue;
+
+        errors.push(
+          `Number range should use an en dash (–), not a hyphen, 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: 'number-range-dashes',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateNumberRangeDashes(ctx.indexFiles),
+};

package/validators/paragraph-length.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import { extractParagraphs, isParagraphLengthExempt, MAX_PARAGRAPH_WORDS } from '../lib/paragraphs.js';
+import { GENERATED_FILES, allowFor, optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // Longest prose paragraph allowed, in words.
+  max_words: MAX_PARAGRAPH_WORDS,
+};
+
+/**
+ * Validate paragraph lengths for skim-ability.
+ *
+ * Long paragraphs are walls of text; skimmers (and readers with ADHD) bounce
+ * off them. Flags any prose paragraph — body text or callout text — over
+ * the `max_words` option (default MAX_PARAGRAPH_WORDS, 120, which flags only
+ * the longest few percent of paragraphs in typical prose). Generated key-takeaways chapters, front/back matter, and scratch
+ * files are exempt (see isParagraphLengthExempt in lib/paragraphs.js).
+ *
+ * @param {string[]} indexFiles - Chapter files from index.yml
+ * @param {{max_words?: number}} [options]
+ * @param {Set<string>} [allowed] - "file:line" paragraphs exempt (validators.allow)
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateParagraphLength(
+  indexFiles,
+  options = optionsFor('paragraph-length', defaults),
+  allowed = allowFor('paragraph-length'),
+) {
+  const errors = [];
+  const MAX_WORDS = options.max_words;
+
+  // Intentional exceptions — paragraphs that genuinely resist splitting
+  // (one sustained argument that weakens when broken). Keep this near-empty;
+  // splitting is almost always the right call.
+  // Format: "file:line" using the paragraph start line.
+  const PARAGRAPH_LENGTH_ALLOWLIST = allowed;
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    if (isParagraphLengthExempt(file)) continue;
+    if (GENERATED_FILES.has(file)) continue; // generated pages (lint.generated) aren't prose
+    const content = fs.readFileSync(file, 'utf8');
+
+    for (const paragraph of extractParagraphs(content)) {
+      if (paragraph.words <= MAX_WORDS) continue;
+      const location = `${file}:${paragraph.line}`;
+      if (PARAGRAPH_LENGTH_ALLOWLIST.has(location)) continue;
+      errors.push(
+        `Paragraph too long (${paragraph.words} words, max ${MAX_WORDS}) in ${location} — split it up for skim-ability`
+      );
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'paragraph-length',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateParagraphLength(ctx.indexFiles, ctx.options, ctx.allow),
+};

package/validators/quote-punctuation.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+
+/**
+ * Validate quote punctuation against two rules:
+ *
+ *   1. Periods and commas belong INSIDE the closing quote (US convention):
+ *      `left".` must read `left."` and `"fit",` must read `"fit,"`.
+ *      Flagged as: a *letter* + closing quote (straight " or curly ") + `.`/`,`.
+ *      Requiring a letter before the quote deliberately excludes inch/foot
+ *      measurements (`6".`, `0.75"`) — a digit, not a letter, precedes the quote.
+ *
+ *   2. No comma after a quoted question or exclamation (Chicago style):
+ *      `"…ready?", she asked` must read `"…ready?" she asked`.
+ *      Flagged as: `?` or `!` + closing quote + `,`.
+ *
+ * Inline code, fenced code blocks, and YAML frontmatter are skipped.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateQuotePunctuation(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;
+    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 fenced code blocks
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      const isInInlineCode = (index) =>
+        ((line.slice(0, index).match(/`/g) || []).length % 2) === 1;
+      const context = (index, len) =>
+        line.slice(Math.max(0, index - 15), index + len + 15).trim();
+
+      // Rule 1: letter, closing quote (straight or curly), then period/comma.
+      const leaked = /[A-Za-z]["”][.,]/g;
+      let m;
+      while ((m = leaked.exec(line)) !== null) {
+        if (isInInlineCode(m.index)) continue;
+        errors.push(
+          `Quote punctuation: period/comma belongs inside the closing quote in ${file}:${i + 1}: "...${context(m.index, m[0].length)}..."`
+        );
+      }
+
+      // Rule 2: comma after a quoted question/exclamation (drop it, Chicago style).
+      const questionComma = /[?!]["”],/g;
+      while ((m = questionComma.exec(line)) !== null) {
+        if (isInInlineCode(m.index)) continue;
+        errors.push(
+          `Quote punctuation: drop the comma after a quoted question/exclamation in ${file}:${i + 1}: "...${context(m.index, m[0].length)}..."`
+        );
+      }
+    }
+  }
+
+  return { errors, warnings: [] };
+}
+
+export default {
+  name: 'quote-punctuation',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateQuotePunctuation(ctx.indexFiles),
+};

package/validators/section-intro-final-lead.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import { getSectionIntros } from '../lib/validate.js';
+
+/**
+ * Validate that the final paragraph of each narrative section intro is inside
+ * a `.lead` fenced div, matching the lead styling of the rest of the intro.
+ * In HTML, `section.section-opener > p` already applies lead styling to direct
+ * paragraphs, but EPUB and DOCX rely on the explicit `.lead` div
+ * (`custom-style="lead"`), so a trailing plain paragraph renders as body text
+ * there while the surrounding intro renders as lead. Only the section-opener
+ * preamble (before the first H2) is checked.
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateSectionIntroFinalLead() {
+  const errors = [];
+  const warnings = [];
+  const intros = getSectionIntros();
+
+  for (const { section, file } of intros) {
+    const content = fs.readFileSync(file, 'utf8');
+    // Only check narrative section intros: those whose first heading is an H1.
+    // Front-matter files (copyright, dedication) and the back cover don't serve
+    // as narrative bridges between sections.
+    const firstHeading = content.split('\n').find((l) => /^#+\s/.test(l.trim()));
+    if (!firstHeading || !/^#\s/.test(firstHeading.trim())) continue;
+    if (section === 'Back cover') continue;
+
+    // Only check the section-opener preamble (before the first H2)
+    const h2Index = content.search(/^## /m);
+    const preamble = h2Index !== -1 ? content.slice(0, h2Index) : content;
+    const lines = preamble.split('\n');
+
+    // Walk the preamble tracking fenced divs to find the innermost div class
+    // (if any) containing the last content line.
+    let inCodeBlock = false;
+    const divStack = [];
+    let lastContentLine = null;
+    let lastContentDivClass = null;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      if (/^```/.test(line)) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Opening div: ::: {.class ...}
+      const openMatch = line.match(/^:::\s*\{[^}]*\.([\w-]+)/);
+      if (openMatch) {
+        divStack.push(openMatch[1]);
+        continue;
+      }
+      // Opening div without a class: ::: {custom-style="..."} or ::: {#id}
+      if (/^:::\s*\{/.test(line)) {
+        divStack.push(null);
+        continue;
+      }
+      // Closing div
+      if (/^:::\s*$/.test(line)) {
+        divStack.pop();
+        continue;
+      }
+
+      // Skip blanks, headings, and HTML comments
+      if (line === '' || /^#+\s/.test(line) || /^<!--/.test(line)) continue;
+
+      lastContentLine = i + 1;
+      lastContentDivClass = divStack.length > 0 ? divStack[divStack.length - 1] : null;
+    }
+
+    if (lastContentLine !== null && lastContentDivClass !== 'lead') {
+      errors.push(
+        `Section intro "${section}" in ${file}:${lastContentLine} ends with a paragraph outside a .lead div. ` +
+        `Wrap the final paragraph in ::: {.lead custom-style="lead"} so it matches the lead styling ` +
+        `of the rest of the section intro in EPUB and DOCX output.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'section-intro-final-lead',
+  tags: ['style'],
+  defaults: {},
+  run: () => validateSectionIntroFinalLead(),
+};

package/validators/section-intro-has-lead.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import { getSectionIntros } from '../lib/validate.js';
+
+/**
+ * Validate that section intro files use {.section-opener} on their H1 heading.
+ * The .section-opener class triggers page-level CSS that applies lead styling
+ * to all direct paragraphs and lists, replacing the need for individual .lead divs.
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateSectionIntroHasLead() {
+  const errors = [];
+  const warnings = [];
+  const intros = getSectionIntros();
+
+  for (const { section, file } of intros) {
+    const content = fs.readFileSync(file, 'utf8');
+    // Only check narrative section intros: those whose first heading is an H1.
+    // Front-matter files (copyright, dedication) and the back cover don't serve
+    // as narrative bridges between sections.
+    const firstHeading = content.split('\n').find((l) => /^#+\s/.test(l.trim()));
+    if (!firstHeading || !/^#\s/.test(firstHeading.trim())) continue;
+    if (section === 'Back cover') continue;
+
+    const hasSectionOpener = /^#\s.*\{[^}]*\.section-opener[^}]*\}/m.test(content);
+    if (!hasSectionOpener) {
+      errors.push(
+        `Section intro "${section}" in ${file} is missing {.section-opener} on its H1 heading. ` +
+        `Add {.section-opener} to the H1 for page-level lead styling.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'section-intro-has-lead',
+  tags: ['style'],
+  defaults: {},
+  run: () => validateSectionIntroHasLead(),
+};

package/validators/section-intro-no-tldr.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import { getSectionIntros } from '../lib/validate.js';
+
+/**
+ * Validate that section intro files do not contain TL;DR blocks in the section-opener
+ * portion (before the first H2). TL;DRs under H2 sub-chapters within the file are allowed.
+ * Section intros use {.section-opener} on their H1 instead of TL;DR blocks.
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateSectionIntroNoTldr() {
+  const errors = [];
+  const warnings = [];
+  const intros = getSectionIntros();
+
+  for (const { section, file } of intros) {
+    const content = fs.readFileSync(file, 'utf8');
+    // Only check the portion before the first H2 heading
+    const h2Index = content.search(/^## /m);
+    const preamble = h2Index !== -1 ? content.slice(0, h2Index) : content;
+    const hasTldr = /^:::\s*\{\.tldr\b/m.test(preamble);
+    if (hasTldr) {
+      errors.push(
+        `Section intro "${section}" in ${file} contains a TL;DR block in the section-opener preamble. ` +
+        `Section intros should use {.section-opener} on their H1, not .tldr blocks.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'section-intro-no-tldr',
+  tags: ['style'],
+  defaults: {},
+  run: () => validateSectionIntroNoTldr(),
+};

package/validators/section-intros.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import { getSectionIntros } from '../lib/validate.js';
+
+/**
+ * Validate that section intro files use H1 headings (not H2 or lower).
+ * Section intros must use # (H1) to appear as top-level entries in the PDF table of contents.
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ */
+export function validateSectionIntros() {
+  const errors = [];
+  const warnings = [];
+  const intros = getSectionIntros();
+
+  for (const { section, file } of intros) {
+    const firstLine = fs.readFileSync(file, 'utf8').split('\n')[0] || '';
+    const match = firstLine.match(/^(#+)\s/);
+    if (match && match[1].length > 1) {
+      errors.push(
+        `Section intro "${section}" in ${file} uses H${match[1].length} heading instead of H1. ` +
+        `Section intros must use # (H1) to appear in the PDF table of contents.`
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default {
+  name: 'section-intros',
+  tags: ['style'],
+  defaults: {},
+  run: () => validateSectionIntros(),
+};

package/validators/sentence-starters.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import { allowFor, optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // Consecutive sentences with the same first word that trigger a warning.
+  threshold: 3,
+};
+
+/**
+ * Validate sentence starter variety within paragraphs.
+ * Warns when `threshold` (3) or more consecutive sentences in a paragraph start with the same word.
+ * Repetitive openings make prose feel monotonous and AI-generated.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @param {{threshold?: number}} [options]
+ * @param {Set<string>} [allowed] - "file:line" paragraphs exempt (validators.allow)
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateSentenceStarters(
+  indexFiles,
+  options = optionsFor('sentence-starters', defaults),
+  allowed = allowFor('sentence-starters'),
+) {
+  const warnings = [];
+  const THRESHOLD = options.threshold; // consecutive sentences with same starter
+
+  // Intentional rhetorical patterns (parallel structure, escalation, question lists)
+  // Format: "file:line" using the paragraph start line reported by the checker
+  const RHETORICAL_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;
+    let paragraphLines = [];
+    let paragraphStartLine = 0;
+
+    const checkParagraph = () => {
+      if (paragraphLines.length === 0) return;
+      const text = paragraphLines.join(' ');
+
+      // Split into sentences (simple heuristic: period/!/? followed by space and uppercase)
+      const sentences = text.split(/(?<=[.!?])\s+(?=[A-Z"'*[])/).filter(s => s.trim());
+      if (sentences.length < THRESHOLD) return;
+
+      // Check for consecutive same-word starters
+      let streak = 1;
+      let prevStarter = '';
+      for (let i = 0; i < sentences.length; i++) {
+        // Extract first word (skip markdown formatting: **, *, [)
+        const starterMatch = sentences[i].match(/^[*_[\]]*([A-Za-z]+)/);
+        if (!starterMatch) {
+          streak = 1;
+          prevStarter = '';
+          continue;
+        }
+        const starter = starterMatch[1].toLowerCase();
+
+        if (starter === prevStarter && starter.length > 1) {
+          streak++;
+          if (streak >= THRESHOLD) {
+            const location = `${file}:${paragraphStartLine}`;
+            if (!RHETORICAL_ALLOWLIST.has(location)) {
+              warnings.push(
+                `${streak} consecutive sentences start with "${starterMatch[1]}" in ${location}`
+              );
+            }
+            break;
+          }
+        } else {
+          streak = 1;
+        }
+        prevStarter = starter;
+      }
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (/^```/.test(line.trim())) {
+        inCodeBlock = !inCodeBlock;
+        checkParagraph();
+        paragraphLines = [];
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      // Skip callout divs (their content is intentionally structured)
+      if (/^:::\s*\{/.test(line.trim())) {
+        checkParagraph();
+        paragraphLines = [];
+        inCallout = true;
+        continue;
+      }
+      if (/^:::\s*$/.test(line.trim())) {
+        inCallout = false;
+        paragraphLines = [];
+        continue;
+      }
+      if (inCallout) continue;
+
+      // Skip headings, list items, and blank lines
+      if (/^#{1,6}\s/.test(line) || /^\s*[-*+]\s/.test(line) || /^\s*\d+\.\s/.test(line)) {
+        checkParagraph();
+        paragraphLines = [];
+        continue;
+      }
+
+      if (line.trim() === '') {
+        checkParagraph();
+        paragraphLines = [];
+        continue;
+      }
+
+      if (paragraphLines.length === 0) {
+        paragraphStartLine = i + 1;
+      }
+      paragraphLines.push(line.trim());
+    }
+    checkParagraph();
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'sentence-starters',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateSentenceStarters(ctx.indexFiles, ctx.options, ctx.allow),
+};