docrev 0.2.0

package/lib/crossref.js

@@ -0,0 +1,426 @@
+/**
+ * Cross-reference handling - dynamic figure/table references
+ *
+ * Enables:
+ * - @fig:label syntax in source (auto-numbered)
+ * - Conversion to "Figure 1" in Word output
+ * - Auto-conversion back during import
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Patterns for detecting hardcoded references
+ * Matches: Figure 1, Fig. 1a, fig 1b-c, Figs. 1-3, Table S1, etc.
+ * Includes optional letter suffixes for sub-panels (a, b, c, etc.)
+ */
+const DETECTION_PATTERNS = {
+  // Figures: Fig, Fig., fig, figure, Figure, FIGURE, Figs, Figures (plural)
+  // With optional letter suffix: 1a, 1b, 2a-c, etc.
+  figure: /\b(Figures?|Figs?\.?)\s*(\d+|S\d+)([a-z])?(?:\s*[-–—&,]\s*(\d+|S\d+)?([a-z])?)?\b/gi,
+
+  // Tables: Tab, Tab., tab, table, Table, TABLE, Tabs, Tables (plural)
+  // With optional letter suffix for sub-tables
+  table: /\b(Tables?|Tabs?\.?)\s*(\d+|S\d+)([a-z])?(?:\s*[-–—&,]\s*(\d+|S\d+)?([a-z])?)?\b/gi,
+
+  // Equations: Eq, Eq., eq, equation, Equation
+  equation: /\b(Equations?|Eqs?\.?)\s*(\d+)([a-z])?(?:\s*[-–—&,]\s*(\d+)?([a-z])?)?\b/gi,
+};
+
+/**
+ * Pattern for extracting anchors from markdown: {#fig:label}, {#tbl:label}
+ */
+const ANCHOR_PATTERN = /\{#(fig|tbl|eq):([^}]+)\}/gi;
+
+/**
+ * Pattern for @-style references: @fig:label, @tbl:label
+ */
+const REF_PATTERN = /@(fig|tbl|eq):([a-zA-Z0-9_-]+)/gi;
+
+/**
+ * Normalize a reference type to standard form
+ * @param {string} typeStr - e.g., "Figure", "Fig.", "Figs", "table"
+ * @returns {string} - "fig", "tbl", or "eq"
+ */
+export function normalizeType(typeStr) {
+  const lower = typeStr.toLowerCase().replace(/\.$/, '');
+  if (lower.startsWith('fig')) return 'fig';
+  if (lower.startsWith('tab')) return 'tbl';
+  if (lower.startsWith('eq')) return 'eq';
+  return lower;
+}
+
+/**
+ * Parse a reference number, handling supplementary (S1, S2) and letter suffixes (1a, 1b)
+ * @param {string} numStr - e.g., "1", "S1", "S2", "1a", "S1b"
+ * @param {string} [suffix] - optional letter suffix already extracted
+ * @returns {{isSupp: boolean, num: number, suffix: string|null}}
+ */
+export function parseRefNumber(numStr, suffix = null) {
+  if (!numStr) return { isSupp: false, num: 0, suffix };
+  const isSupp = numStr.toUpperCase().startsWith('S');
+  const numPart = isSupp ? numStr.slice(1) : numStr;
+  // Extract suffix if embedded in numStr (e.g., "1a")
+  const match = numPart.match(/^(\d+)([a-z])?$/i);
+  const num = match ? parseInt(match[1], 10) : parseInt(numPart, 10);
+  const extractedSuffix = suffix || (match && match[2]) || null;
+  return { isSupp, num, suffix: extractedSuffix ? extractedSuffix.toLowerCase() : null };
+}
+
+/**
+ * Build a registry of figure/table labels from .md files
+ * Scans for {#fig:label} and {#tbl:label} anchors
+ *
+ * @param {string} directory - Directory containing .md files
+ * @param {string[]} [excludeFiles] - Files to exclude
+ * @returns {{
+ *   figures: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
+ *   tables: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
+ *   equations: Map<string, {label: string, num: number, file: string}>,
+ *   byNumber: {fig: Map<string, string>, tbl: Map<string, string>, eq: Map<string, string>}
+ * }}
+ */
+export function buildRegistry(directory, excludeFiles = ['paper.md', 'README.md', 'CLAUDE.md']) {
+  const figures = new Map();
+  const tables = new Map();
+  const equations = new Map();
+
+  // Counters for numbering (separate for main and supplementary)
+  let figNum = 0;
+  let figSuppNum = 0;
+  let tblNum = 0;
+  let tblSuppNum = 0;
+  let eqNum = 0;
+
+  // Get all .md files
+  const files = fs.readdirSync(directory).filter((f) => {
+    if (!f.endsWith('.md')) return false;
+    if (excludeFiles.some((e) => f.toLowerCase() === e.toLowerCase())) return false;
+    return true;
+  });
+
+  // Sort by likely document order (use sections.yaml if available)
+  let orderedFiles = files;
+  const sectionsPath = path.join(directory, 'sections.yaml');
+  if (fs.existsSync(sectionsPath)) {
+    try {
+      const yaml = require('js-yaml');
+      const config = yaml.load(fs.readFileSync(sectionsPath, 'utf-8'));
+      if (config.sections) {
+        const sectionOrder = Object.entries(config.sections)
+          .sort((a, b) => (a[1].order ?? 999) - (b[1].order ?? 999))
+          .map(([file]) => file);
+        orderedFiles = sectionOrder.filter((f) => files.includes(f));
+        // Add any remaining files not in sections.yaml
+        for (const f of files) {
+          if (!orderedFiles.includes(f)) orderedFiles.push(f);
+        }
+      }
+    } catch {
+      // Ignore yaml errors, use default order
+    }
+  }
+
+  // Determine if a file is supplementary
+  const isSupplementary = (filename) =>
+    filename.toLowerCase().includes('supp') || filename.toLowerCase().includes('appendix');
+
+  // Process each file in order
+  for (const file of orderedFiles) {
+    const filePath = path.join(directory, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const isSupp = isSupplementary(file);
+
+    // Find all anchors
+    let match;
+    ANCHOR_PATTERN.lastIndex = 0;
+    while ((match = ANCHOR_PATTERN.exec(content)) !== null) {
+      const type = match[1].toLowerCase();
+      const label = match[2];
+
+      if (type === 'fig') {
+        if (isSupp) {
+          figSuppNum++;
+          figures.set(label, { label, num: figSuppNum, isSupp: true, file });
+        } else {
+          figNum++;
+          figures.set(label, { label, num: figNum, isSupp: false, file });
+        }
+      } else if (type === 'tbl') {
+        if (isSupp) {
+          tblSuppNum++;
+          tables.set(label, { label, num: tblSuppNum, isSupp: true, file });
+        } else {
+          tblNum++;
+          tables.set(label, { label, num: tblNum, isSupp: false, file });
+        }
+      } else if (type === 'eq') {
+        eqNum++;
+        equations.set(label, { label, num: eqNum, file });
+      }
+    }
+  }
+
+  // Build reverse lookup: number → label
+  const byNumber = {
+    fig: new Map(),
+    figS: new Map(),
+    tbl: new Map(),
+    tblS: new Map(),
+    eq: new Map(),
+  };
+
+  for (const [label, info] of figures) {
+    const key = info.isSupp ? 'figS' : 'fig';
+    byNumber[key].set(info.num, label);
+  }
+  for (const [label, info] of tables) {
+    const key = info.isSupp ? 'tblS' : 'tbl';
+    byNumber[key].set(info.num, label);
+  }
+  for (const [label, info] of equations) {
+    byNumber.eq.set(info.num, label);
+  }
+
+  return { figures, tables, equations, byNumber };
+}
+
+/**
+ * Get the display string for a label (e.g., "Figure 1", "Table S2")
+ * @param {string} type - "fig", "tbl", "eq"
+ * @param {string} label
+ * @param {object} registry
+ * @returns {string|null}
+ */
+export function labelToDisplay(type, label, registry) {
+  const collection =
+    type === 'fig' ? registry.figures : type === 'tbl' ? registry.tables : registry.equations;
+
+  const info = collection.get(label);
+  if (!info) return null;
+
+  const prefix = type === 'fig' ? 'Figure' : type === 'tbl' ? 'Table' : 'Equation';
+  const numStr = info.isSupp ? `S${info.num}` : `${info.num}`;
+
+  return `${prefix} ${numStr}`;
+}
+
+/**
+ * Get the label for a display number (e.g., "fig:heatmap" from Figure 1)
+ * @param {string} type - "fig", "tbl", "eq"
+ * @param {number} num
+ * @param {boolean} isSupp
+ * @param {object} registry
+ * @returns {string|null}
+ */
+export function numberToLabel(type, num, isSupp, registry) {
+  const key = isSupp ? `${type}S` : type;
+  return registry.byNumber[key]?.get(num) || null;
+}
+
+/**
+ * Detect all hardcoded references in text
+ * @param {string} text
+ * @returns {Array<{type: string, match: string, numbers: Array<{num: number, isSupp: boolean, suffix: string|null}>, position: number}>}
+ */
+export function detectHardcodedRefs(text) {
+  const refs = [];
+
+  for (const [type, pattern] of Object.entries(DETECTION_PATTERNS)) {
+    pattern.lastIndex = 0;
+    let match;
+
+    while ((match = pattern.exec(text)) !== null) {
+      const numbers = [];
+
+      // Pattern groups:
+      // [1] = type (Figure, Fig., etc.)
+      // [2] = first number (1, S1)
+      // [3] = first suffix (a, b) - optional
+      // [4] = second number for range (2, S2) - optional
+      // [5] = second suffix (b, c) - optional
+
+      // Parse first number with optional suffix
+      const first = parseRefNumber(match[2], match[3]);
+      numbers.push(first);
+
+      // Parse second number/suffix if present (range like 1a-c or 1-3)
+      if (match[4] || match[5]) {
+        const second = parseRefNumber(match[4] || match[2], match[5]);
+
+        // Handle suffix-only ranges (e.g., "1a-c" means 1a, 1b, 1c)
+        if (!match[4] && match[5] && first.suffix) {
+          // Expand letter range: a-c → a, b, c
+          const startCode = first.suffix.charCodeAt(0);
+          const endCode = match[5].charCodeAt(0);
+          for (let code = startCode + 1; code <= endCode; code++) {
+            numbers.push({
+              num: first.num,
+              isSupp: first.isSupp,
+              suffix: String.fromCharCode(code)
+            });
+          }
+        } else if (match[4]) {
+          // Expand number range
+          if (first.isSupp === second.isSupp && !first.suffix && !second.suffix) {
+            for (let n = first.num + 1; n <= second.num; n++) {
+              numbers.push({ num: n, isSupp: first.isSupp, suffix: null });
+            }
+          } else {
+            numbers.push(second);
+          }
+        }
+      }
+
+      refs.push({
+        type: normalizeType(type),
+        match: match[0],
+        numbers,
+        position: match.index,
+      });
+    }
+  }
+
+  // Sort by position
+  refs.sort((a, b) => a.position - b.position);
+  return refs;
+}
+
+/**
+ * Convert hardcoded references to @-style references
+ * @param {string} text
+ * @param {object} registry
+ * @returns {{converted: string, conversions: Array<{from: string, to: string}>, warnings: string[]}}
+ */
+export function convertHardcodedRefs(text, registry) {
+  const refs = detectHardcodedRefs(text);
+  const conversions = [];
+  const warnings = [];
+
+  // Process in reverse order to preserve positions
+  let result = text;
+  for (let i = refs.length - 1; i >= 0; i--) {
+    const ref = refs[i];
+
+    // Build replacement
+    const labels = [];
+    for (const { num, isSupp } of ref.numbers) {
+      const label = numberToLabel(ref.type, num, isSupp, registry);
+      if (label) {
+        labels.push(`@${ref.type}:${label}`);
+      } else {
+        const displayNum = isSupp ? `S${num}` : `${num}`;
+        warnings.push(`Unknown reference: ${ref.type} ${displayNum} (no matching label)`);
+        labels.push(ref.match); // Keep original if no match
+      }
+    }
+
+    if (labels.length > 0 && !labels.includes(ref.match)) {
+      const replacement = labels.join('; ');
+      result = result.slice(0, ref.position) + replacement + result.slice(ref.position + ref.match.length);
+
+      conversions.push({
+        from: ref.match,
+        to: replacement,
+      });
+    }
+  }
+
+  return { converted: result, conversions, warnings };
+}
+
+/**
+ * Detect @-style references in text
+ * @param {string} text
+ * @returns {Array<{type: string, label: string, match: string, position: number}>}
+ */
+export function detectDynamicRefs(text) {
+  const refs = [];
+  REF_PATTERN.lastIndex = 0;
+  let match;
+
+  while ((match = REF_PATTERN.exec(text)) !== null) {
+    refs.push({
+      type: match[1],
+      label: match[2],
+      match: match[0],
+      position: match.index,
+    });
+  }
+
+  return refs;
+}
+
+/**
+ * Get reference status for a file/text
+ * @param {string} text
+ * @param {object} registry
+ * @returns {{
+ *   dynamic: Array,
+ *   hardcoded: Array,
+ *   anchors: {figures: number, tables: number, equations: number}
+ * }}
+ */
+export function getRefStatus(text, registry) {
+  const dynamic = detectDynamicRefs(text);
+  const hardcoded = detectHardcodedRefs(text);
+
+  // Count anchors in this text
+  ANCHOR_PATTERN.lastIndex = 0;
+  let figCount = 0,
+    tblCount = 0,
+    eqCount = 0;
+  let match;
+  while ((match = ANCHOR_PATTERN.exec(text)) !== null) {
+    if (match[1] === 'fig') figCount++;
+    else if (match[1] === 'tbl') tblCount++;
+    else if (match[1] === 'eq') eqCount++;
+  }
+
+  return {
+    dynamic,
+    hardcoded,
+    anchors: { figures: figCount, tables: tblCount, equations: eqCount },
+  };
+}
+
+/**
+ * Format registry for display
+ * @param {object} registry
+ * @returns {string}
+ */
+export function formatRegistry(registry) {
+  const lines = [];
+
+  if (registry.figures.size > 0) {
+    lines.push('Figures:');
+    for (const [label, info] of registry.figures) {
+      const num = info.isSupp ? `S${info.num}` : info.num;
+      lines.push(`  Figure ${num}: @fig:${label} (${info.file})`);
+    }
+  }
+
+  if (registry.tables.size > 0) {
+    if (lines.length > 0) lines.push('');
+    lines.push('Tables:');
+    for (const [label, info] of registry.tables) {
+      const num = info.isSupp ? `S${info.num}` : info.num;
+      lines.push(`  Table ${num}: @tbl:${label} (${info.file})`);
+    }
+  }
+
+  if (registry.equations.size > 0) {
+    if (lines.length > 0) lines.push('');
+    lines.push('Equations:');
+    for (const [label, info] of registry.equations) {
+      lines.push(`  Equation ${info.num}: @eq:${label} (${info.file})`);
+    }
+  }
+
+  if (lines.length === 0) {
+    lines.push('No figure/table anchors found.');
+  }
+
+  return lines.join('\n');
+}