docrev 0.9.17 → 0.10.0

package/dist/lib/build.js

@@ -9,6 +9,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 import YAML from 'yaml';
 import { stripAnnotations } from './annotations.js';
@@ -22,13 +23,19 @@ import { hasPandoc, hasPandocCrossref, hasLatex } from './dependencies.js';
 import { buildImageRegistry, writeImageRegistry } from './image-registry.js';
 import { getJournalProfile } from './journals.js';
 import { resolveCSL } from './csl.js';
+import { mergeMacros, generateLatexPreamble, writeMacrosSidecar, getMacroFilterPath, } from './macros.js';
 // =============================================================================
 // Constants
 // =============================================================================
 /** Supported output formats */
 const SUPPORTED_FORMATS = ['pdf', 'docx', 'tex', 'beamer', 'pptx'];
-/** Maximum title length for output filename */
-const MAX_TITLE_FILENAME_LENGTH = 50;
+/**
+ * Maximum length for slugified-title output filenames. Only used when no
+ * explicit `output:` filename is configured. Long titles are truncated at the
+ * last `-` boundary at-or-before this length so words stay intact (the old
+ * blind `.slice(0, 50)` cut mid-word).
+ */
+const MAX_TITLE_FILENAME_LENGTH = 80;
 /**
  * Default rev.yaml configuration
  */
@@ -61,6 +68,7 @@ export const DEFAULT_CONFIG = {
         keepComments: false,
         affiliationNewline: true,
         toc: false,
+        translateRawFigures: true,
     },
     tex: {
         standalone: true,
@@ -94,6 +102,9 @@ export const DEFAULT_CONFIG = {
         beamer: null,
         all: null, // Runs after any format
     },
+    // Placeholder/highlight macros. Defaults are the built-ins from
+    // lib/macros.ts; users append their own here.
+    macros: [],
     // Final outputs land here (created on demand). Set to null or '' to keep
     // outputs in the project root.
     outputDir: 'output',
@@ -158,6 +169,21 @@ export function mergeJournalFormatting(config, formatting, directory) {
     }
     return merged;
 }
