book-kit 0.0.0-stage → 0.6.0

package/lib/is-main.js

@@ -0,0 +1,21 @@
+// True when the module at `metaUrl` is the script node was asked to run, as
+// opposed to being imported (by another command or a test).
+//
+// Commands used to compare process.argv[1] with fileURLToPath(import.meta.url)
+// directly. Node reports import.meta.url as the real path, but argv[1] as the
+// path it was given, so through a symlinked node_modules (npm link, pnpm, a
+// worktree sharing another checkout's install) the two differ and the command
+// silently did nothing. Compare real paths instead.
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function isMain(metaUrl) {
+  const script = process.argv[1];
+  if (!script) return false;
+  try {
+    return realpathSync(script) === realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    return false;
+  }
+}

package/lib/lint.js

@@ -0,0 +1,148 @@
+// Resolved lint configs for a book: the kit's base configs, layered with the
+// presets' and the book's settings, the same way book.config.yml is.
+//
+//   textlint      configs/textlintrc.json, deep-merged with lint.textlint
+//   kit rules     rules/*.js and each preset's rules/*.js, switched on and
+//                 configured by lint.rules (name -> true | false | options)
+//   markdownlint  configs/markdownlint-cli2.jsonc's `config`, deep-merged
+//                 with lint.markdownlint
+//
+// textlint gives rules loaded with --rulesdir no config at all (they can't
+// be switched off or given options), and only rules named by package or path
+// in a textlintrc get options. So the build writes one rules directory per
+// book holding a small wrapper for each enabled rule, named like the rule and
+// with its options baked in, and points --rulesdir at that.
+//
+// A book with its own .textlintrc or .markdownlint-cli2.jsonc uses that file
+// as is (and, for textlint, every kit rule), as before presets existed.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { deepMerge, kitPath, pathFor } from './config.js';
+
+const BOOK_TEXTLINTRC = '.textlintrc';
+const BOOK_MARKDOWNLINT = '.markdownlint-cli2.jsonc';
+
+const ruleFiles = (dir) =>
+  existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.js')).sort().map((f) => join(dir, f)) : [];
+
+const ruleName = (file) => basename(file, '.js');
+
+// Our own JSONC files only use whole-line // comments.
+function readJsonc(file) {
+  return JSON.parse(readFileSync(file, 'utf8').replace(/^\s*\/\/.*$/gm, ''));
+}
+
+/**
+ * The textlint rules a book enables, in name order: [{ name, file, options }].
+ * Kit rules are on only when lint.rules turns them on; a preset's rules are
+ * on unless lint.rules turns them off.
+ * @param {object} config - Resolved config
+ */
+export function enabledRules(config) {
+  const settings = config.lint?.rules ?? {};
+  const candidates = [
+    ...ruleFiles(kitPath('rules')).map((file) => ({ file, on: Boolean(settings[ruleName(file)]) })),
+    ...(config.presets ?? []).flatMap(({ dir }) =>
+      ruleFiles(join(dir, 'rules')).map((file) => ({ file, on: settings[ruleName(file)] !== false })),
+    ),
+  ];
+  const byName = new Map();
+  for (const { file, on } of candidates) byName.set(ruleName(file), { file, on }); // later layers win
+  return [...byName.entries()]
+    .filter(([, { on }]) => on)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([name, { file }]) => {
+      const setting = settings[name];
+      const options = setting && typeof setting === 'object' ? setting : {};
+      return { name, file, options };
+    });
+}
+
+/**
+ * Whether command-line arguments for textlint or markdownlint name what to
+ * lint. Options and their values pass through untouched, so a value like
+ * `--format json` or a formatter's .js path isn't taken for a file: an
+ * argument names files only when it ends in .md, is a glob, or is a directory.
+ * @param {string[]} args
+ * @param {string} cwd - Where relative paths resolve (the book root)
+ */
+export function namesFiles(args, cwd) {
+  return args.some((arg) => {
+    if (arg.startsWith('-')) return false;
+    if (arg.endsWith('.md') || arg.includes('*')) return true;
+    try {
+      return statSync(join(cwd, arg)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** The textlintrc a book gets: the kit base merged with lint.textlint. */
+export function textlintConfig(config) {
+  return deepMerge(readJsonc(kitPath('configs', 'textlintrc.json')), config.lint?.textlint ?? {});
+}
+
+/** The markdownlint-cli2 config a book gets: the kit base merged with lint.markdownlint. */
+// Drafts (structure.draft_suffix) aren't linted.
+export function markdownlintConfig(config) {
+  const base = readJsonc(kitPath('configs', 'markdownlint-cli2.jsonc'));
+  const drafts = `**/*${config.structure?.draft_suffix ?? '-scratch'}.md`;
+  return {
+    ...base,
+    config: deepMerge(base.config, config.lint?.markdownlint ?? {}),
+    ignores: [drafts, ...(base.ignores ?? [])],
+  };
+}
+
+function wrapperSource({ name, file, options }) {
+  return `// Generated by book-kit for the book's textlint run (lib/lint.js): the
+// ${name} rule with its lint.rules options. Edit book.config.yml, not this file.
+import rule from ${JSON.stringify(file)};
+
+const options = ${JSON.stringify(options)};
+const withOptions = (reporter) => reporter && ((context, own = {}) => reporter(context, { ...options, ...own }));
+
+export default typeof rule === 'function'
+  ? withOptions(rule)
+  : { ...rule, linter: withOptions(rule.linter), fixer: withOptions(rule.fixer) };
+`;
+}
+
+/**
+ * Write the book's textlint config and rules directory under
+ * dist/.book-kit/textlint/, or point at the book's own .textlintrc.
+ * @param {object} config - Resolved config
+ * @returns {{ config: string, rulesdir: string }} paths for --config and --rulesdir
+ */
+export function prepareTextlint(config) {
+  const own = join(config.root, BOOK_TEXTLINTRC);
+  if (existsSync(own)) return { config: own, rulesdir: kitPath('rules') };
+
+  const dir = join(pathFor('dist', config), '.book-kit', 'textlint');
+  const rulesdir = join(dir, 'rules');
+  rmSync(rulesdir, { recursive: true, force: true }); // drop rules the book has since turned off
+  mkdirSync(rulesdir, { recursive: true });
+  // The wrappers are ES modules, whatever the book's own package.json says.
+  writeFileSync(join(dir, 'package.json'), '{ "type": "module" }\n');
+  for (const rule of enabledRules(config)) writeFileSync(join(rulesdir, `${rule.name}.js`), wrapperSource(rule));
+  const out = join(dir, 'textlintrc.json');
+  writeFileSync(out, `${JSON.stringify(textlintConfig(config), null, 2)}\n`);
+  return { config: out, rulesdir };
+}
+
+/**
+ * Write the book's markdownlint-cli2 config, or point at the book's own.
+ * @param {object} config - Resolved config
+ * @returns {string} path for markdownlint-cli2 --config
+ */
+export function prepareMarkdownlint(config) {
+  const own = join(config.root, BOOK_MARKDOWNLINT);
+  if (existsSync(own)) return own;
+  const dir = join(pathFor('dist', config), '.book-kit');
+  mkdirSync(dir, { recursive: true });
+  const out = join(dir, 'markdownlint-cli2.jsonc');
+  writeFileSync(out, `${JSON.stringify(markdownlintConfig(config), null, 2)}\n`);
+  return out;
+}

package/lib/pandoc.js

@@ -0,0 +1,148 @@
+// Generates dist/.book-kit/pandoc-<format>.yml: the per-book half of the pandoc
+// defaults (identity metadata, resource paths, cover), derived from
+// book.config.yml. Recipes pass it after the kit's identity-free defaults in
+// defaults/, so pandoc's metadata merge lets it win.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as yaml from 'js-yaml';
+import { kitPath, loadConfig, pathFor } from './config.js';
+import { revision } from './revision.js';
+
+export const FORMATS = ['html', 'pdf', 'epub', 'kindle', 'docx'];
+
+/**
+ * A filter or template a book names in build.filters / build.templates. A
+ * path (containing "/" or starting with ".") is book-relative; a bare name is
+ * looked up in the presets' <kind>/ directories, last preset first, then the
+ * kit's.
+ * @param {string} spec - e.g. "revision", "template.html", "./filters/mine.lua"
+ * @param {'filters'|'templates'} kind
+ * @param {string} ext - appended to a bare name that lacks it ('.lua' for filters)
+ */
+export function resolveAsset(spec, kind, ext, config) {
+  if (spec.includes('/') || spec.startsWith('.')) return join(config.root, spec);
+  const file = spec.endsWith(ext) ? spec : `${spec}${ext}`;
+  for (const { dir } of [...(config.presets ?? [])].reverse()) {
+    const candidate = join(dir, kind, file);
+    if (existsSync(candidate)) return candidate;
+  }
+  const kit = kitPath(kind, file);
+  if (!existsSync(kit)) {
+    throw new Error(`build.${kind}: no ${kind.slice(0, -1)} named "${spec}" in the kit or a preset (use ./path for one in the book)`);
+  }
+  return kit;
+}
+
+// The Lua filter chain for a format: build.filters.<format>, in order, with
+// the literal entry "extra_filters" standing for build.extra_filters.<format>
+// (book-relative paths).
+function filtersFor(format, config) {
+  const extra = (config.build.extra_filters?.[format] ?? []).map((f) => join(config.root, f));
+  return (config.build.filters?.[format] ?? []).flatMap((spec) =>
+    spec === 'extra_filters' ? extra : [resolveAsset(spec, 'filters', '.lua', config)],
+  );
+}
+
+function buildDate() {
+  const epoch = Number(process.env.SOURCE_DATE_EPOCH);
+  return (Number.isFinite(epoch) && epoch > 0 ? new Date(epoch * 1000) : new Date()).toISOString().slice(0, 10);
+}
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// Dublin Core supplement for the OPF, for books without a hand-written
+// epub.xml. metadata.uuid must stay constant across every revision of the book.
+export function epubMetadataXml(config = loadConfig()) {
+  const m = config.metadata;
+  if (!m.uuid) {
+    throw new Error('metadata.uuid is required to generate EPUB metadata (any UUID; never change it). Try: node -e "console.log(crypto.randomUUID())"');
+  }
+  const lines = [`<dc:identifier id="epub-id">urn:uuid:${xml(m.uuid)}</dc:identifier>`];
+  if (m.isbn_ebook) lines.push(`<dc:identifier id="isbn-ebook">urn:isbn:${xml(m.isbn_ebook)}</dc:identifier>`);
+  // Always emit a date: without one, pandoc derives dc:date from the `date`
+  // metadata (the build stamp, not a date) and writes an empty element, which
+  // fails EPUBCheck. Unpublished books get the build date (SOURCE_DATE_EPOCH
+  // when set, for reproducible builds).
+  lines.push(`<dc:date>${xml(m.pub_date || buildDate())}</dc:date>`);
+  if (m.publisher) lines.push(`<dc:publisher>${xml(m.publisher)}</dc:publisher>`);
+  for (const subject of m.subjects ?? []) lines.push(`<dc:subject>${xml(subject)}</dc:subject>`);
+  return `${lines.join('\n')}\n`;
+}
+
+const isEmpty = (v) => v == null || v === '' || (Array.isArray(v) && v.length === 0);
+
+function compact(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => !isEmpty(v)));
+}
+
+export function pandocDefaults(format, config = loadConfig()) {
+  if (!FORMATS.includes(format)) throw new Error(`Unknown format "${format}" (expected ${FORMATS.join(', ')})`);
+  const m = config.metadata;
+  const ebook = format === 'epub' || format === 'kindle';
+
+  const metadata = compact({
+    title: m.title,
+    subtitle: m.subtitle,
+    description: format === 'docx' ? undefined : m.description,
+    author: [].concat(m.author ?? []),
+    lang: m.lang,
+    date: revision(config),
+    rights: format === 'docx' ? undefined : m.rights,
+    // The print ISBN identifies the PDF/HTML; the ebook ISBN goes in the OPF
+    // via paths.epub_metadata (dc:identifier), not here.
+    isbn: format === 'html' || format === 'pdf' ? m.isbn_paperback : undefined,
+  });
+
+  // Point at the compiled stylesheet in dist/ explicitly, so pandoc never picks
+  // up the uncompiled Tailwind source through the resource path.
+  const STYLESHEETS = { html: 'style.css', pdf: 'style.css', epub: 'style-epub.css', kindle: 'style-kindle.css' };
+  if (STYLESHEETS[format]) metadata.css = join(config.paths.dist, STYLESHEETS[format]);
+
+  if (ebook) {
+    const a = config.accessibility;
+    Object.assign(metadata, compact({
+      'cover-label': config.strings?.cover_label,
+      accessModes: a.access_modes,
+      accessModeSufficient: a.access_mode_sufficient,
+      accessibilityFeatures: a.features,
+      accessibilityHazards: a.hazards,
+      accessibilitySummary: a.summary,
+      conformsTo: a.conforms_to,
+    }));
+  }
+  Object.assign(metadata, config.pandoc_metadata);
+
+  const out = {
+    metadata,
+    'resource-path': ['.', config.paths.fonts, config.paths.src],
+    filters: filtersFor(format, config),
+  };
+  const template = config.build.templates?.[format];
+  if (template) out.template = resolveAsset(template, 'templates', '', config);
+  if (ebook) out['epub-metadata'] = epubMetadataPath(config);
+  if (format !== 'docx' && existsSync(pathFor('cover', config))) {
+    out['epub-cover-image'] = config.paths.cover;
+  }
+  if (format === 'docx' && existsSync(join(config.root, 'reference.docx'))) {
+    out['reference-doc'] = 'reference.docx';
+  }
+  return out;
+}
+
+// The book's epub.xml if it has one, else one generated from config.
+function epubMetadataPath(config) {
+  const own = pathFor('epub_metadata', config);
+  if (existsSync(own)) return own;
+  const out = join(pathFor('dist', config), '.book-kit', 'epub.xml');
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, epubMetadataXml(config));
+  return out;
+}
+
+export function writePandocDefaults(format, config = loadConfig()) {
+  const out = join(pathFor('dist', config), '.book-kit', `pandoc-${format}.yml`);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, yaml.dump(pandocDefaults(format, config), { lineWidth: -1 }));
+  return out;
+}

package/lib/paragraphs.js

@@ -0,0 +1,173 @@
+/**
+ * Shared paragraph extraction for prose-length analysis.
+ *
+ * Splits a chapter's Markdown into prose paragraphs (body text and callout
+ * text), skipping code blocks, headings, list items, blockquotes, tables,
+ * and footnote definitions. Used by the paragraph-length validator
+ * (validators/paragraph-length.js); keep any other paragraph analysis on this
+ * one implementation so thresholds and reports always agree.
+ */
+
+/**
+ * Maximum words per paragraph before it's flagged as a skim-ability problem.
+ * Fixed rather than recomputed from the book (which would make it a moving
+ * target), and high enough to flag only the longest few percent of paragraphs
+ * in typical nonfiction prose. Tune it with validators.options.paragraph-length.
+ */
+import { isNonChapter } from './structure.js';
+
+const MAX_PARAGRAPH_WORDS = 120;
+
+/**
+ * Strip inline Markdown/Pandoc markup from a paragraph, preserving visible
+ * text. Heuristic, not a parser — sufficient for word/character counting.
+ * @param {string} text - Single paragraph of Markdown
+ * @returns {string} Plaintext-ish content
+ */
+function stripInlineMarkup(text) {
+  let stripped = text;
+
+  // Inline code: collapse to a single-word placeholder so `git commit -m "…"`
+  // counts as one token, not five
+  stripped = stripped.replace(/`[^`]*`/g, 'code');
+
+  // Images: keep alt text, drop URLs
+  stripped = stripped.replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1 ');
+
+  // Links: keep link text, drop URLs
+  stripped = stripped.replace(/\[([^\]]*)\]\([^)]+\)/g, '$1 ');
+
+  // Pandoc inline spans, e.g. [API]{.smallcaps}: keep the text
+  stripped = stripped.replace(/\[([^\]]*)\]\{[^}]*\}/g, '$1');
+
+  // Footnote references: not visible prose
+  stripped = stripped.replace(/\[\^[^\]]+\]/g, '');
+
+  // Emphasis and strong emphasis markers (*, _, **, __)
+  stripped = stripped.replace(/(\*\*|__)(.*?)\1/g, '$2');
+  stripped = stripped.replace(/(\*|_)(.*?)\1/g, '$2');
+
+  // Collapse whitespace
+  stripped = stripped.replace(/\s+/g, ' ').trim();
+
+  return stripped;
+}
+
+/**
+ * Extract prose paragraphs from chapter Markdown.
+ *
+ * A paragraph is a run of consecutive non-blank prose lines. Boundaries:
+ * blank lines, headings, list items, blockquotes, tables, footnote
+ * definitions, HTML comments, and fenced div markers (:::). Fenced code
+ * blocks are skipped entirely. Paragraphs inside fenced divs (callouts:
+ * .tldr, .pro-tip, .for-managers, etc.) are included and tagged
+ * `inCallout: true` — a wall of text in a box is still a wall of text.
+ *
+ * @param {string} content - Raw chapter Markdown
+ * @returns {Array<{line: number, text: string, plain: string, words: number,
+ *   chars: number, sentences: number, inCallout: boolean}>}
+ *   One entry per paragraph; `line` is the 1-based line where it starts.
+ */
+function extractParagraphs(content) {
+  const lines = content.split('\n');
+  const paragraphs = [];
+
+  let inCodeBlock = false;
+  let inCallout = false;
+  let paragraphLines = [];
+  let paragraphStartLine = 0;
+  let paragraphInCallout = false;
+
+  const flush = () => {
+    if (paragraphLines.length === 0) return;
+    const text = paragraphLines.join(' ');
+    const plain = stripInlineMarkup(text);
+    const words = plain.length === 0
+      ? 0
+      : plain.split(/\s+/).filter(word => word.length > 0).length;
+    // Sentence count is a rough heuristic: terminal punctuation followed by
+    // whitespace or end-of-paragraph
+    const sentences = (plain.match(/[.!?](\s|$)/g) || []).length;
+    paragraphs.push({
+      line: paragraphStartLine,
+      text,
+      plain,
+      words,
+      chars: plain.length,
+      sentences,
+      inCallout: paragraphInCallout
+    });
+    paragraphLines = [];
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Fenced code blocks: skip contents entirely
+    if (/^```/.test(trimmed) || /^~~~/.test(trimmed)) {
+      flush();
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) continue;
+
+    // Fenced div open (e.g. ::: {.pro-tip custom-style="pro-tip"})
+    if (/^:::\s*\{/.test(trimmed)) {
+      flush();
+      inCallout = true;
+      continue;
+    }
+    // Fenced div close
+    if (/^:::\s*$/.test(trimmed)) {
+      flush();
+      inCallout = false;
+      continue;
+    }
+
+    // Non-prose block-level lines end the current paragraph
+    if (
+      /^#{1,6}\s/.test(line) ||          // headings
+      /^\s*[-*+]\s/.test(line) ||        // bullet list items
+      /^\s*\d+\.\s/.test(line) ||        // numbered list items
+      /^\s{0,3}>/.test(line) ||          // blockquotes
+      /^\s*\|/.test(line) ||             // tables
+      /^\[\^[^\]]+\]:/.test(trimmed) ||  // footnote definitions
+      /^<!--/.test(trimmed)              // HTML comments (e.g. textlint directives)
+    ) {
+      flush();
+      continue;
+    }
+
+    if (trimmed === '') {
+      flush();
+      continue;
+    }
+
+    if (paragraphLines.length === 0) {
+      paragraphStartLine = i + 1;
+      paragraphInCallout = inCallout;
+    }
+    paragraphLines.push(trimmed);
+  }
+  flush();
+
+  return paragraphs;
+}
+
+/**
+ * Files exempt from paragraph-length checks: structural pages, key-takeaways
+ * collections, and scratch drafts (see lib/structure.js).
+ * @param {string} filePath - Path to chapter file (e.g. src/foo.md)
+ * @returns {boolean} True if the file should be skipped
+ */
+function isParagraphLengthExempt(filePath) {
+  return isNonChapter(filePath);
+}
+
+export {
+  extractParagraphs,
+  stripInlineMarkup,
+  isParagraphLengthExempt,
+  MAX_PARAGRAPH_WORDS
+};

