docrev 0.10.1 → 0.11.0

package/lib/macros.ts

@@ -1,273 +1,273 @@
-/**
- * Placeholder/highlight macros for docrev.
- *
- * Users write `\tofill{X}` (or any custom macro they declare) in markdown
- * source and the build pipeline expands it per output format:
- *
- *   - docx: raw OpenXML run with explicit color + bold (Span+style is NOT
- *     honored by pandoc's docx writer, so we emit raw <w:r> nodes).
- *   - pdf / tex / beamer: a `\providecommand` is injected via header-includes,
- *     so the LaTeX command works directly. `\providecommand` means the user
- *     can still override with `\renewcommand` in their own preamble.
- *   - html: raw HTML span with inline style.
- *   - everything else (markdown, gfm, etc.): bold [X] fallback. Never silently
- *     dropped.
- *
- * The mechanism is generic: `\tofill` is the first built-in. Users can add
- * their own macros under `macros:` in rev.yaml, and override the built-in by
- * declaring a macro with the same name.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Per-format rendering rules for a macro.
- *
- * Fields are independent — set any subset. Unset fields fall back to defaults
- * (no color, no bold, no italic, bracket wrap on, etc.).
- */
-export interface MacroFormatStyle {
-  /** Hex color without '#' (e.g. "C2410C"). */
-  color?: string;
-  /** Wrap the rendered content in bold. */
-  bold?: boolean;
-  /** Wrap the rendered content in italic. */
-  italic?: boolean;
-  /** Wrap the content in [...] brackets. Default: true. */
-  bracket?: boolean;
-  /** Optional literal prefix string inside the brackets (e.g. "NOTE: "). */
-  prefix?: string;
-  /** Optional literal suffix string inside the brackets. */
-  suffix?: string;
-}
-
-/**
- * Macro definition. `name` is the LaTeX command name without the leading
- * backslash (e.g. "tofill" → \tofill{...}). `formats` holds per-format rules;
- * a missing format key inherits from `default`.
- */
-export interface MacroDef {
-  name: string;
-  /** Default rendering rules; used when a format-specific override is absent. */
-  default?: MacroFormatStyle;
-  /** Per-format overrides, keyed by pandoc format (docx, pdf, html, ...). */
-  formats?: Record<string, MacroFormatStyle>;
-}
-
-/**
- * Built-in macros shipped with docrev. The first entry is the original use
- * case: \tofill{X} → bold orange [X] placeholder.
- */
-export const BUILTIN_MACROS: MacroDef[] = [
-  {
-    name: 'tofill',
-    default: { color: 'C2410C', bold: true, bracket: true },
-  },
-];
-
-// =============================================================================
-// Validation
-// =============================================================================
-
-const MACRO_NAME_RE = /^[A-Za-z][A-Za-z0-9]*$/;
-const HEX_COLOR_RE = /^[0-9A-Fa-f]{6}$/;
-
-/**
- * Validate a user-declared macro entry. Returns a list of error strings;
- * empty means the macro is valid.
- */
-export function validateMacro(macro: unknown): string[] {
-  const errors: string[] = [];
-
-  if (!macro || typeof macro !== 'object' || Array.isArray(macro)) {
-    return ['macro must be an object'];
-  }
-  const m = macro as Partial<MacroDef>;
-
-  if (!m.name || typeof m.name !== 'string') {
-    errors.push('macro.name is required');
-  } else if (!MACRO_NAME_RE.test(m.name)) {
-    errors.push(`macro.name "${m.name}" must match [A-Za-z][A-Za-z0-9]*`);
-  }
-
-  const checkStyle = (style: unknown, key: string): void => {
-    if (style === undefined) return;
-    if (!style || typeof style !== 'object' || Array.isArray(style)) {
-      errors.push(`${key} must be an object`);
-      return;
-    }
-    const s = style as MacroFormatStyle;
-    if (s.color !== undefined && (typeof s.color !== 'string' || !HEX_COLOR_RE.test(s.color))) {
-      errors.push(`${key}.color must be a 6-digit hex string without '#' (got "${s.color}")`);
-    }
-    for (const flag of ['bold', 'italic', 'bracket'] as const) {
-      if (s[flag] !== undefined && typeof s[flag] !== 'boolean') {
-        errors.push(`${key}.${flag} must be a boolean`);
-      }
-    }
-    for (const text of ['prefix', 'suffix'] as const) {
-      if (s[text] !== undefined && typeof s[text] !== 'string') {
-        errors.push(`${key}.${text} must be a string`);
-      }
-    }
-  };
-
-  checkStyle(m.default, 'macro.default');
-  if (m.formats !== undefined) {
-    if (!m.formats || typeof m.formats !== 'object' || Array.isArray(m.formats)) {
-      errors.push('macro.formats must be an object keyed by format name');
-    } else {
-      for (const [fmt, style] of Object.entries(m.formats)) {
-        checkStyle(style, `macro.formats.${fmt}`);
-      }
-    }
-  }
-
-  return errors;
-}
-
-// =============================================================================
-// Merge
-// =============================================================================
-
-/**
- * Merge built-in macros with user-declared macros. User entries override
- * built-ins by `name` (case-sensitive). Invalid entries are dropped with a
- * console warning so a malformed user macro never silently disables the
- * built-in.
- */
-export function mergeMacros(userMacros: unknown): MacroDef[] {
-  const builtins = new Map<string, MacroDef>();
-  for (const m of BUILTIN_MACROS) builtins.set(m.name, m);
-
-  if (!userMacros) return [...builtins.values()];
-  if (!Array.isArray(userMacros)) {
-    console.warn('macros: rev.yaml `macros` must be a list; ignoring');
-    return [...builtins.values()];
-  }
-
-  for (const raw of userMacros) {
-    const errors = validateMacro(raw);
-    if (errors.length > 0) {
-      console.warn(`macros: skipping invalid macro: ${errors.join('; ')}`);
-      continue;
-    }
-    const def = raw as MacroDef;
-    builtins.set(def.name, def);
-  }
-
-  return [...builtins.values()];
-}
-
-// =============================================================================
-// LaTeX preamble generation (PDF / tex / beamer)
-// =============================================================================
-
-/**
- * Build the LaTeX color spec for a style. Returns the wrapping LaTeX with a
- * `#1` placeholder where the argument lands.
- */
-function latexCommandBody(style: MacroFormatStyle): string {
-  const prefix = style.prefix ? escapeLatex(style.prefix) : '';
-  const suffix = style.suffix ? escapeLatex(style.suffix) : '';
-  const inner = `${prefix}#1${suffix}`;
-  const bracketed = style.bracket === false ? inner : `[${inner}]`;
-
-  let body = bracketed;
-  if (style.italic) body = `\\textit{${body}}`;
-  if (style.bold) body = `\\textbf{${body}}`;
-  if (style.color) body = `\\textcolor[HTML]{${style.color.toUpperCase()}}{${body}}`;
-  return body;
-}
-
-/**
- * Generate `\providecommand` definitions for all macros. `\providecommand`
- * means user-supplied `\renewcommand` (in a custom header-includes file) still
- * wins, preserving backwards compat with existing projects.
- *
- * Returns an empty string when the macro list is empty.
- */
-export function generateLatexPreamble(macros: MacroDef[]): string {
-  const lines: string[] = ['% docrev: placeholder macros'];
-  // \textcolor in [HTML]{...} requires xcolor with the [HTML] option.
-  lines.push('\\PassOptionsToPackage{HTML}{xcolor}');
-  // Some templates already load xcolor; \usepackage tolerates duplicates with
-  // the same options.
-  lines.push('\\usepackage[HTML]{xcolor}');
-
-  for (const m of macros) {
-    const style = pickStyle(m, 'latex');
-    const body = latexCommandBody(style);
-    lines.push(`\\providecommand{\\${m.name}}[1]{${body}}`);
-  }
-
-  return lines.join('\n');
-}
-
-function escapeLatex(s: string): string {
-  // Conservative escape — these are user-authored short literals (prefix/suffix).
-  return s
-    .replace(/\\/g, '\\textbackslash{}')
-    .replace(/([&%$#_{}])/g, '\\$1')
-    .replace(/~/g, '\\textasciitilde{}')
-    .replace(/\^/g, '\\textasciicircum{}');
-}
-
-// =============================================================================
-// Style resolution per format
-// =============================================================================
-
-/**
- * Resolve the effective style for a macro in a given pandoc format. Per-format
- * override wins over the macro's default; both can be partial — fields are
- * not merged across `default` and `formats[fmt]` (the format-specific entry
- * replaces `default` entirely when present), keeping rev.yaml semantics
- * predictable.
- *
- * Falls back to `default` when no `formats[fmt]` exists, and to an empty
- * style ({}) when neither is set.
- */
-export function pickStyle(macro: MacroDef, format: string): MacroFormatStyle {
-  const fmt = macro.formats?.[format];
-  if (fmt) return fmt;
-  return macro.default ?? {};
-}
-
-// =============================================================================
-// Lua filter sidecar
-// =============================================================================
-
-/**
- * Serialize the macro list to a compact JSON sidecar consumed by the lua
- * filter at build time. The lua filter reads this file at startup and uses it
- * to expand `\tofill{X}` (or any other declared macro) per FORMAT.
- *
- * Returns the absolute path to the written sidecar.
- */
-export function writeMacrosSidecar(directory: string, macros: MacroDef[]): string {
-  const sidecarPath = path.join(directory, '.macros.json');
-  fs.writeFileSync(sidecarPath, JSON.stringify({ macros }), 'utf-8');
-  return sidecarPath;
-}
-
-/**
- * Resolve the absolute path to the bundled lua filter. Works both from source
- * (`lib/macro-filter.lua`) and from the compiled package (`dist/lib/...`)
- * because the postbuild script copies .lua files alongside the .js output.
- */
-export function getMacroFilterPath(): string {
-  // import.meta.url points to the running file: lib/macros.ts in source,
-  // dist/lib/macros.js when published. The filter sits next to it.
-  //
-  // Use fileURLToPath so paths with spaces (Windows: "C:\Users\Gilles Colling\…")
-  // resolve correctly. The naive `new URL(...).pathname` returns URL-encoded
-  // `%20` segments and fs.existsSync silently fails.
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.join(here, 'macro-filter.lua');
-}
+/**
+ * Placeholder/highlight macros for docrev.
+ *
+ * Users write `\tofill{X}` (or any custom macro they declare) in markdown
+ * source and the build pipeline expands it per output format:
+ *
+ *   - docx: raw OpenXML run with explicit color + bold (Span+style is NOT
+ *     honored by pandoc's docx writer, so we emit raw <w:r> nodes).
+ *   - pdf / tex / beamer: a `\providecommand` is injected via header-includes,
+ *     so the LaTeX command works directly. `\providecommand` means the user
+ *     can still override with `\renewcommand` in their own preamble.
+ *   - html: raw HTML span with inline style.
+ *   - everything else (markdown, gfm, etc.): bold [X] fallback. Never silently
+ *     dropped.
+ *
+ * The mechanism is generic: `\tofill` is the first built-in. Users can add
+ * their own macros under `macros:` in rev.yaml, and override the built-in by
+ * declaring a macro with the same name.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Per-format rendering rules for a macro.
+ *
+ * Fields are independent — set any subset. Unset fields fall back to defaults
+ * (no color, no bold, no italic, bracket wrap on, etc.).
+ */
+export interface MacroFormatStyle {
+  /** Hex color without '#' (e.g. "C2410C"). */
+  color?: string;
+  /** Wrap the rendered content in bold. */
+  bold?: boolean;
+  /** Wrap the rendered content in italic. */
+  italic?: boolean;
+  /** Wrap the content in [...] brackets. Default: true. */
+  bracket?: boolean;
+  /** Optional literal prefix string inside the brackets (e.g. "NOTE: "). */
+  prefix?: string;
+  /** Optional literal suffix string inside the brackets. */
+  suffix?: string;
+}
+
+/**
+ * Macro definition. `name` is the LaTeX command name without the leading
+ * backslash (e.g. "tofill" → \tofill{...}). `formats` holds per-format rules;
+ * a missing format key inherits from `default`.
+ */
+export interface MacroDef {
+  name: string;
+  /** Default rendering rules; used when a format-specific override is absent. */
+  default?: MacroFormatStyle;
+  /** Per-format overrides, keyed by pandoc format (docx, pdf, html, ...). */
+  formats?: Record<string, MacroFormatStyle>;
+}
+
+/**
+ * Built-in macros shipped with docrev. The first entry is the original use
+ * case: \tofill{X} → bold orange [X] placeholder.
+ */
+export const BUILTIN_MACROS: MacroDef[] = [
+  {
+    name: 'tofill',
+    default: { color: 'C2410C', bold: true, bracket: true },
+  },
+];
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+const MACRO_NAME_RE = /^[A-Za-z][A-Za-z0-9]*$/;
+const HEX_COLOR_RE = /^[0-9A-Fa-f]{6}$/;
+
+/**
+ * Validate a user-declared macro entry. Returns a list of error strings;
+ * empty means the macro is valid.
+ */
+export function validateMacro(macro: unknown): string[] {
+  const errors: string[] = [];
+
+  if (!macro || typeof macro !== 'object' || Array.isArray(macro)) {
+    return ['macro must be an object'];
+  }
+  const m = macro as Partial<MacroDef>;
+
+  if (!m.name || typeof m.name !== 'string') {
+    errors.push('macro.name is required');
+  } else if (!MACRO_NAME_RE.test(m.name)) {
+    errors.push(`macro.name "${m.name}" must match [A-Za-z][A-Za-z0-9]*`);
+  }
+
+  const checkStyle = (style: unknown, key: string): void => {
+    if (style === undefined) return;
+    if (!style || typeof style !== 'object' || Array.isArray(style)) {
+      errors.push(`${key} must be an object`);
+      return;
+    }
+    const s = style as MacroFormatStyle;
+    if (s.color !== undefined && (typeof s.color !== 'string' || !HEX_COLOR_RE.test(s.color))) {
+      errors.push(`${key}.color must be a 6-digit hex string without '#' (got "${s.color}")`);
+    }
+    for (const flag of ['bold', 'italic', 'bracket'] as const) {
+      if (s[flag] !== undefined && typeof s[flag] !== 'boolean') {
+        errors.push(`${key}.${flag} must be a boolean`);
+      }
+    }
+    for (const text of ['prefix', 'suffix'] as const) {
+      if (s[text] !== undefined && typeof s[text] !== 'string') {
+        errors.push(`${key}.${text} must be a string`);
+      }
+    }
+  };
+
+  checkStyle(m.default, 'macro.default');
+  if (m.formats !== undefined) {
+    if (!m.formats || typeof m.formats !== 'object' || Array.isArray(m.formats)) {
+      errors.push('macro.formats must be an object keyed by format name');
+    } else {
+      for (const [fmt, style] of Object.entries(m.formats)) {
+        checkStyle(style, `macro.formats.${fmt}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+// =============================================================================
+// Merge
+// =============================================================================
+
+/**
+ * Merge built-in macros with user-declared macros. User entries override
+ * built-ins by `name` (case-sensitive). Invalid entries are dropped with a
+ * console warning so a malformed user macro never silently disables the
+ * built-in.
+ */
+export function mergeMacros(userMacros: unknown): MacroDef[] {
+  const builtins = new Map<string, MacroDef>();
+  for (const m of BUILTIN_MACROS) builtins.set(m.name, m);
+
+  if (!userMacros) return [...builtins.values()];
+  if (!Array.isArray(userMacros)) {
+    console.warn('macros: rev.yaml `macros` must be a list; ignoring');
+    return [...builtins.values()];
+  }
+
+  for (const raw of userMacros) {
+    const errors = validateMacro(raw);
+    if (errors.length > 0) {
+      console.warn(`macros: skipping invalid macro: ${errors.join('; ')}`);
+      continue;
+    }
+    const def = raw as MacroDef;
+    builtins.set(def.name, def);
+  }
+
+  return [...builtins.values()];
+}
+
+// =============================================================================
+// LaTeX preamble generation (PDF / tex / beamer)
+// =============================================================================
+
+/**
+ * Build the LaTeX color spec for a style. Returns the wrapping LaTeX with a
+ * `#1` placeholder where the argument lands.
+ */
+function latexCommandBody(style: MacroFormatStyle): string {
+  const prefix = style.prefix ? escapeLatex(style.prefix) : '';
+  const suffix = style.suffix ? escapeLatex(style.suffix) : '';
+  const inner = `${prefix}#1${suffix}`;
+  const bracketed = style.bracket === false ? inner : `[${inner}]`;
+
+  let body = bracketed;
+  if (style.italic) body = `\\textit{${body}}`;
+  if (style.bold) body = `\\textbf{${body}}`;
+  if (style.color) body = `\\textcolor[HTML]{${style.color.toUpperCase()}}{${body}}`;
+  return body;
+}
+
+/**
+ * Generate `\providecommand` definitions for all macros. `\providecommand`
+ * means user-supplied `\renewcommand` (in a custom header-includes file) still
+ * wins, preserving backwards compat with existing projects.
+ *
+ * Returns an empty string when the macro list is empty.
+ */
+export function generateLatexPreamble(macros: MacroDef[]): string {
+  const lines: string[] = ['% docrev: placeholder macros'];
+  // \textcolor in [HTML]{...} requires xcolor with the [HTML] option.
+  lines.push('\\PassOptionsToPackage{HTML}{xcolor}');
+  // Some templates already load xcolor; \usepackage tolerates duplicates with
+  // the same options.
+  lines.push('\\usepackage[HTML]{xcolor}');
+
+  for (const m of macros) {
+    const style = pickStyle(m, 'latex');
+    const body = latexCommandBody(style);
+    lines.push(`\\providecommand{\\${m.name}}[1]{${body}}`);
+  }
+
+  return lines.join('\n');
+}
+
+function escapeLatex(s: string): string {
+  // Conservative escape — these are user-authored short literals (prefix/suffix).
+  return s
+    .replace(/\\/g, '\\textbackslash{}')
+    .replace(/([&%$#_{}])/g, '\\$1')
+    .replace(/~/g, '\\textasciitilde{}')
+    .replace(/\^/g, '\\textasciicircum{}');
+}
+
+// =============================================================================
+// Style resolution per format
+// =============================================================================
+
+/**
+ * Resolve the effective style for a macro in a given pandoc format. Per-format
+ * override wins over the macro's default; both can be partial — fields are
+ * not merged across `default` and `formats[fmt]` (the format-specific entry
+ * replaces `default` entirely when present), keeping rev.yaml semantics
+ * predictable.
+ *
+ * Falls back to `default` when no `formats[fmt]` exists, and to an empty
+ * style ({}) when neither is set.
+ */
+export function pickStyle(macro: MacroDef, format: string): MacroFormatStyle {
+  const fmt = macro.formats?.[format];
+  if (fmt) return fmt;
+  return macro.default ?? {};
+}
+
+// =============================================================================
+// Lua filter sidecar
+// =============================================================================
+
+/**
+ * Serialize the macro list to a compact JSON sidecar consumed by the lua
+ * filter at build time. The lua filter reads this file at startup and uses it
+ * to expand `\tofill{X}` (or any other declared macro) per FORMAT.
+ *
+ * Returns the absolute path to the written sidecar.
+ */
+export function writeMacrosSidecar(directory: string, macros: MacroDef[]): string {
+  const sidecarPath = path.join(directory, '.macros.json');
+  fs.writeFileSync(sidecarPath, JSON.stringify({ macros }), 'utf-8');
+  return sidecarPath;
+}
+
+/**
+ * Resolve the absolute path to the bundled lua filter. Works both from source
+ * (`lib/macro-filter.lua`) and from the compiled package (`dist/lib/...`)
+ * because the postbuild script copies .lua files alongside the .js output.
+ */
+export function getMacroFilterPath(): string {
+  // import.meta.url points to the running file: lib/macros.ts in source,
+  // dist/lib/macros.js when published. The filter sits next to it.
+  //
+  // Use fileURLToPath so paths with spaces (Windows: "C:\Users\Gilles Colling\…")
+  // resolve correctly. The naive `new URL(...).pathname` returns URL-encoded
+  // `%20` segments and fs.existsSync silently fails.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(here, 'macro-filter.lua');
+}