+/**
+ * In-place: copy `pandoc-args` → `pandocArgs` on an object (if not already set).
+ * Idempotent. Coerces a single string into a one-element array.
+ */
+function normalizePandocArgsKey(obj) {
+    if (!obj || typeof obj !== 'object')
+        return;
+    const hy = obj['pandoc-args'];
+    if (hy === undefined)
+        return;
+    if (obj.pandocArgs === undefined) {
+        obj.pandocArgs = Array.isArray(hy) ? hy : [hy];
+    }
+    delete obj['pandoc-args'];
+}
 /**
  * Load rev.yaml config from directory
  * @param directory - Project directory path
@@ -176,6 +202,15 @@ export function loadConfig(directory) {
     try {
         const content = fs.readFileSync(configPath, 'utf-8');
         const userConfig = YAML.parse(content) || {};
+        // Accept hyphenated `pandoc-args` (the form pandoc itself uses) in addition
+        // to camelCase `pandocArgs`. Hyphenated is what we document; camelCase is
+        // accepted for users who already prefer that convention.
+        normalizePandocArgsKey(userConfig);
+        for (const fmt of ['pdf', 'docx', 'tex', 'beamer', 'pptx']) {
+            if (userConfig[fmt] && typeof userConfig[fmt] === 'object') {
+                normalizePandocArgsKey(userConfig[fmt]);
+            }
+        }
         // Deep merge with defaults
         let config = {
             ...DEFAULT_CONFIG,
@@ -576,6 +611,13 @@ export function applyFormatTransforms(content, format, config, registry) {
     }
     else if (format === 'docx') {
         content = convertDynamicRefsToDisplay(content, registry);
+        // Pandoc strips raw LaTeX in docx output. Translate the common
+        // `\begin{figure}...\end{figure}` shape to portable markdown so figures
+        // actually appear; exotic blocks are left alone (warned about in build()).
+        if (config.docx?.translateRawFigures !== false) {
+            const { translated } = translateRawLatexFigures(content);
+            content = translated;
+        }
         if (hasNumberedAffiliations(config)) {
             const mdBlock = generateMarkdownAuthorBlock(config);
             content = content.replace(/^(---\r?\n[\s\S]*?---\r?\n)/, `$1\n${mdBlock}\n`);
@@ -629,8 +671,202 @@ function convertDynamicRefsToDisplay(text, registry) {
     }
     return result;
 }
+/** Match `\begin{figure}` / `\begin{figure*}` … `\end{figure}` blocks. */
+function makeRawFigureRegex() {
+    return /\\begin\{figure\*?\}(?:\[[^\]]*\])?[\s\S]*?\\end\{figure\*?\}/g;
+}
+/**
+ * Convert a LaTeX width spec to a markdown image attribute value.
+ * - `0.8\textwidth` → `80%`
+ * - `\linewidth` → `100%`
+ * - `8cm`, `2in`, `12pt` → kept verbatim
+ * Returns null for anything we don't translate (block stays "exotic").
+ */
+function convertLatexWidth(raw) {
+    const trimmed = raw.trim();
+    // Coefficient × relative length
+    const rel = trimmed.match(/^([\d.]+)\s*\\(textwidth|linewidth|columnwidth)$/);
+    if (rel) {
+        const pct = Math.round(parseFloat(rel[1]) * 100);
+        if (!isFinite(pct) || pct <= 0)
+            return null;
+        return `${pct}%`;
+    }
+    // Bare relative length
+    if (/^\\(textwidth|linewidth|columnwidth)$/.test(trimmed))
+        return '100%';
+    // Absolute units
+    if (/^[\d.]+\s*(cm|mm|in|pt|px|em|ex)$/.test(trimmed))
+        return trimmed.replace(/\s+/g, '');
+    return null;
+}
+/** Extract a balanced `{...}` argument that follows `command` in `text`. */
+function extractBracedArg(text, command) {
+    const idx = text.indexOf(command);
+    if (idx === -1)
+        return null;
+    let i = idx + command.length;
+    while (i < text.length && /\s/.test(text[i]))
+        i++;
+    if (text[i] !== '{')
+        return null;
+    i++;
+    const start = i;
+    let depth = 1;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '\\' && i + 1 < text.length) {
+            i += 2;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i);
+        }
+        i++;
+    }
+    return null;
+}
+/** True if a `\begin{figure}` block contains features we don't auto-translate. */
+function isExoticFigureBlock(block) {
+    if (/\\subfloat\b/.test(block))
+        return true;
+    if (/\\rotatebox\b/.test(block))
+        return true;
+    const includes = (block.match(/\\includegraphics\b/g) || []).length;
+    if (includes !== 1)
+        return true;
+    const m = block.match(/\\includegraphics\s*(?:\[([^\]]*)\])?\s*\{([^}]+)\}/);
+    if (!m)
+        return true;
+    const opts = m[1] || '';
+    const widthMatch = opts.match(/(?:^|,)\s*width\s*=\s*([^,]+)/);
+    if (widthMatch && !convertLatexWidth(widthMatch[1]))
+        return true;
+    return false;
+}
+/**
+ * Find raw LaTeX figure blocks containing `\includegraphics` in markdown.
+ * `file`, if given, is attached to each result. `line` is 1-based within the
+ * supplied content (the line where `\begin{figure}` sits).
+ */
+export function detectRawLatexFigures(content, file) {
+    const figures = [];
+    const re = makeRawFigureRegex();
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const block = m[0];
+        if (!block.includes('\\includegraphics'))
+            continue;
+        const line = content.slice(0, m.index).split(/\r?\n/).length;
+        figures.push({ file, line, block, exotic: isExoticFigureBlock(block) });
+    }
+    return figures;
+}
+/**
+ * Translate the 80% case: single `\includegraphics` figure with optional
+ * `\caption{...}` and `\label{...}`, wrapped in `\begin{figure}...\end{figure}`,
+ * to portable `![caption](path){#fig:label width=N%}` markdown. Exotic blocks
+ * (see `isExoticFigureBlock`) are left untouched.
+ */
+export function translateRawLatexFigures(content) {
+    let translatedCount = 0;
+    const re = makeRawFigureRegex();
+    const translated = content.replace(re, (block) => {
+        if (!block.includes('\\includegraphics'))
+            return block;
+        if (isExoticFigureBlock(block))
+            return block;
+        const inc = block.match(/\\includegraphics\s*(?:\[([^\]]*)\])?\s*\{([^}]+)\}/);
+        if (!inc)
+            return block;
+        const optsStr = inc[1] || '';
+        const imgPath = inc[2].trim();
+        let width;
+        const widthMatch = optsStr.match(/(?:^|,)\s*width\s*=\s*([^,]+)/);
+        if (widthMatch) {
+            const w = convertLatexWidth(widthMatch[1]);
+            if (!w)
+                return block; // already filtered by isExoticFigureBlock, defensive
+            width = w;
+        }
+        const caption = (extractBracedArg(block, '\\caption') ?? '').trim();
+        const labelRaw = extractBracedArg(block, '\\label');
+        const attrs = [];
+        if (labelRaw) {
+            const label = labelRaw.trim();
+            const labelWithPrefix = /^[a-z]+:/i.test(label) ? label : `fig:${label}`;
+            attrs.push(`#${labelWithPrefix}`);
+        }
+        if (width)
+            attrs.push(`width=${width}`);
+        translatedCount++;
+        const attrStr = attrs.length > 0 ? ` {${attrs.join(' ')}}` : '';
+        return `![${caption}](${imgPath})${attrStr}`;
+    });
+    return { translated, translatedCount };
+}
 /**
- * Build pandoc arguments for format
+ * Format the warning surfaced for raw LaTeX figure blocks that won't render
+ * in docx. `translateEnabled` reflects whether auto-translate ran (true = the
+ * listed blocks are exotic leftovers; false = no translation was attempted).
+ */
+function formatRawLatexFigureWarning(figs, translateEnabled) {
+    const reason = translateEnabled ? 'too complex to auto-translate' : 'translateRawFigures: false';
+    const lines = [
+        `${figs.length} raw LaTeX figure block(s) won't render in docx (${reason}).`,
+    ];
+    for (const f of figs) {
+        const loc = f.file ? `${f.file}:${f.line}` : `line ${f.line}`;
+        const pathMatch = f.block.match(/\\includegraphics\s*(?:\[[^\]]*\])?\s*\{([^}]+)\}/);
+        const pathInfo = pathMatch ? `  ${pathMatch[1].trim()}` : '';
+        lines.push(`  ${loc}${pathInfo}`);
+    }
+    lines.push('  Hint: use ![caption](path){#fig:label width=80%} for format-portable figures,');
+    lines.push('        or pass --pandoc-arg=--lua-filter=<your.lua> to translate them yourself.');
+    return lines.join('\n');
+}
+/**
+ * Walk section files and gather a warning for any raw LaTeX figure blocks that
+ * won't survive the docx build. Returns null when there's nothing to warn about.
+ */
+export function collectRawLatexFigureWarning(directory, config) {
+    const translateEnabled = config.docx?.translateRawFigures !== false;
+    const all = [];
+    for (const section of findSections(directory, config.sections)) {
+        const sectionPath = path.join(directory, section);
+        if (!fs.existsSync(sectionPath))
+            continue;
+        try {
+            const content = fs.readFileSync(sectionPath, 'utf-8');
+            const figs = detectRawLatexFigures(content, section);
+            for (const f of figs) {
+                // When auto-translate is on, non-exotic blocks get rewritten cleanly —
+                // only the exotic leftovers need warning. When opted out, everything
+                // is at risk and we warn about every block.
+                if (translateEnabled && !f.exotic)
+                    continue;
+                all.push(f);
+            }
+        }
+        catch {
+            // ignore unreadable sections
+        }
+    }
+    if (all.length === 0)
+        return null;
+    return formatRawLatexFigureWarning(all, translateEnabled);
+}
+/**
+ * Build pandoc arguments for format.
+ *
+ * Returns only the built-in args derived from config. Passthrough args
+ * (config.pandocArgs, config[format].pandocArgs, CLI --pandoc-arg) are
+ * appended later in runPandoc so they win against pptx/crossref defaults
+ * added there.
  */
 export function buildPandocArgs(format, config, outputPath) {
     const args = [];
@@ -748,6 +984,25 @@ export function buildPandocArgs(format, config, outputPath) {
     }
     return args;
 }