package/lib/revision.js

@@ -0,0 +1,35 @@
+// The build stamp: "<semver> (<short sha>)", e.g. "1.2.0 (0123abcd)".
+//
+// It's passed to pandoc as the `date` metadata and filled into any
+// [...]{.revision} span by filters/revision.lua, so builds never rewrite
+// tracked files. $BOOK_KIT_REVISION overrides it (reproducible parity builds).
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { pathFor, loadConfig } from './config.js';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const DEFAULT_VERSION = '0.1.0';
+
+export function readVersion(path) {
+  if (!existsSync(path)) return DEFAULT_VERSION;
+  const raw = readFileSync(path, 'utf8').trim();
+  if (!SEMVER.test(raw)) {
+    console.warn(`Warning: ${path} holds "${raw}", which isn't semver; using ${DEFAULT_VERSION}`);
+    return DEFAULT_VERSION;
+  }
+  return raw;
+}
+
+export function gitSha(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+export function revision(config = loadConfig()) {
+  if (process.env.BOOK_KIT_REVISION) return process.env.BOOK_KIT_REVISION;
+  return `${readVersion(pathFor('version', config))} (${gitSha(config.root)})`;
+}

package/lib/structure.js

@@ -0,0 +1,39 @@
+// What counts as a chapter. Structural pages (copyright, dedication, about the
+// author, ...), section key-takeaways collections, and scratch drafts aren't
+// narrative chapters, so the prose validators and audits skip them.
+//
+// structure.structural_slugs entries match a file's slug exactly, or by
+// prefix when they end in "*" ("appendix*").
+
+import path from 'node:path';
+import { loadConfigOrDefaults } from './config.js';
+
+export function slugOf(file) {
+  return path.basename(file, '.md');
+}
+
+function matches(slug, pattern) {
+  return pattern.endsWith('*') ? slug.startsWith(pattern.slice(0, -1)) : slug === pattern;
+}
+
+export function isStructuralSlug(slug, config = loadConfigOrDefaults()) {
+  return config.structure.structural_slugs.some((p) => matches(slug, p));
+}
+
+export function isStructural(file, config = loadConfigOrDefaults()) {
+  return isStructuralSlug(slugOf(file), config);
+}
+
+export function isTakeaways(file, config = loadConfigOrDefaults()) {
+  return slugOf(file).endsWith(config.structure.takeaways_suffix);
+}
+
+// A draft that isn't part of the book yet (structure.draft_suffix).
+export function isScratch(file, config = loadConfigOrDefaults()) {
+  return slugOf(file).endsWith(config.structure.draft_suffix ?? '-scratch');
+}
+
+// Not a narrative chapter: skip it in prose audits.
+export function isNonChapter(file, config = loadConfigOrDefaults()) {
+  return isStructural(file, config) || isTakeaways(file, config) || isScratch(file, config);
+}

package/lib/textlint-github-formatter.js

@@ -0,0 +1,58 @@
+/**
+ * textlint formatter that reports findings as GitHub Actions workflow
+ * commands (`::error file=…,line=…::message`), so each one becomes an
+ * annotation on the right file and line.
+ *
+ * The `prose` recipe uses it when GITHUB_ACTIONS is set. Without it,
+ * textlint's stylish output gets parsed by the eslint-stylish problem
+ * matcher that actions/setup-node registers, which misreads it: its file
+ * pattern matches any non-blank line (so a finding becomes the "file" for
+ * the next one, annotated on `.github`), the `✓` fixable marker keeps
+ * fixable findings from matching at all, and multi-line messages are
+ * dropped. Workflow commands carry the file with each finding and escape
+ * newlines, so none of that applies.
+ */
+import path from 'node:path';
+
+const LEVELS = { 1: 'warning', 2: 'error', 3: 'notice' };
+
+// Escaping from @actions/core: data escapes %, CR, LF; properties also , and :
+const escapeData = (s) => String(s)
+  .replace(/%/g, '%25')
+  .replace(/\r/g, '%0D')
+  .replace(/\n/g, '%0A');
+const escapeProperty = (s) => escapeData(s)
+  .replace(/:/g, '%3A')
+  .replace(/,/g, '%2C');
+
+/**
+ * @param {import('@textlint/types').TextlintResult[]} results
+ * @returns {string} One workflow command per finding, then a count
+ */
+export default function format(results) {
+  // Annotation paths are relative to the repository root, which may sit
+  // above the book (the workflow's working-directory input).
+  const root = process.env.GITHUB_WORKSPACE || process.cwd();
+  const lines = [];
+  let count = 0;
+
+  for (const { filePath, messages } of results) {
+    const file = path.relative(root, filePath);
+    for (const m of messages) {
+      count++;
+      const level = LEVELS[m.severity] || 'error';
+      const props = [
+        `file=${escapeProperty(file)}`,
+        `line=${m.line}`,
+        `col=${m.column}`,
+        `title=${escapeProperty(`textlint (${m.ruleId})`)}`,
+      ].join(',');
+      let message = m.message;
+      if (m.fix) message += `${/[.!?]$/.test(message) ? '' : '.'} Fixable with \`just prose --fix\`.`;
+      lines.push(`::${level} ${props}::${escapeData(message)}`);
+    }
+  }
+
+  if (count) lines.push(`${count} prose problem${count === 1 ? '' : 's'}`);
+  return lines.join('\n');
+}