docrev 0.7.7 → 0.7.9

package/README.md

@@ -157,10 +157,25 @@ my-report/
 Write your content in the markdown files. When ready to share:
 
 ```bash
-rev build docx
+rev build docx pdf
 ```
 
-This produces `my-report.docx` with citations resolved, equations rendered, and cross-references numbered. Use `rev build pdf` for PDF output instead.
+After building, your project structure looks like:
+
+```
+my-report/
+├── intro.md
+├── methods.md
+├── results.md
+├── discussion.md
+├── references.bib
+├── rev.yaml
+├── paper.md              ← combined sections (auto-generated)
+├── my-report.docx        ← output for collaborators
+└── my-report.pdf         ← output for journals
+```
+
+The output filename is derived from your project title in `rev.yaml`. Citations are resolved, equations rendered, and cross-references numbered.
 
 ### Starting from an Existing Word Document
 

package/lib/build.js

@@ -13,7 +13,7 @@ import * as path from 'path';
 import { execSync, spawn } from 'child_process';
 import YAML from 'yaml';
 import { stripAnnotations } from './annotations.js';
-import { buildRegistry, labelToDisplay, detectDynamicRefs } from './crossref.js';
+import { buildRegistry, labelToDisplay, detectDynamicRefs, resolveForwardRefs } from './crossref.js';
 import { processVariables, hasVariables } from './variables.js';
 
 /**
@@ -160,8 +160,22 @@ export function combineSections(directory, config, options = {}) {
   // Read all section contents for variable processing
   const sectionContents = [];
 
+  // Check if we need to auto-inject references before supplementary
+  // Pandoc places refs at the end by default, which breaks when supplementary follows
+  const hasRefsSection = sections.some(s =>
+    s.toLowerCase().includes('reference') || s.toLowerCase().includes('refs')
+  );
+  const suppIndex = sections.findIndex(s =>
+    s.toLowerCase().includes('supp') || s.toLowerCase().includes('appendix')
+  );
+  const hasBibliography = config.bibliography && fs.existsSync(path.join(directory, config.bibliography));
+
+  // Track if we find an explicit refs div in any section
+  let hasExplicitRefsDiv = false;
+
   // Combine sections
-  for (const section of sections) {
+  for (let i = 0; i < sections.length; i++) {
+    const section = sections[i];
     const filePath = path.join(directory, section);
     let content = fs.readFileSync(filePath, 'utf-8');
 
@@ -169,6 +183,21 @@ export function combineSections(directory, config, options = {}) {
     content = stripFrontmatter(content);
     sectionContents.push(content);
 
+    // Check if this section has an explicit refs div
+    if (content.includes('::: {#refs}') || content.includes(':::  {#refs}')) {
+      hasExplicitRefsDiv = true;
+    }
+
+    // Auto-inject references before supplementary if needed
+    if (i === suppIndex && hasBibliography && !hasRefsSection && !hasExplicitRefsDiv) {
+      parts.push('# References\n');
+      parts.push('::: {#refs}');
+      parts.push(':::');
+      parts.push('');
+      parts.push('');
+      options._refsAutoInjected = true;
+    }
+
     parts.push(content.trim());
     parts.push('');
     parts.push(''); // Double newline between sections
@@ -181,6 +210,18 @@ export function combineSections(directory, config, options = {}) {
     paperContent = processVariables(paperContent, config, { sectionContents });
   }
 
+  // Resolve forward references (refs that appear before their anchor definition)
+  // This fixes pandoc-crossref limitation with multi-file documents
+  if (hasPandocCrossref()) {
+    const registry = buildRegistry(directory, sections);
+    const { text, resolved } = resolveForwardRefs(paperContent, registry);
+    if (resolved.length > 0) {
+      paperContent = text;
+      // Store resolved count for optional reporting
+      options._forwardRefsResolved = resolved.length;
+    }
+  }
+
   const paperPath = path.join(directory, 'paper.md');
 
   fs.writeFileSync(paperPath, paperContent, 'utf-8');
@@ -239,7 +280,8 @@ export function prepareForFormat(paperPath, format, config, options = {}) {
   let content = fs.readFileSync(paperPath, 'utf-8');
 
   // Build crossref registry for reference conversion
-  const registry = buildRegistry(directory);
+  // Pass sections from config to ensure correct file ordering
+  const registry = buildRegistry(directory, config.sections);
 
   if (format === 'pdf' || format === 'tex') {
     // Strip all annotations for clean output
@@ -520,10 +562,11 @@ export async function runPandoc(inputPath, format, config, options = {}) {
  * @param {string} directory
  * @param {string[]} formats - ['pdf', 'docx', 'tex'] or ['all']
  * @param {object} options
- * @returns {Promise<{results: object[], paperPath: string, warnings: string[]}>}
+ * @returns {Promise<{results: object[], paperPath: string, warnings: string[], forwardRefsResolved: number}>}
  */
 export async function build(directory, formats = ['pdf', 'docx'], options = {}) {
   const warnings = [];
+  let forwardRefsResolved = 0;
 
   // Check pandoc
   if (!hasPandoc()) {
@@ -545,7 +588,10 @@ export async function build(directory, formats = ['pdf', 'docx'], options = {})
   const config = options.config || loadConfig(directory);
 
   // Combine sections → paper.md
-  const paperPath = combineSections(directory, config, options);
+  const buildOptions = { ...options };
+  const paperPath = combineSections(directory, config, buildOptions);
+  forwardRefsResolved = buildOptions._forwardRefsResolved || 0;
+  const refsAutoInjected = buildOptions._refsAutoInjected || false;
 
   // Expand 'all' to all formats
   if (formats.includes('all')) {
@@ -570,7 +616,7 @@ export async function build(directory, formats = ['pdf', 'docx'], options = {})
     }
   }
 
-  return { results, paperPath, warnings };
+  return { results, paperPath, warnings, forwardRefsResolved, refsAutoInjected };
 }
 
 /**

package/lib/commands/build.js

@@ -17,7 +17,7 @@ import {
   getRefStatus,
   formatRegistry,
   build,
-  loadConfig as loadBuildConfig,
+  loadBuildConfig,
   hasPandoc,
   hasPandocCrossref,
   formatBuildResults,
@@ -555,7 +555,7 @@ export function register(program, pkg) {
       const spin = fmt.spinner('Building...').start();
 
       try {
-        const { results, paperPath } = await build(dir, targetFormats, {
+        const { results, paperPath, forwardRefsResolved, refsAutoInjected } = await build(dir, targetFormats, {
           crossref: options.crossref,
           config,
         });
@@ -563,7 +563,14 @@ export function register(program, pkg) {
         spin.stop();
 
         console.log(chalk.cyan('Combined sections → paper.md'));
-        console.log(chalk.dim(`  ${paperPath}\n`));
+        console.log(chalk.dim(`  ${paperPath}`));
+        if (forwardRefsResolved > 0) {
+          console.log(chalk.dim(`  ${forwardRefsResolved} forward reference(s) pre-resolved`));
+        }
+        if (refsAutoInjected) {
+          console.log(chalk.dim(`  References section auto-injected before supplementary`));
+        }
+        console.log('');
 
         console.log(chalk.cyan('Output:'));
         console.log(formatBuildResults(results));

package/lib/crossref.js

@@ -11,6 +11,49 @@ import * as fs from 'fs';
 import * as path from 'path';
 import YAML from 'yaml';
 
+/**
+ * Discover section files from a directory by reading config files
+ * Only returns files explicitly defined in rev.yaml or sections.yaml
+ * Returns empty array if no config found (caller should handle this)
+ *
+ * @param {string} directory
+ * @returns {string[]} Ordered list of section filenames, or empty if no config
+ */
+function discoverSectionFiles(directory) {
+  // Try rev.yaml first
+  const revYamlPath = path.join(directory, 'rev.yaml');
+  if (fs.existsSync(revYamlPath)) {
+    try {
+      const config = YAML.parse(fs.readFileSync(revYamlPath, 'utf-8'));
+      if (config.sections && Array.isArray(config.sections) && config.sections.length > 0) {
+        return config.sections.filter(f => fs.existsSync(path.join(directory, f)));
+      }
+    } catch {
+      // Ignore yaml errors, try next option
+    }
+  }
+
+  // Try sections.yaml
+  const sectionsPath = path.join(directory, 'sections.yaml');
+  if (fs.existsSync(sectionsPath)) {
+    try {
+      const config = YAML.parse(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);
+        return sectionOrder.filter(f => fs.existsSync(path.join(directory, f)));
+      }
+    } catch {
+      // Ignore yaml errors
+    }
+  }
+
+  // No config found - return empty array
+  // Caller must handle this (either error or use explicit sections)
+  return [];
+}
+
 /**
  * Patterns for detecting hardcoded references
  * Matches complex patterns including:
@@ -208,8 +251,14 @@ export function parseReferenceList(listStr) {
  * Build a registry of figure/table labels from .md files
  * Scans for {#fig:label} and {#tbl:label} anchors
  *
+ * IMPORTANT: This function requires either explicit sections or a rev.yaml/sections.yaml config.
+ * It will NOT guess by scanning all .md files, as this leads to incorrect numbering
+ * when temporary files (paper_clean.md, etc.) exist in the directory.
+ *
  * @param {string} directory - Directory containing .md files
- * @param {string[]} [excludeFiles] - Files to exclude
+ * @param {string[]} [sections] - Array of section filenames to scan (recommended).
+ *   If not provided, reads from rev.yaml or sections.yaml.
+ *   Returns empty registry if no sections can be determined.
  * @returns {{
  *   figures: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
  *   tables: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
@@ -217,7 +266,7 @@ export function parseReferenceList(listStr) {
  *   byNumber: {fig: Map<string, string>, tbl: Map<string, string>, eq: Map<string, string>}
  * }}
  */