+/**
+ * Collect passthrough pandoc args for a format in the canonical order:
+ * top-level config → format-specific config → CLI extras. Later wins for
+ * repeated flags.
+ */
+export function collectPandocPassthroughArgs(format, config, extraArgs = []) {
+    const out = [];
+    if (config.pandocArgs && config.pandocArgs.length > 0) {
+        out.push(...config.pandocArgs);
+    }
+    const formatConfig = config[format];
+    if (formatConfig?.pandocArgs && formatConfig.pandocArgs.length > 0) {
+        out.push(...formatConfig.pandocArgs);
+    }
+    if (extraArgs.length > 0) {
+        out.push(...extraArgs);
+    }
+    return out;
+}
 /**
  * Write crossref.yaml if needed
  */
@@ -777,31 +1032,98 @@ export function resolveOutputDir(directory, config) {
         return directory;
     return path.isAbsolute(out) ? out : path.join(directory, out);
 }
+/** File extension (with leading dot) for each supported pandoc format. */
+const FORMAT_EXTENSIONS = {
+    tex: '.tex',
+    pdf: '.pdf',
+    docx: '.docx',
+    beamer: '.pdf',
+    pptx: '.pptx',
+};
+/** Get file extension for a format, defaulting to `.pdf`. */
+export function getFormatExtension(format) {
+    return FORMAT_EXTENSIONS[format] ?? '.pdf';
+}
+/**
+ * Slugify a title for use as a default output filename. Lowercases, replaces
+ * non-alphanumeric runs with `-`, and truncates at the last `-` boundary
+ * at-or-before MAX_TITLE_FILENAME_LENGTH so words stay whole (the old blind
+ * `.slice` cut mid-word).
+ */
+export function slugifyTitle(title) {
+    if (!title)
+        return 'paper';
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!slug)
+        return 'paper';
+    if (slug.length <= MAX_TITLE_FILENAME_LENGTH)
+        return slug;
+    const cut = slug.slice(0, MAX_TITLE_FILENAME_LENGTH);
+    const lastDash = cut.lastIndexOf('-');
+    // Only truncate at a hyphen if it leaves a reasonable amount of content.
+    // Otherwise hard-cut (handles degenerate titles with no spaces at all).
+    if (lastDash >= MAX_TITLE_FILENAME_LENGTH / 2) {
+        return slug.slice(0, lastDash);
+    }
+    return cut;
+}
+/**
+ * Ensure `name` ends with `ext` (case-insensitive). If the user already supplied
+ * the correct extension, return unchanged; if they supplied none or a different
+ * one, append the format's canonical extension.
+ *
+ * Different-extension case (e.g. `output.docx` when building tex): we append
+ * rather than replace, since stripping looks like an unsafe guess. The result
+ * `output.docx.tex` is loud enough to flag the misconfiguration.
+ */
+function ensureExtension(name, ext) {
+    if (name.toLowerCase().endsWith(ext.toLowerCase()))
+        return name;
+    return name + ext;
+}
+/**
+ * Resolve the final output path for a build.
+ *
+ * Priority: `options.outputPath` (internal force) > `cliOverride` (-o flag) >
+ * `config.output[format]` > slugified title fallback.
+ *
+ * Relative paths from `cliOverride`/`config.output` resolve under outputDir;
+ * absolute paths bypass outputDir. The fallback path always lives under
+ * outputDir.
+ *
+ * @param suffix - Appended before the extension (e.g. "-changes", "-slides").
+ *                 Suppressed when user supplied an explicit name via CLI or
+ *                 config — they pick their own suffix.
+ */
+export function resolveOutputPath(directory, config, format, options = {}) {
+    const { cliOverride, suffix = '' } = options;
+    const ext = getFormatExtension(format);
+    const explicit = cliOverride ?? config.output?.[format];
+    if (explicit) {
+        const baseDir = path.isAbsolute(explicit)
+            ? path.dirname(explicit)
+            : resolveOutputDir(directory, config);
+        const baseName = path.basename(explicit);
+        const stem = baseName.replace(/\.[^./\\]+$/, '');
+        return path.join(baseDir, ensureExtension(`${stem}${suffix}`, ext));
+    }
+    const slug = slugifyTitle(config.title);
+    return path.join(resolveOutputDir(directory, config), `${slug}${suffix}${ext}`);
+}
 /**
  * Run pandoc build
  */
 export async function runPandoc(inputPath, format, config, options = {}) {
     const directory = path.dirname(inputPath);
-    const baseName = config.title
-        ? config.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
-        : 'paper';
-    // Map format to file extension
-    const extMap = {
-        tex: '.tex',
-        pdf: '.pdf',
-        docx: '.docx',
-        beamer: '.pdf', // beamer outputs PDF
-        pptx: '.pptx',
-    };
-    const ext = extMap[format] || '.pdf';
-    // For beamer, use -slides suffix to distinguish from regular PDF
+    // outputPath (internal force) wins over the resolver. For beamer, we keep
+    // the `-slides` suffix on the slug fallback to distinguish from a regular
+    // PDF build; when the user supplies an explicit name, they pick their own.
     const suffix = format === 'beamer' ? '-slides' : '';
-    // Allow custom output path via options. Auto-named outputs go through the
-    // configured outputDir (default 'output/'); explicit paths are honored as-is
-    // so callers can route temp/intermediate artefacts where they want.
     const outputPath = options.outputPath
-        ? options.outputPath
-        : path.join(resolveOutputDir(directory, config), `${baseName}${suffix}${ext}`);
+        ?? resolveOutputPath(directory, config, format, {
+            cliOverride: options.output,
+            suffix,
+        });
     if (!options.outputPath) {
         const outDir = path.dirname(outputPath);
         if (!fs.existsSync(outDir)) {
@@ -847,12 +1169,46 @@ export async function runPandoc(inputPath, format, config, options = {}) {
         if (referenceDoc) {
             args.push('--reference-doc', referenceDoc);
         }
-        // Add color filter for PPTX (handles [text]{color=#RRGGBB} syntax)
-        const colorFilterPath = path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), 'pptx-color-filter.lua');
+        // Add color filter for PPTX (handles [text]{color=#RRGGBB} syntax).
+        // fileURLToPath handles Windows paths with spaces — the old
+        // `new URL(...).pathname` returned URL-encoded `%20` and fs.existsSync
+        // silently failed.
+        const colorFilterPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'pptx-color-filter.lua');
         if (fs.existsSync(colorFilterPath)) {
             args.push('--lua-filter', colorFilterPath);
         }
     }
