docrev 0.2.0

package/lib/build.js

@@ -0,0 +1,486 @@
+/**
+ * Build system - combines sections → paper.md → PDF/DOCX/TEX
+ *
+ * Features:
+ * - Reads rev.yaml config
+ * - Combines section files into paper.md (persisted)
+ * - Strips annotations appropriately per output format
+ * - Runs pandoc with crossref filter
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync, spawn } from 'child_process';
+import yaml from 'js-yaml';
+import { stripAnnotations } from './annotations.js';
+import { buildRegistry, labelToDisplay, detectDynamicRefs } from './crossref.js';
+
+/**
+ * Default rev.yaml configuration
+ */
+export const DEFAULT_CONFIG = {
+  title: 'Untitled Document',
+  authors: [],
+  sections: [],
+  bibliography: null,
+  csl: null,
+  crossref: {
+    figureTitle: 'Figure',
+    tableTitle: 'Table',
+    figPrefix: ['Fig.', 'Figs.'],
+    tblPrefix: ['Table', 'Tables'],
+    secPrefix: ['Section', 'Sections'],
+    linkReferences: true,
+  },
+  pdf: {
+    template: null,
+    documentclass: 'article',
+    fontsize: '12pt',
+    geometry: 'margin=1in',
+    linestretch: 1.5,
+    numbersections: false,
+  },
+  docx: {
+    reference: null,
+    keepComments: true,
+  },
+  tex: {
+    standalone: true,
+  },
+};
+
+/**
+ * Load rev.yaml config from directory
+ * @param {string} directory
+ * @returns {object} merged config with defaults
+ */
+export function loadConfig(directory) {
+  const configPath = path.join(directory, 'rev.yaml');
+
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG, _configPath: null };
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const userConfig = yaml.load(content) || {};
+
+    // Deep merge with defaults
+    const config = {
+      ...DEFAULT_CONFIG,
+      ...userConfig,
+      crossref: { ...DEFAULT_CONFIG.crossref, ...userConfig.crossref },
+      pdf: { ...DEFAULT_CONFIG.pdf, ...userConfig.pdf },
+      docx: { ...DEFAULT_CONFIG.docx, ...userConfig.docx },
+      tex: { ...DEFAULT_CONFIG.tex, ...userConfig.tex },
+      _configPath: configPath,
+    };
+
+    return config;
+  } catch (err) {
+    throw new Error(`Failed to parse rev.yaml: ${err.message}`);
+  }
+}
+
+/**
+ * Find section files in directory
+ * @param {string} directory
+ * @param {string[]} configSections - sections from rev.yaml (optional)
+ * @returns {string[]} ordered list of section files
+ */
+export function findSections(directory, configSections = []) {
+  // If sections specified in config, use that order
+  if (configSections.length > 0) {
+    const sections = [];
+    for (const section of configSections) {
+      const filePath = path.join(directory, section);
+      if (fs.existsSync(filePath)) {
+        sections.push(section);
+      } else {
+        console.warn(`Warning: Section file not found: ${section}`);
+      }
+    }
+    return sections;
+  }
+
+  // Try sections.yaml
+  const sectionsYamlPath = path.join(directory, 'sections.yaml');
+  if (fs.existsSync(sectionsYamlPath)) {
+    try {
+      const sectionsConfig = yaml.load(fs.readFileSync(sectionsYamlPath, 'utf-8'));
+      if (sectionsConfig.sections) {
+        return Object.entries(sectionsConfig.sections)
+          .sort((a, b) => (a[1].order ?? 999) - (b[1].order ?? 999))
+          .map(([file]) => file)
+          .filter((f) => fs.existsSync(path.join(directory, f)));
+      }
+    } catch {
+      // Ignore yaml errors
+    }
+  }
+
+  // Default: find all .md files except special ones
+  const exclude = ['paper.md', 'readme.md', 'claude.md'];
+  const files = fs.readdirSync(directory).filter((f) => {
+    if (!f.endsWith('.md')) return false;
+    if (exclude.includes(f.toLowerCase())) return false;
+    return true;
+  });
+
+  // Sort alphabetically as fallback
+  return files.sort();
+}
+
+/**
+ * Combine section files into paper.md
+ * @param {string} directory
+ * @param {object} config
+ * @param {object} options
+ * @returns {string} path to paper.md
+ */
+export function combineSections(directory, config, options = {}) {
+  const sections = findSections(directory, config.sections);
+
+  if (sections.length === 0) {
+    throw new Error('No section files found. Create .md files or specify sections in rev.yaml');
+  }
+
+  const parts = [];
+
+  // Add YAML frontmatter
+  const frontmatter = buildFrontmatter(config);
+  parts.push('---');
+  parts.push(yaml.dump(frontmatter).trim());
+  parts.push('---');
+  parts.push('');
+
+  // Combine sections
+  for (const section of sections) {
+    const filePath = path.join(directory, section);
+    let content = fs.readFileSync(filePath, 'utf-8');
+
+    // Remove any existing frontmatter from section files
+    content = stripFrontmatter(content);
+
+    parts.push(content.trim());
+    parts.push('');
+    parts.push(''); // Double newline between sections
+  }
+
+  const paperContent = parts.join('\n');
+  const paperPath = path.join(directory, 'paper.md');
+
+  fs.writeFileSync(paperPath, paperContent, 'utf-8');
+
+  return paperPath;
+}
+
+/**
+ * Build YAML frontmatter from config
+ * @param {object} config
+ * @returns {object}
+ */
+function buildFrontmatter(config) {
+  const fm = {};
+
+  if (config.title) fm.title = config.title;
+
+  if (config.authors && config.authors.length > 0) {
+    fm.author = config.authors;
+  }
+
+  if (config.bibliography) {
+    fm.bibliography = config.bibliography;
+  }
+
+  if (config.csl) {
+    fm.csl = config.csl;
+  }
+
+  return fm;
+}
+
+/**
+ * Strip YAML frontmatter from content
+ * @param {string} content
+ * @returns {string}
+ */
+function stripFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (match) {
+    return content.slice(match[0].length);
+  }
+  return content;
+}
+
+/**
+ * Prepare paper.md for specific output format
+ * @param {string} paperPath
+ * @param {string} format - 'pdf', 'docx', 'tex'
+ * @param {object} config
+ * @param {object} options
+ * @returns {string} path to prepared file
+ */
+export function prepareForFormat(paperPath, format, config, options = {}) {
+  const directory = path.dirname(paperPath);
+  let content = fs.readFileSync(paperPath, 'utf-8');
+
+  // Build crossref registry for reference conversion
+  const registry = buildRegistry(directory);
+
+  if (format === 'pdf' || format === 'tex') {
+    // Strip all annotations for clean output
+    content = stripAnnotations(content);
+  } else if (format === 'docx') {
+    // Strip track changes, optionally keep comments
+    content = stripAnnotations(content, { keepComments: config.docx.keepComments });
+
+    // Convert @fig:label to "Figure 1" for Word readers
+    content = convertDynamicRefsToDisplay(content, registry);
+  }
+
+  // Write to temporary file
+  const preparedPath = path.join(directory, `.paper-${format}.md`);
+  fs.writeFileSync(preparedPath, content, 'utf-8');
+
+  return preparedPath;
+}
+
+/**
+ * Convert @fig:label references to display format (Figure 1)
+ * @param {string} text
+ * @param {object} registry
+ * @returns {string}
+ */
+function convertDynamicRefsToDisplay(text, registry) {
+  const refs = detectDynamicRefs(text);
+
+  // Process in reverse order to preserve positions
+  let result = text;
+  for (let i = refs.length - 1; i >= 0; i--) {
+    const ref = refs[i];
+    const display = labelToDisplay(ref.type, ref.label, registry);
+
+    if (display) {
+      result = result.slice(0, ref.position) + display + result.slice(ref.position + ref.match.length);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build pandoc arguments for format
+ * @param {string} format
+ * @param {object} config
+ * @param {string} outputPath
+ * @returns {string[]}
+ */
+export function buildPandocArgs(format, config, outputPath) {
+  const args = [];
+
+  // Output format
+  if (format === 'tex') {
+    args.push('-t', 'latex');
+    if (config.tex.standalone) {
+      args.push('-s');
+    }
+  } else if (format === 'pdf') {
+    args.push('-t', 'pdf');
+  } else if (format === 'docx') {
+    args.push('-t', 'docx');
+  }
+
+  args.push('-o', outputPath);
+
+  // Crossref filter (if available)
+  if (hasPandocCrossref()) {
+    args.push('--filter', 'pandoc-crossref');
+  }
+
+  // Bibliography
+  if (config.bibliography) {
+    args.push('--citeproc');
+  }
+
+  // Format-specific options
+  if (format === 'pdf') {
+    if (config.pdf.template) {
+      args.push('--template', config.pdf.template);
+    }
+    args.push('-V', `documentclass=${config.pdf.documentclass}`);
+    args.push('-V', `fontsize=${config.pdf.fontsize}`);
+    args.push('-V', `geometry:${config.pdf.geometry}`);
+    if (config.pdf.linestretch !== 1) {
+      args.push('-V', `linestretch=${config.pdf.linestretch}`);
+    }
+    if (config.pdf.numbersections) {
+      args.push('--number-sections');
+    }
+  } else if (format === 'docx') {
+    if (config.docx.reference) {
+      args.push('--reference-doc', config.docx.reference);
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Check if pandoc-crossref is available
+ * @returns {boolean}
+ */
+export function hasPandocCrossref() {
+  try {
+    execSync('pandoc-crossref --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if pandoc is available
+ * @returns {boolean}
+ */
+export function hasPandoc() {
+  try {
+    execSync('pandoc --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write crossref.yaml if needed
+ * @param {string} directory
+ * @param {object} config
+ */
+function ensureCrossrefConfig(directory, config) {
+  const crossrefPath = path.join(directory, 'crossref.yaml');
+
+  if (!fs.existsSync(crossrefPath) && hasPandocCrossref()) {
+    fs.writeFileSync(crossrefPath, yaml.dump(config.crossref), 'utf-8');
+  }
+}
+
+/**
+ * Run pandoc build
+ * @param {string} inputPath
+ * @param {string} format
+ * @param {object} config
+ * @param {object} options
+ * @returns {Promise<{outputPath: string, success: boolean, error?: string}>}
+ */
+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';
+
+  const ext = format === 'tex' ? '.tex' : format === 'pdf' ? '.pdf' : '.docx';
+  const outputPath = path.join(directory, `${baseName}${ext}`);
+
+  // Ensure crossref.yaml exists
+  ensureCrossrefConfig(directory, config);
+
+  const args = buildPandocArgs(format, config, outputPath);
+
+  // Add crossref metadata file if exists
+  const crossrefPath = path.join(directory, 'crossref.yaml');
+  if (fs.existsSync(crossrefPath) && hasPandocCrossref()) {
+    args.push('--metadata-file', crossrefPath);
+  }
+
+  // Input file
+  args.push(inputPath);
+
+  return new Promise((resolve) => {
+    const pandoc = spawn('pandoc', args, {
+      cwd: directory,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stderr = '';
+    pandoc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    pandoc.on('close', (code) => {
+      if (code === 0) {
+        resolve({ outputPath, success: true });
+      } else {
+        resolve({ outputPath, success: false, error: stderr || `Exit code ${code}` });
+      }
+    });
+
+    pandoc.on('error', (err) => {
+      resolve({ outputPath, success: false, error: err.message });
+    });
+  });
+}
+
+/**
+ * Full build pipeline
+ * @param {string} directory
+ * @param {string[]} formats - ['pdf', 'docx', 'tex'] or ['all']
+ * @param {object} options
+ * @returns {Promise<{results: object[], paperPath: string}>}
+ */
+export async function build(directory, formats = ['pdf', 'docx'], options = {}) {
+  // Check pandoc
+  if (!hasPandoc()) {
+    throw new Error('pandoc not found. Run `rev install` to install dependencies.');
+  }
+
+  // Load config
+  const config = loadConfig(directory);
+
+  // Combine sections → paper.md
+  const paperPath = combineSections(directory, config, options);
+
+  // Expand 'all' to all formats
+  if (formats.includes('all')) {
+    formats = ['pdf', 'docx', 'tex'];
+  }
+
+  const results = [];
+
+  for (const format of formats) {
+    // Prepare format-specific version
+    const preparedPath = prepareForFormat(paperPath, format, config, options);
+
+    // Run pandoc
+    const result = await runPandoc(preparedPath, format, config, options);
+    results.push({ format, ...result });
+
+    // Clean up temp file
+    try {
+      fs.unlinkSync(preparedPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  return { results, paperPath };
+}
+
+/**
+ * Get build status summary
+ * @param {object[]} results
+ * @returns {string}
+ */
+export function formatBuildResults(results) {
+  const lines = [];
+
+  for (const r of results) {
+    if (r.success) {
+      lines.push(`  ${r.format.toUpperCase()}: ${path.basename(r.outputPath)}`);
+    } else {
+      lines.push(`  ${r.format.toUpperCase()}: FAILED - ${r.error}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/lib/citations.js

@@ -0,0 +1,149 @@
+/**
+ * Citation validation utilities
+ * Check that all [@cite] references exist in .bib file
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Extract all citation keys from markdown text
+ * Handles: [@Key], [@Key1; @Key2], @Key (inline)
+ * @param {string} text
+ * @returns {Array<{key: string, line: number, file: string}>}
+ */
+export function extractCitations(text, file = '') {
+  const citations = [];
+  const lines = text.split('\n');
+
+  // Pattern for bracketed citations: [@Key] or [@Key1; @Key2]
+  const bracketPattern = /\[@([^\]]+)\]/g;
+  // Pattern for inline citations: @Key (word boundary)
+  const inlinePattern = /(?<!\[)@([A-Za-z][A-Za-z0-9_-]*\d{4}[a-z]?)(?![;\]])/g;
+
+  for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+    const line = lines[lineNum];
+
+    // Skip code blocks and comments
+    if (line.trim().startsWith('```') || line.trim().startsWith('<!--')) continue;
+
+    // Bracketed citations
+    let match;
+    while ((match = bracketPattern.exec(line)) !== null) {
+      // Split by ; for multiple citations
+      const keys = match[1].split(';').map(k => k.trim().replace(/^@/, ''));
+      for (const key of keys) {
+        if (key) {
+          citations.push({ key, line: lineNum + 1, file });
+        }
+      }
+    }
+
+    // Inline citations (reset lastIndex)
+    inlinePattern.lastIndex = 0;
+    while ((match = inlinePattern.exec(line)) !== null) {
+      citations.push({ key: match[1], line: lineNum + 1, file });
+    }
+  }
+
+  return citations;
+}
+
+/**
+ * Parse .bib file and extract all entry keys
+ * @param {string} bibPath
+ * @returns {Set<string>}
+ */
+export function parseBibFile(bibPath) {
+  const keys = new Set();
+
+  if (!fs.existsSync(bibPath)) {
+    return keys;
+  }
+
+  const content = fs.readFileSync(bibPath, 'utf-8');
+
+  // Pattern for bib entries: @type{key,
+  const entryPattern = /@\w+\s*\{\s*([^,\s]+)\s*,/g;
+
+  let match;
+  while ((match = entryPattern.exec(content)) !== null) {
+    keys.add(match[1]);
+  }
+
+  return keys;
+}
+
+/**
+ * Validate citations against bib file
+ * @param {string[]} mdFiles - Markdown files to check
+ * @param {string} bibPath - Path to .bib file
+ * @returns {{valid: Array, missing: Array, unused: Array, duplicates: Array}}
+ */
+export function validateCitations(mdFiles, bibPath) {
+  // Collect all citations from markdown
+  const allCitations = [];
+  for (const file of mdFiles) {
+    if (!fs.existsSync(file)) continue;
+    const text = fs.readFileSync(file, 'utf-8');
+    const citations = extractCitations(text, path.basename(file));
+    allCitations.push(...citations);
+  }
+
+  // Get bib keys
+  const bibKeys = parseBibFile(bibPath);
+
+  // Categorize
+  const valid = [];
+  const missing = [];
+  const citedKeys = new Set();
+  const keyOccurrences = new Map();
+
+  for (const citation of allCitations) {
+    citedKeys.add(citation.key);
+
+    // Track occurrences for duplicates
+    if (!keyOccurrences.has(citation.key)) {
+      keyOccurrences.set(citation.key, []);
+    }
+    keyOccurrences.get(citation.key).push(citation);
+
+    if (bibKeys.has(citation.key)) {
+      valid.push(citation);
+    } else {
+      missing.push(citation);
+    }
+  }
+
+  // Find unused bib entries
+  const unused = [...bibKeys].filter(key => !citedKeys.has(key));
+
+  // Find duplicate citations (same key cited multiple times - not an error, just info)
+  const duplicates = [...keyOccurrences.entries()]
+    .filter(([key, occurrences]) => occurrences.length > 1)
+    .map(([key, occurrences]) => ({ key, count: occurrences.length, locations: occurrences }));
+
+  return { valid, missing, unused, duplicates };
+}
+
+/**
+ * Get citation statistics
+ * @param {string[]} mdFiles
+ * @param {string} bibPath
+ * @returns {object}
+ */
+export function getCitationStats(mdFiles, bibPath) {
+  const result = validateCitations(mdFiles, bibPath);
+  const bibKeys = parseBibFile(bibPath);
+
+  return {
+    totalCitations: result.valid.length + result.missing.length,
+    uniqueCited: new Set([...result.valid, ...result.missing].map(c => c.key)).size,
+    valid: result.valid.length,
+    missing: result.missing.length,
+    missingKeys: [...new Set(result.missing.map(c => c.key))],
+    bibEntries: bibKeys.size,
+    unused: result.unused.length,
+    unusedKeys: result.unused,
+  };
+}

package/lib/config.js

@@ -0,0 +1,60 @@
+/**
+ * User configuration management
+ * Stores user preferences in ~/.revrc
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const CONFIG_PATH = path.join(os.homedir(), '.revrc');
+
+/**
+ * Load user config
+ * @returns {object}
+ */
+export function loadUserConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return {};
+}
+
+/**
+ * Save user config
+ * @param {object} config
+ */
+export function saveUserConfig(config) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * Get user name
+ * @returns {string|null}
+ */
+export function getUserName() {
+  const config = loadUserConfig();
+  return config.userName || null;
+}
+
+/**
+ * Set user name
+ * @param {string} name
+ */
+export function setUserName(name) {
+  const config = loadUserConfig();
+  config.userName = name;
+  saveUserConfig(config);
+}
+
+/**
+ * Get config file path
+ * @returns {string}
+ */
+export function getConfigPath() {
+  return CONFIG_PATH;
+}