docrev 0.10.0 → 0.10.2

package/lib/commands/sync.ts

@@ -10,7 +10,8 @@ import {
   path,
   fmt,
   findFiles,
-  loadConfig,
+  resolveSectionsConfig,
+  getOrderedSections,
   extractSectionsFromText,
   countAnnotations,
   buildRegistry,
@@ -18,6 +19,7 @@ import {
   inlineDiffPreview,
 } from './context.js';
 import type { Command } from 'commander';
+import type { SectionsConfig } from '../types.js';
 import * as readline from 'readline';
 
 interface ImportStats {
@@ -113,12 +115,11 @@ export function register(program: Command): void {
           console.log(chalk.dim(`Total: ${stats.total} comments from ${authorList}`));
           console.log();
 
-          const configPath = path.resolve(options.dir, options.config);
-          if (fs.existsSync(configPath) && !options.dryRun) {
-            const config = loadConfig(configPath);
-            const mainSection = config.sections?.[0];
+          const resolved = resolveSectionsConfig(options.dir, options.config);
+          if (resolved && !options.dryRun) {
+            const mainSection = getOrderedSections(resolved.config)[0];
 
-            if (mainSection && typeof mainSection === 'string') {
+            if (mainSection) {
               const mainPath = path.join(options.dir, mainSection);
               if (fs.existsSync(mainPath)) {
                 console.log(chalk.dim(`Use 'rev pdf-comments ${docx} --append ${mainSection}' to add comments to markdown.`));
@@ -135,18 +136,21 @@ export function register(program: Command): void {
         return;
       }
 
-      const configPath = path.resolve(options.dir, options.config);
-      if (!fs.existsSync(configPath)) {
-        console.error(fmt.status('error', `Config not found: ${configPath}`));
-        console.error(chalk.dim('  Run "rev init" first to generate sections.yaml'));
+      // Resolve the section config: an explicit sections.yaml if present,
+      // otherwise the `sections:` list in rev.yaml (single source of truth).
+      const resolved = resolveSectionsConfig(options.dir, options.config);
+      if (!resolved) {
+        console.error(fmt.status('error', `No section config found in ${path.resolve(options.dir)}`));
+        console.error(chalk.dim('  Add a `sections:` list to rev.yaml, or run "rev init" to generate sections.yaml.'));
         process.exit(1);
       }
+      const sectionsConfig = resolved.config;
 
       // --comments-only: import comments only, never modify existing prose.
       // Use this when the markdown has been revised since the docx was sent
       // out — track changes from a stale draft would clobber newer edits.
       if (options.commentsOnly) {
-        await syncCommentsOnly(docx, sections, options, configPath);
+        await syncCommentsOnly(docx, sections, options, sectionsConfig);
         return;
       }
 
@@ -161,8 +165,9 @@ export function register(program: Command): void {
       const spin = fmt.spinner(`Importing ${path.basename(docx)}...`).start();
 
       try {
-        const config = loadConfig(configPath);
-        const { importFromWord, extractWordComments, extractCommentAnchors, insertCommentsIntoMarkdown, extractFromWord } = await import('../import.js');
+        const config = sectionsConfig;
+        const { importFromWord, extractWordComments, extractCommentAnchors, insertCommentsIntoMarkdown, extractFromWord, extractHeadings } = await import('../import.js');
+        const { computeSectionBoundaries } = await import('./section-boundaries.js');
 
         let registry = null;
         let totalRefConversions = 0;
@@ -283,91 +288,50 @@ export function register(program: Command): void {
         }> = [];
         let totalChanges = 0;
 
-        // Calculate section boundaries in the XML document text for comment filtering
-        // Comment positions (docPosition) are relative to xmlDocText, NOT wordText
-        // So we must find section headers in xmlDocText to get matching boundaries
-        const sectionBoundaries: Array<{ file: string; start: number; end: number }> = [];
-        const xmlLower = xmlDocText.toLowerCase();
-
-        // Standard section header keywords to search for in XML
-        // Map from file name pattern to search terms
-        const sectionKeywords: Record<string, string[]> = {
-          'abstract': ['abstract', 'summary'],
-          'introduction': ['introduction', 'background'],
-          'methods': ['methods', 'materials and methods', 'methodology'],
-          'results': ['results'],
-          'discussion': ['discussion'],
-          'conclusion': ['conclusion', 'conclusions'],
-        };
-
-        // Helper: find section header (skip labels like "Methods:" in structured abstracts)
-        // Real section headers are NOT followed by ":" immediately
-        function findSectionHeader(text: string, keyword: string, startFrom: number = 0): number {
-          const lower = text.toLowerCase();
-          let idx = startFrom;
-          while ((idx = lower.indexOf(keyword, idx)) !== -1) {
-            // Check what follows the keyword
-            const afterKeyword = text.slice(idx + keyword.length, idx + keyword.length + 5);
-            // Skip if followed by ":" (this is a label, not a section header)
-            // Real headers are followed by text content, a newline, or a subheading
-            if (!afterKeyword.startsWith(':') && !afterKeyword.startsWith(' :')) {
-              return idx;
-            }
-            idx++;
-          }
-          return -1;
-        }
+        // Route comments to sections using boundaries from the document's real
+        // heading paragraphs. docPosition (from extractCommentAnchors) and each
+        // heading's docPosition share one coordinate system over xmlDocText, so
+        // every configured section gets a boundary — not only the handful that
+        // matched a hardcoded keyword list. Sections named "Objectives" or
+        // "Annex 2" used to get no boundary, so their comments were silently
+        // dropped while the summary still claimed every comment was placed.
+        // This is the same routing path as `sync --comments-only`.
+        const headings = await extractHeadings(docx);
+        const sectionBoundaries = computeSectionBoundaries(config.sections, headings, xmlDocText.length);
+        const firstBoundaryStart = sectionBoundaries.length > 0 ? sectionBoundaries[0].start : 0;
+
+        // Truthful comment accounting: track which comments were routed to a
+        // synced section and how many were actually written, so the summary
+        // reports placements rather than the raw extracted count.
+        const routedCommentIds = new Set<string>();
+        let totalCommentsPlaced = 0;
+        let totalCommentsDeduped = 0;
+        let totalCommentsUnmatched = 0;
 
         for (const section of wordSections) {
-          const fileBase = section.file.replace(/\.md$/i, '').toLowerCase();
-
-          // Get keywords for this section
-          const keywords = sectionKeywords[fileBase] || [fileBase];
-
-          // Find the first valid keyword that exists in XML (not a label)
-          let headerIdx = -1;
-          for (const kw of keywords) {
-            const idx = findSectionHeader(xmlDocText, kw, 0);
-            if (idx >= 0 && (headerIdx < 0 || idx < headerIdx)) {
-              headerIdx = idx;
-            }
-          }
-
-          if (headerIdx >= 0) {
-            // Find the next section's start to determine end boundary
-            let nextHeaderIdx = xmlDocText.length;
-            const sectionIdx = wordSections.indexOf(section);
-            if (sectionIdx < wordSections.length - 1) {
-              const nextFileBase = wordSections[sectionIdx + 1].file.replace(/\.md$/i, '').toLowerCase();
-              const nextKeywords = sectionKeywords[nextFileBase] || [nextFileBase];
-              for (const nkw of nextKeywords) {
-                const foundNext = findSectionHeader(xmlDocText, nkw, headerIdx + 10);
-                if (foundNext >= 0 && foundNext < nextHeaderIdx) {
-                  nextHeaderIdx = foundNext;
-                }
-              }
-            }
+          const sectionPath = path.join(options.dir, section.file);
 
-            sectionBoundaries.push({
+          if (!fs.existsSync(sectionPath)) {
+            sectionResults.push({
               file: section.file,
-              start: headerIdx,
-              end: nextHeaderIdx
+              header: section.header,
+              status: 'skipped',
+              stats: undefined,
             });
-
+            continue;
           }
-        }
 
-        // Document length is the XML text length (same coordinate system as docPosition)
-        const docLength = xmlDocText.length;
-
-        for (const section of wordSections) {
-          const sectionPath = path.join(options.dir, section.file);
-
-          if (!fs.existsSync(sectionPath)) {
+          // A section that appears in the reviewed document as a bare heading
+          // with no body was not really part of this build (e.g. a "no-annex"
+          // export synced against the full project). Importing it would diff
+          // real prose against an empty body and rewrite the file to near-empty.
+          // Leave it untouched.
+          const bodyEmpty = section.content.trim() === section.header.trim();
+          if (bodyEmpty) {
             sectionResults.push({
               file: section.file,
               header: section.header,
-              status: 'skipped',
+              status: 'untouched',
               stats: undefined,
             });
             continue;
@@ -389,31 +353,19 @@ export function register(program: Command): void {
             totalRefConversions += refConversions.length;
           }
 
-          let commentsInserted = 0;
           if (comments.length > 0 && anchors.size > 0) {
-            // Filter comments to only those that belong to this section
-            // Use exact position matching: docPosition is in xmlDocText coordinates,
-            // and sectionBoundaries are also in xmlDocText coordinates (same source!)
+            // Filter comments to those whose docPosition falls in this section's
+            // boundary (docPosition and boundaries share xmlDocText coordinates).
+            // The section owning the first boundary also catches comments placed
+            // before any heading.
             const boundary = sectionBoundaries.find(b => b.file === section.file);
-            const isFirstSection = wordSections.indexOf(section) === 0;
-            const firstBoundaryStart = sectionBoundaries.length > 0 ? Math.min(...sectionBoundaries.map(b => b.start)) : 0;
+            const ownsFirstBoundary = !!boundary && boundary.start === firstBoundaryStart;
 
-            const sectionComments = comments.filter((c: any) => {
+            const sectionComments = comments.filter((c: { id: string }) => {
               const anchorData = anchors.get(c.id);
-              if (!anchorData) return false;
-
-              // Use exact position - no scaling needed since both are in xmlDocText coordinates
-              if (anchorData.docPosition !== undefined && boundary) {
-                // Include comments within section boundaries
-                if (anchorData.docPosition >= boundary.start && anchorData.docPosition < boundary.end) {
-                  return true;
-                }
-                // Also include "outside" comments (before first section) in the first section file
-                if (isFirstSection && anchorData.docPosition < firstBoundaryStart) {
-                  return true;
-                }
-              }
-
+              if (!anchorData || anchorData.docPosition === undefined || !boundary) return false;
+              if (anchorData.docPosition >= boundary.start && anchorData.docPosition < boundary.end) return true;
+              if (ownsFirstBoundary && anchorData.docPosition < firstBoundaryStart) return true;
               return false;
             });
 
@@ -422,22 +374,20 @@ export function register(program: Command): void {
             }
 
             if (sectionComments.length > 0) {
-              // Use a more robust pattern that handles < in comment text
-              const commentPattern = /\{>>.*?<<\}/gs;
-              const beforeCount = (annotated.match(commentPattern) || []).length;
+              for (const c of sectionComments) routedCommentIds.add(c.id);
+              const cstats = { placed: 0, deduped: 0, unmatched: 0 };
               annotated = insertCommentsIntoMarkdown(annotated, sectionComments, anchors, {
                 quiet: !process.env.DEBUG,
-                sectionBoundary: boundary  // Pass section boundary for position-based insertion
+                sectionBoundary: boundary,
+                outStats: cstats,
               });
-              const afterCount = (annotated.match(commentPattern) || []).length;
-              commentsInserted = afterCount - beforeCount;
+              stats.comments = (stats.comments || 0) + cstats.placed;
+              totalCommentsPlaced += cstats.placed;
+              totalCommentsDeduped += cstats.deduped;
+              totalCommentsUnmatched += cstats.unmatched;
 
               if (process.env.DEBUG) {
-                console.log(`[DEBUG] ${section.file}: inserted ${commentsInserted} of ${sectionComments.length} comments`);
-              }
-
-              if (commentsInserted > 0) {
-                stats.comments = (stats.comments || 0) + commentsInserted;
+                console.log(`[DEBUG] ${section.file}: placed ${cstats.placed}, deduped ${cstats.deduped}, unmatched ${cstats.unmatched} of ${sectionComments.length}`);
               }
             }
           }
@@ -471,11 +421,11 @@ export function register(program: Command): void {
         }
 
         const tableRows = sectionResults.map((r) => {
-          if (r.status === 'skipped') {
+          if (r.status === 'skipped' || r.status === 'untouched') {
             return [
               chalk.dim(r.file),
               chalk.dim(r.header.slice(0, 25)),
-              chalk.yellow('skipped'),
+              chalk.yellow(r.status),
               '',
               '',
               '',
@@ -520,17 +470,38 @@ export function register(program: Command): void {
           }
         }
 
+        // Comments carried by the document but never routed to a synced section
+        // (they fell in a skipped/untouched/absent section). Surfacing these
+        // keeps the summary honest instead of reporting every extracted comment
+        // as placed.
+        const unroutedComments = comments.length - routedCommentIds.size;
+
         if (options.dryRun) {
           console.log(fmt.box(chalk.yellow('Dry run - no files written'), { padding: 0 }));
         } else if (totalChanges > 0 || totalRefConversions > 0 || comments.length > 0) {
           const summaryLines: string[] = [];
           summaryLines.push(`${chalk.bold(wordSections.length)} sections processed`);
           if (totalChanges > 0) summaryLines.push(`${chalk.bold(totalChanges)} annotations imported`);
-          if (comments.length > 0) summaryLines.push(`${chalk.bold(comments.length)} comments placed`);
+          if (totalCommentsPlaced > 0) {
+            summaryLines.push(`${chalk.bold(totalCommentsPlaced)} of ${comments.length} comments placed`);
+          }
+          if (totalCommentsDeduped > 0) {
+            summaryLines.push(`${chalk.cyan(totalCommentsDeduped)} already present (skipped)`);
+          }
+          if (totalCommentsUnmatched > 0) {
+            summaryLines.push(`${chalk.yellow(totalCommentsUnmatched)} unmatched (anchor not in current prose)`);
+          }
+          if (unroutedComments > 0) {
+            summaryLines.push(`${chalk.yellow(unroutedComments)} not routed to any synced section`);
+          }
           if (totalRefConversions > 0) summaryLines.push(`${chalk.bold(totalRefConversions)} refs converted to @-syntax`);
 
           console.log(fmt.box(summaryLines.join('\n'), { title: 'Summary', padding: 0 }));
           console.log();
+          if (totalCommentsUnmatched > 0 || unroutedComments > 0) {
+            console.log(chalk.yellow(`  ${totalCommentsUnmatched + unroutedComments} comment(s) were not written. Run "rev verify-anchors" or re-sync with the full document.`));
+            console.log();
+          }
           console.log(chalk.dim('Next steps:'));
           console.log(chalk.dim('  1. rev review <section.md>  - Accept/reject changes'));
           console.log(chalk.dim('  2. rev comments <section.md> - View/address comments'));
@@ -560,9 +531,8 @@ async function syncCommentsOnly(
   docx: string,
   sectionFilter: string[] | undefined,
   options: SyncOptions,
-  configPath: string,
+  config: SectionsConfig,
 ): Promise<void> {
-  const config = loadConfig(configPath);
   const { extractWordComments, extractCommentAnchors, extractHeadings, insertCommentsIntoMarkdown } = await import('../import.js');
   const { computeSectionBoundaries } = await import('./section-boundaries.js');
 

package/lib/commands/verify-anchors.ts

@@ -18,7 +18,7 @@ import {
   fs,
   path,
   fmt,
-  loadConfig,
+  resolveSectionsConfig,
   jsonMode,
   jsonOutput,
 } from './context.js';
@@ -58,14 +58,14 @@ export function register(program: Command): void {
         process.exit(1);
       }
 
-      const configPath = path.resolve(options.dir, options.config);
-      if (!fs.existsSync(configPath)) {
-        console.error(fmt.status('error', `Config not found: ${configPath}`));
-        console.error(chalk.dim('  Run "rev init" first to generate sections.yaml'));
+      const resolved = resolveSectionsConfig(options.dir, options.config);
+      if (!resolved) {
+        console.error(fmt.status('error', `No section config found in ${path.resolve(options.dir)}`));
+        console.error(chalk.dim('  Add a `sections:` list to rev.yaml, or run "rev init" to generate sections.yaml.'));
         process.exit(1);
       }
 
-      const config = loadConfig(configPath);
+      const config = resolved.config;
       const { extractWordComments, extractCommentAnchors, extractHeadings } = await import('../import.js');
 
       let comments;

package/lib/sections.ts

@@ -47,6 +47,28 @@ export function extractHeader(filePath: string): string | null {
   return null;
 }
 
+/**
+ * Extract the first markdown heading of ANY level (`#`–`######`) from a file.
+ *
+ * Unlike {@link extractHeader} (which is H1-only by contract), this is used to
+ * derive a section's header from files that lead with a subsection — e.g.
+ * `02_objectives.md` starting with `## 1.2 Objectives`. Using the real first
+ * heading lets the derived header match the corresponding docx heading.
+ */
+export function extractFirstHeading(filePath: string): string | null {
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const match = line.match(/^#{1,6}\s+(.+)$/);
+    if (match && match[1]) {
+      return match[1].trim();
+    }
+  }
+
+  return null;
+}
+
 /**
  * Generate sections.yaml from existing .md files
  */
@@ -64,7 +86,10 @@ export function generateConfig(
 
   for (const file of files) {
     const filePath = path.join(directory, file);
-    const header = extractHeader(filePath);
+    // Use the first heading at any level: a section file may be headed by a
+    // subsection (## 1.2 Objectives). H1-only extraction left such files with a
+    // filename-derived header that never matched the reviewed document.
+    const header = extractFirstHeading(filePath);
     const baseName = path.basename(file, '.md').toLowerCase();
 
     // Determine order based on common patterns
@@ -144,6 +169,74 @@ export function saveConfig(configPath: string, config: SectionsConfig): void {
   fs.writeFileSync(configPath, yamlStr, 'utf-8');
 }
 
+/**
+ * Derive a SectionsConfig from the `sections:` list in rev.yaml.
+ *
+ * Each listed file's header is its first markdown H1 (falling back to a
+ * title-cased file name); order follows the list order in rev.yaml. This is
+ * the same section list that `build` consumes, so a project that only has a
+ * `rev.yaml` needs no separate `sections.yaml`.
+ *
+ * Returns null when rev.yaml is absent, unparseable, or has no `sections` list.
+ */
+export function deriveSectionsFromRev(directory: string): SectionsConfig | null {
+  const revPath = path.join(directory, 'rev.yaml');
+  if (!fs.existsSync(revPath)) return null;
+
+  let parsed: { sections?: unknown };
+  try {
+    parsed = YAML.parse(fs.readFileSync(revPath, 'utf-8')) || {};
+  } catch {
+    return null;
+  }
+
+  const list = parsed.sections;
+  if (!Array.isArray(list) || list.length === 0) return null;
+
+  const sections: Record<string, SectionConfig> = {};
+  list.forEach((entry, index) => {
+    if (typeof entry !== 'string') return;
+    const header = extractFirstHeading(path.join(directory, entry)) || titleCase(path.basename(entry, '.md'));
+    sections[entry] = { header, aliases: [], order: index };
+  });
+
+  if (Object.keys(sections).length === 0) return null;
+
+  return {
+    version: 1,
+    description: 'Derived from rev.yaml sections list',
+    sections,
+  };
+}
+
+/**
+ * Resolve the effective sections config for a project directory.
+ *
+ * Precedence (single source of truth, with optional override):
+ *   1. An explicit sections config file (default `sections.yaml`) when it
+ *      exists — lets users override headers/aliases/order.
+ *   2. Otherwise the `sections:` list in `rev.yaml`, via {@link deriveSectionsFromRev}.
+ *
+ * Returns null only when neither source yields any sections; callers turn that
+ * into a user-facing error.
+ */
+export function resolveSectionsConfig(
+  directory: string,
+  configFileName = 'sections.yaml'
+): { config: SectionsConfig; source: string } | null {
+  const explicitPath = path.resolve(directory, configFileName);
+  if (fs.existsSync(explicitPath)) {
+    return { config: loadConfig(explicitPath), source: explicitPath };
+  }
+
+  const derived = deriveSectionsFromRev(directory);
+  if (derived) {
+    return { config: derived, source: path.resolve(directory, 'rev.yaml') };
+  }
+
+  return null;
+}
+
 /**
  * Match a heading to a section file
  */
@@ -286,7 +379,7 @@ export function splitAnnotatedPaper(
     let currentContent: string[] = [];
 
     for (const line of lines) {
-      const headerMatch = line.match(/^#\s+(.+)$/);
+      const headerMatch = line.match(/^#{1,6}\s+(.+)$/);
 
       if (headerMatch && headerMatch[1]) {
         // Save previous section

package/mkdocs.yml

@@ -1,64 +1,64 @@
-site_name: docrev
-site_url: https://gillescolling.com/docrev
-site_description: CLI for writing documents in Markdown while collaborating with Word users.
-site_author: Gilles Colling
-repo_url: https://github.com/gcol33/docrev
-repo_name: gcol33/docrev
-
-theme:
-  name: material
-  palette:
-    - scheme: default
-      primary: custom
-      accent: custom
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      primary: custom
-      accent: custom
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-  font:
-    text: Roboto
-    code: Roboto Mono
-  features:
-    - navigation.tabs
-    - navigation.top
-    - navigation.instant
-    - search.highlight
-    - content.code.copy
-  icon:
-    repo: fontawesome/brands/github
-
-nav:
-  - Home: index.md
-  - Get Started: workflow.md
-  - Commands: commands.md
-  - Configuration: configuration.md
-  - Troubleshooting: troubleshooting.md
-
-markdown_extensions:
-  - pymdownx.highlight:
-      anchor_linenums: true
-  - pymdownx.superfences
-  - pymdownx.inlinehilite
-  - pymdownx.tabbed:
-      alternate_style: true
-  - admonition
-  - pymdownx.details
-  - attr_list
-  - md_in_html
-  - toc:
-      permalink: true
-
-extra_css:
-  - stylesheets/extra.css
-
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/gcol33/docrev
-    - icon: fontawesome/brands/npm
-      link: https://www.npmjs.com/package/docrev
+site_name: docrev
+site_url: https://gillescolling.com/docrev
+site_description: CLI for writing documents in Markdown while collaborating with Word users.
+site_author: Gilles Colling
+repo_url: https://github.com/gcol33/docrev
+repo_name: gcol33/docrev
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+  features:
+    - navigation.tabs
+    - navigation.top
+    - navigation.instant
+    - search.highlight
+    - content.code.copy
+  icon:
+    repo: fontawesome/brands/github
+
+nav:
+  - Home: index.md
+  - Get Started: workflow.md
+  - Commands: commands.md
+  - Configuration: configuration.md
+  - Troubleshooting: troubleshooting.md
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+extra_css:
+  - stylesheets/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/gcol33/docrev
+    - icon: fontawesome/brands/npm
+      link: https://www.npmjs.com/package/docrev

package/package.json

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