+    // Wire placeholder macros (built-in \tofill plus user-declared entries).
+    // - docx/html: lua filter expands \name{X} to format-specific raw runs.
+    // - pdf/tex/beamer: inject a \providecommand preamble so LaTeX renders it
+    //   directly. `\providecommand` is non-clobbering, so a user who already
+    //   has `\providecommand{\tofill}{...}` in their own header keeps theirs.
+    //
+    // Sidecar path is passed to the lua filter via DOCREV_MACROS_FILE in the
+    // child env (not pandoc metadata) because pandoc walks RawInline/RawBlock
+    // BEFORE Meta — by the time a Meta handler could read the path, the inline
+    // expansion has already happened.
+    const macroTempFiles = [];
+    let macroEnvFile = null;
+    const macros = mergeMacros(config.macros);
+    if (macros.length > 0) {
+        if (format === 'docx' || format === 'html' || format === 'html5' || format === 'html4') {
+            const sidecarPath = writeMacrosSidecar(directory, macros);
+            macroTempFiles.push(sidecarPath);
+            macroEnvFile = sidecarPath;
+            const filterPath = getMacroFilterPath();
+            if (fs.existsSync(filterPath)) {
+                args.push('--lua-filter', filterPath);
+            }
+        }
+        else if (format === 'pdf' || format === 'tex' || format === 'beamer') {
+            const preamble = generateLatexPreamble(macros);
+            const preamblePath = path.join(directory, '.macros.tex');
+            fs.writeFileSync(preamblePath, preamble, 'utf-8');
+            macroTempFiles.push(preamblePath);
+            args.push('-H', path.basename(preamblePath));
+        }
+    }
     // Add crossref metadata file if exists (skip for slides - they don't use crossref)
     if (format !== 'beamer' && format !== 'pptx') {
         const crossrefPath = path.join(directory, 'crossref.yaml');
@@ -861,18 +1217,41 @@ export async function runPandoc(inputPath, format, config, options = {}) {
             args.push('--metadata-file', 'crossref.yaml');
         }
     }