-export function buildRegistry(directory, excludeFiles = ['paper.md', 'README.md', 'CLAUDE.md']) {
+export function buildRegistry(directory, sections) {
   const figures = new Map();
   const tables = new Map();
   const equations = new Map();
@@ -229,32 +278,16 @@ export function buildRegistry(directory, excludeFiles = ['paper.md', 'README.md'
   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;
-  });
+  let orderedFiles;
 
-  // 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 config = YAML.parse(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
-    }
+  if (Array.isArray(sections) && sections.length > 0) {
+    // Use explicitly provided section files - most reliable
+    orderedFiles = sections.filter(f => fs.existsSync(path.join(directory, f)));
+  } else {
+    // Try to determine sections from config files (rev.yaml or sections.yaml)
+    orderedFiles = discoverSectionFiles(directory);
+    // If no config found, return empty registry rather than guessing
+    // This prevents bugs from scanning wrong files
   }
 
   // Determine if a file is supplementary
@@ -489,6 +522,88 @@ export function getRefStatus(text, registry) {
   };
 }
 
+/**
+ * Detect forward references in combined text
+ * A forward reference is a @ref that appears before its {#anchor} definition
+ *
+ * @param {string} text - Combined document text
+ * @returns {{
+ *   forwardRefs: Array<{type: string, label: string, match: string, position: number}>,
+ *   anchorPositions: Map<string, number>
+ * }}
+ */
+export function detectForwardRefs(text) {
+  // Build map of anchor positions: "fig:label" -> position
+  const anchorPositions = new Map();
+  ANCHOR_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = ANCHOR_PATTERN.exec(text)) !== null) {
+    const key = `${match[1]}:${match[2]}`;
+    // Only store first occurrence (in case of duplicates)
+    if (!anchorPositions.has(key)) {
+      anchorPositions.set(key, match.index);
+    }
+  }
+
+  // Find all references
+  const refs = detectDynamicRefs(text);
+
+  // Filter to only forward references
+  const forwardRefs = refs.filter((ref) => {
+    const key = `${ref.type}:${ref.label}`;
+    const anchorPos = anchorPositions.get(key);
+    // Forward ref if anchor doesn't exist or appears after the reference
+    return anchorPos === undefined || ref.position < anchorPos;
+  });
+
+  return { forwardRefs, anchorPositions };
+}
+
+/**
+ * Resolve forward references to display format
+ * Only resolves refs that appear before their anchor definition
+ * Leaves other refs for pandoc-crossref to handle (preserves clickable links)
+ *
+ * @param {string} text - Combined document text
+ * @param {object} registry - Registry from buildRegistry()
+ * @returns {{
+ *   text: string,
+ *   resolved: Array<{from: string, to: string, position: number}>,
+ *   unresolved: Array<{ref: string, position: number}>
+ * }}
+ */
+export function resolveForwardRefs(text, registry) {
+  const { forwardRefs } = detectForwardRefs(text);
+  const resolved = [];
+  const unresolved = [];
+
+  // Process in reverse order to preserve positions
+  let result = text;
+  for (let i = forwardRefs.length - 1; i >= 0; i--) {
+    const ref = forwardRefs[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);
+      resolved.push({
+        from: ref.match,
+        to: display,
+        position: ref.position,
+      });
+    } else {
+      unresolved.push({
+        ref: ref.match,
+        position: ref.position,
+      });
+    }
+  }
+
+  return { text: result, resolved, unresolved };
+}
+
 /**
  * Format registry for display
  * @param {object} registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docrev",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",