docrev 0.7.7 → 0.7.8

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);
+    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');
@@ -520,10 +561,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 +587,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 +615,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

@@ -489,6 +489,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.8",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",