+    // Passthrough args go last so they win against built-in defaults.
+    args.push(...collectPandocPassthroughArgs(format, config, options.pandocArgs));
     // Input file (use basename since we set cwd to directory)
     args.push(path.basename(inputPath));
+    if (options.verbose) {
+        const quoted = args.map(a => /[\s"'$`]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a).join(' ');
+        console.error(`[pandoc ${format}] (cwd: ${directory})`);
+        console.error(`  pandoc ${quoted}`);
+    }
     return new Promise((resolve) => {
+        const pandocEnv = { ...process.env };
+        if (macroEnvFile) {
+            pandocEnv.DOCREV_MACROS_FILE = macroEnvFile;
+        }
         const pandoc = spawn('pandoc', args, {
             cwd: directory,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: pandocEnv,
         });
         let stderr = '';
         pandoc.stderr?.on('data', (data) => {
             stderr += data.toString();
         });
+        const cleanupMacroTempFiles = () => {
+            for (const tmp of macroTempFiles) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch {
+                    // ignore — best-effort cleanup
+                }
+            }
+        };
         pandoc.on('close', async (code) => {
+            cleanupMacroTempFiles();
             if (code === 0) {
                 // For PPTX, post-process to add slide numbers, buildup colors, and logos
                 if (format === 'pptx') {
@@ -923,6 +1302,7 @@ export async function runPandoc(inputPath, format, config, options = {}) {
             }
         });
         pandoc.on('error', (err) => {
+            cleanupMacroTempFiles();
             resolve({ outputPath, success: false, error: err.message });
         });
     });
@@ -966,6 +1346,12 @@ export async function build(directory, formats = ['pdf', 'docx'], options = {})
         if (imageReg.figures?.length > 0) {
             writeImageRegistry(directory, imageReg);
         }
+        // Warn about raw LaTeX figure blocks that won't render in docx (pandoc
+        // drops them silently). With auto-translate on (default), this surfaces
+        // only the exotic leftovers; with it off, every block.
+        const rawFigWarning = collectRawLatexFigureWarning(directory, config);
+        if (rawFigWarning)
+            warnings.push(rawFigWarning);
     }
     const results = [];
     for (const format of formats) {