@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/pipeline/list-generation.js

@@ -6,8 +6,11 @@ import { preprocessMarkdown } from './markdown-processor.js';
 import { matchListMarker, stripListMarker } from './list-markers.js';
 import { serializeToOoxml } from './serialization.js';
 import { generateTableOoxml } from '../services/table-reconciliation.js';
-import { parseTable } from './content-analysis.js';
-import { log } from '../adapters/logger.js';
+import { parseTable } from './content-analysis.js';
+import { log } from '../adapters/logger.js';
+import { createRevisionMetadata, NS_W, RunKind } from '../core/types.js';
+import { parseOoxmlSafe, serializeXml } from '../adapters/xml-adapter.js';
+import { createWordElement } from '../core/word-xml.js';
 
 /**
  * Executes list generation when paragraph content expands into list/table blocks.
@@ -39,10 +42,17 @@ export async function executeListGeneration(options) {
     const normalizedListText = normalizeCompositeListMarkers(cleanText);
     const lineMetadata = buildLineMetadata(normalizedListText);
     const rawLines = lineMetadata.map(line => line.raw);
-    const results = [];
+    const results = [];
+    const sourcePPr = getSourceParagraphProperties(originalRunModel);
+    const inheritedTypographyRPrXml = extractInheritedTypographyRPrXml(originalRunModel, sourcePPr);
+    const inheritedHeadingRPrXml = extractInheritedTypographyRPrXml(
+        originalRunModel,
+        sourcePPr,
+        ['rFonts', 'kern', 'position', 'rtl', 'cs', 'lang']
+    );
 
     let deletionRuns = [];
-    if (generateRedlines) {
+    if (generateRedlines) {
         if (originalRunModel && originalRunModel.length > 0) {
             deletionRuns = originalRunModel
                 .filter(run => run.kind === 'text' || run.kind === 'run')
@@ -56,8 +66,18 @@ export async function executeListGeneration(options) {
                 startOffset: 0,
                 endOffset: trimmed.length
             }];
-        }
-    }
+        }
+    }
+
+    if (generateRedlines && deletionRuns.length > 0) {
+        const deletedPPr = addParagraphMarkRevision(sourcePPr, 'del', author, revisionIdAllocator);
+        const deletedParagraph = serializeToOoxml(deletionRuns, deletedPPr, [], {
+            author,
+            generateRedlines,
+            revisionIdAllocator
+        });
+        results.push(deletedParagraph);
+    }
 
     const indentStep = detectIndentationStep(rawLines);
     log(`[ListGen] Detected indentation step: ${indentStep} spaces/chars`);
@@ -71,19 +91,11 @@ export async function executeListGeneration(options) {
         if (tableBlock) {
             const tableData = parseTable(tableBlock.tableText);
             if (tableData.headers.length > 0 || tableData.rows.length > 0) {
-                if (generateRedlines && results.length === 0 && deletionRuns.length > 0) {
-                    results.push(serializeToOoxml(deletionRuns, null, [], {
-                        author,
-                        generateRedlines,
-                        font,
-                        revisionIdAllocator
-                    }));
-                }
-
                 results.push(generateTableOoxml(tableData, {
                     generateRedlines,
                     author,
-                    revisionIdAllocator
+                    revisionIdAllocator,
+                    trackAsBlock: true
                 }));
                 i = tableBlock.endIndex;
                 continue;
@@ -91,31 +103,29 @@ export async function executeListGeneration(options) {
         }
 
         const line = lineMetadata[i];
-        const entry = buildListEntry(
-            line,
-            i,
-            indentStep,
+        const entry = buildListEntry(
+            line,
+            indentStep,
             numberingContext,
             numberingService,
             generateRedlines,
             author,
             font,
             revisionIdAllocator,
-            deletionRuns
-        );
+            inheritedTypographyRPrXml,
+            inheritedHeadingRPrXml
+        );
         results.push(entry.ooxml);
     }
 
     const numberingXml = numberingService.generateNumberingXml();
     const finalOoxml = results.join('');
-    const blankParagraph = '<w:p><w:pPr></w:pPr></w:p>';
-    const oxmlWithSpacing = finalOoxml + blankParagraph;
-
-    log(`[ListGen] ✅ Generated OOXML for ${results.length} list items, total length: ${oxmlWithSpacing.length}`);
-    log(`[ListGen] First 200 chars: ${oxmlWithSpacing.substring(0, 200)}...`);
+
+    log(`[ListGen] ✅ Generated OOXML for ${results.length} paragraphs, total length: ${finalOoxml.length}`);
+    log(`[ListGen] First 200 chars: ${finalOoxml.substring(0, 200)}...`);
 
     return {
-        ooxml: oxmlWithSpacing,
+        ooxml: finalOoxml,
         isValid: true,
         warnings: ['Paragraph expanded to list fragment'],
         type: 'fragment',
@@ -226,28 +236,33 @@ function collectMarkdownTableBlock(lineMetadata, index) {
     };
 }
 
-function buildListEntry(
-    line,
-    lineIndex,
-    indentStep,
+function buildListEntry(
+    line,
+    indentStep,
     numberingContext,
     numberingService,
     generateRedlines,
     author,
     font,
     revisionIdAllocator,
-    deletionRuns
-) {
-    let pPrXml = '';
-    let segmentText = '';
+    inheritedTypographyRPrXml,
+    inheritedHeadingRPrXml
+) {
+    let pPrXml = '';
+    let segmentText = '';
+    let insertedRPrXml = inheritedTypographyRPrXml;
 
     if (line.headerMatch) {
         const level = Math.min(line.headerMatch[1].length, 9);
         const outlineLevel = Math.min(level - 1, 8);
         const headingSizes = [32, 28, 26, 24, 22, 20, 20, 20, 20];
-        const headingSize = headingSizes[level - 1] || headingSizes[headingSizes.length - 1];
-        segmentText = line.headerMatch[2].trim();
-        pPrXml = `<w:pPr><w:pStyle w:val="Heading${level}"/><w:outlineLvl w:val="${outlineLevel}"/><w:rPr><w:b/><w:sz w:val="${headingSize}"/><w:szCs w:val="${headingSize}"/></w:rPr></w:pPr>`;
+        const headingSize = headingSizes[level - 1] || headingSizes[headingSizes.length - 1];
+        segmentText = line.headerMatch[2].trim();
+        pPrXml = `<w:pPr><w:pStyle w:val="Heading${level}"/><w:outlineLvl w:val="${outlineLevel}"/><w:rPr><w:b/><w:sz w:val="${headingSize}"/><w:szCs w:val="${headingSize}"/></w:rPr></w:pPr>`;
+        insertedRPrXml = mergeRunProperties(
+            inheritedHeadingRPrXml,
+            `<w:rPr><w:b/><w:sz w:val="${headingSize}"/><w:szCs w:val="${headingSize}"/></w:rPr>`
+        );
     } else if (line.marker) {
         const lineFormat = numberingService.detectNumberingFormat(line.marker);
         const indentLevel = indentStep > 0 ? Math.floor(line.indentSize / indentStep) : 0;
@@ -259,20 +274,26 @@ function buildListEntry(
         segmentText = stripListMarker(line.raw);
         const numId = numberingService.getOrCreateNumId({ type: lineFormat.format }, numberingContext);
         pPrXml = numberingService.buildListPPr(numId, ilvl);
-    } else {
-        segmentText = line.raw;
-    }
-
-    const { cleanText, formatHints } = preprocessMarkdown(segmentText);
-    const runModel = [];
-
-    if (lineIndex === 0 && deletionRuns.length > 0) {
-        runModel.push(...deletionRuns);
-    }
-
-    runModel.push({
-        kind: generateRedlines ? 'insertion' : 'run',
-        text: cleanText,
+    } else {
+        segmentText = line.raw;
+    }
+
+    if (generateRedlines) {
+        pPrXml = addParagraphMarkRevision(
+            pPrXml || '<w:pPr/>',
+            'ins',
+            author,
+            revisionIdAllocator
+        );
+    }
+
+    const { cleanText, formatHints } = preprocessMarkdown(segmentText);
+    const runModel = [];
+
+    runModel.push({
+        kind: generateRedlines ? 'insertion' : 'run',
+        text: cleanText,
+        rPrXml: insertedRPrXml,
         author,
         startOffset: 0,
         endOffset: cleanText.length
@@ -285,5 +306,79 @@ function buildListEntry(
             font,
             revisionIdAllocator
         })
-    };
-}
+    };
+}
+
+function getSourceParagraphProperties(originalRunModel) {
+    const paragraphStart = (originalRunModel || []).find(run => run.kind === RunKind.PARAGRAPH_START);
+    return paragraphStart?.pPrElement || paragraphStart?.pPrXml || null;
+}
+
+function extractInheritedTypographyRPrXml(
+    originalRunModel,
+    sourcePPr,
+    tagOrder = ['rFonts', 'kern', 'position', 'sz', 'szCs', 'rtl', 'cs', 'lang']
+) {
+    const sources = (originalRunModel || [])
+        .filter(run => (run.kind === RunKind.TEXT || run.kind === 'text') && run.rPrXml)
+        .map(run => run.rPrXml);
+
+    if (sourcePPr) {
+        sources.push(typeof sourcePPr === 'string' ? sourcePPr : serializeXml(sourcePPr));
+    }
+
+    const inherited = [];
+    for (const tagName of tagOrder) {
+        let match = null;
+        for (const source of sources) {
+            match = String(source || '').match(new RegExp(`<w:${tagName}\\b[^>]*(?:\\/>|>[\\s\\S]*?<\\/w:${tagName}>)`));
+            if (match) break;
+        }
+        if (match) inherited.push(match[0]);
+    }
+
+    return inherited.length > 0 ? `<w:rPr>${inherited.join('')}</w:rPr>` : '';
+}
+
+function mergeRunProperties(...sources) {
+    const properties = sources
+        .map(source => String(source || '').replace(/^\s*<w:rPr[^>]*>|<\/w:rPr>\s*$/g, ''))
+        .filter(Boolean)
+        .join('');
+    return properties ? `<w:rPr>${properties}</w:rPr>` : '';
+}
+
+function addParagraphMarkRevision(xml, type, author, revisionIdAllocator) {
+    const metadata = createRevisionMetadata(author, revisionIdAllocator);
+    let pPr;
+    let ownerDoc;
+
+    if (xml?.nodeType === 1) {
+        pPr = xml.cloneNode(true);
+        ownerDoc = pPr.ownerDocument;
+    } else {
+        const pPrXml = typeof xml === 'string' && xml.trim() ? xml : '<w:pPr/>';
+        const parsed = parseOoxmlSafe(`<w:root xmlns:w="${NS_W}">${pPrXml}</w:root>`);
+        if (!parsed.doc) {
+            throw new Error(parsed.error?.message || 'Could not parse paragraph properties for list revision');
+        }
+        ownerDoc = parsed.doc;
+        pPr = Array.from(ownerDoc.documentElement.childNodes || []).find(node => (
+            node.nodeType === 1 && node.localName === 'pPr'
+        ));
+    }
+
+    if (!pPr || !ownerDoc) throw new Error('List paragraph properties are unavailable');
+    let rPr = Array.from(pPr.childNodes || []).find(node => node.nodeType === 1 && node.localName === 'rPr');
+    if (!rPr) {
+        rPr = createWordElement(ownerDoc, 'w:rPr');
+        pPr.appendChild(rPr);
+    }
+
+    const marker = createWordElement(ownerDoc, type === 'del' ? 'w:del' : 'w:ins');
+    marker.setAttribute('w:id', String(metadata.id));
+    marker.setAttribute('w:author', metadata.author);
+    marker.setAttribute('w:date', metadata.date);
+    rPr.appendChild(marker);
+    return serializeXml(pPr);
+}

package/pipeline/list-markers.js

@@ -4,7 +4,7 @@
  * Keeps marker parsing consistent across router, pipeline, and patching flows.
  */
 
-const LIST_MARKER_CORE = String.raw`(?:\d+(?:\.\d+)*\.?|\((?:\d+|[a-zA-Z]|[ivxlcIVXLC]+)\)|[a-zA-Z]\.|\d+\.|[ivxlcIVXLC]+\.|[-*\u2022])`;
+const LIST_MARKER_CORE = String.raw`(?:\d+(?:\.\d+)*\.?|\((?:\d+|[a-zA-Z]|[ivxlcIVXLC]+)\)|[a-zA-Z]\.|\d+\.|[ivxlcIVXLC]+\.|[-*+\u2022])`;
 
 const LINE_REGEX_STRICT = new RegExp(`^(\\s*)((?:${LIST_MARKER_CORE})\\s+)`);
 const LINE_REGEX_LOOSE = new RegExp(`^(\\s*)((?:${LIST_MARKER_CORE})\\s*)`);
@@ -70,8 +70,75 @@ export function extractListMarker(line, options = {}) {
  * @param {boolean} [options.allowZeroSpaceAfterMarker=false] - Allow zero spaces after marker
  * @returns {string}
  */
-export function stripListMarker(line, options = {}) {
+export function stripListMarker(line, options = {}) {
     const { allowZeroSpaceAfterMarker = false } = options;
     const regex = allowZeroSpaceAfterMarker ? LINE_REGEX_LOOSE : LINE_REGEX_STRICT;
     return line.replace(regex, '');
-}
+}
+
+/**
+ * Classifies a parsed marker using the shared list vocabulary.
+ *
+ * @param {string} marker - Marker without trailing whitespace
+ * @returns {'bullet'|'numbered'}
+ */
+export function classifyListMarker(marker) {
+    return /^[-*+\u2022]$/.test(String(marker || '').trim()) ? 'bullet' : 'numbered';
+}
+
+/**
+ * Infers the Word numbering style represented by a numbered marker.
+ *
+ * @param {string} marker - Marker text
+ * @returns {'bullet'|'decimal'|'lowerAlpha'|'upperAlpha'|'lowerRoman'|'upperRoman'}
+ */
+export function inferNumberingStyleFromMarker(marker) {
+    const value = String(marker || '').trim();
+    if (classifyListMarker(value) === 'bullet') return 'bullet';
+    if (/^\d+(?:\.\d+)*\.?$/.test(value) || /^\(\d+\)$/.test(value)) return 'decimal';
+    if (/^[ivxlcdm]+\.$/.test(value)) return 'lowerRoman';
+    if (/^[IVXLCDM]{2,}\.$/.test(value)) return 'upperRoman';
+    if (/^[a-z]\.$/.test(value)) return 'lowerAlpha';
+    if (/^[A-Z]\.$/.test(value)) return 'upperAlpha';
+    return 'decimal';
+}
+
+/**
+ * Returns an outline level encoded directly in a composite decimal marker.
+ * Indentation-derived levels remain the caller's responsibility.
+ *
+ * @param {string} marker - Marker text
+ * @returns {number|null}
+ */
+export function parseOutlineLevelFromMarker(marker) {
+    const value = String(marker || '').trim();
+    if (!/^\d+(?:\.\d+)+\.?$/.test(value)) return null;
+    return Math.max(0, value.replace(/\.$/, '').split('.').length - 1);
+}
+
+/**
+ * Parses one line into the common list-item representation.
+ *
+ * @param {string} line - Input line
+ * @param {{allowZeroSpaceAfterMarker?: boolean, indentSpaces?: number}} [options]
+ * @returns {{line:string,text:string,marker:string,indent:number,level:number,markerType:'bullet'|'numbered',listType:'bullet'|'numbered',numberingStyle:string,outlineLevel:number|null}|null}
+ */
+export function parseListItem(line, options = {}) {
+    const match = matchListMarker(String(line || ''), options);
+    if (!match) return null;
+    const marker = match[2].trim();
+    const indent = (match[1] || '').length;
+    const indentSpaces = Math.max(1, Number(options.indentSpaces) || 2);
+    const markerType = classifyListMarker(marker);
+    return {
+        line: String(line || ''),
+        text: stripListMarker(String(line || ''), options),
+        marker,
+        indent,
+        level: Math.min(8, Math.floor(indent / indentSpaces)),
+        markerType,
+        listType: markerType,
+        numberingStyle: inferNumberingStyleFromMarker(marker),
+        outlineLevel: markerType === 'numbered' ? parseOutlineLevelFromMarker(marker) : null
+    };
+}

package/pipeline/serialization.js

@@ -232,7 +232,8 @@ function buildSimpleRun(text, rPrXml) {
 function buildDeletionXml(item, options = {}) {
     const metadata = createRevisionMetadata(
         options.author ?? getDefaultAuthor(),
-        options.revisionIdAllocator
+        options.revisionIdAllocator,
+        'del'
     );
     const font = options.font ?? null;
     let rPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
@@ -257,7 +258,8 @@ function buildDeletionXml(item, options = {}) {
 function buildInsertionXml(item, formatHints, options = {}) {
     const metadata = createRevisionMetadata(
         options.author ?? getDefaultAuthor(),
-        options.revisionIdAllocator
+        options.revisionIdAllocator,
+        'ins'
     );
     const font = options.font ?? null;
 

package/pipeline/structured-content.js

@@ -0,0 +1,160 @@
+/**
+ * Strict, dependency-light planning for mixed Markdown document insertions.
+ *
+ * Agents should run this before replacing one Word paragraph with content that
+ * contains headings, paragraphs, lists, or tables. The planner never guesses a
+ * malformed table: a Markdown separator row is required so literal pipe text
+ * cannot silently reach the document.
+ */
+
+import { matchListMarker } from './list-markers.js';
+
+const TABLE_SEPARATOR = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+
+function isBlank(line) {
+    return !line || line.trim().length === 0;
+}
+
+function isTableLine(line) {
+    const trimmed = String(line || '').trim();
+    return trimmed.startsWith('|') && trimmed.endsWith('|');
+}
+
+function tableCells(line) {
+    return String(line || '').trim().split('|').slice(1, -1).map(cell => cell.trim());
+}
+
+function classifyLine(line) {
+    if (isBlank(line)) return 'blank';
+    if (/^\s*#{1,9}\s+\S/.test(line)) return 'heading';
+    if (isTableLine(line)) return 'table';
+    if (matchListMarker(line)) return 'list';
+    return 'paragraph';
+}
+
+/**
+ * Decomposes mixed Markdown into explicit document blocks and validates the
+ * structural syntax required by the OOXML generator.
+ *
+ * @param {string} markdown
+ * @returns {{ valid: boolean, normalizedMarkdown: string, blocks: Array<object>, issues: Array<object>, counts: Record<string, number>, requiresStructuredContent: boolean }}
+ */
+export function analyzeStructuredContent(markdown) {
+    const source = typeof markdown === 'string' ? markdown.replace(/\r\n?/g, '\n') : String(markdown ?? '');
+    const lines = source.split('\n');
+    const blocks = [];
+    const issues = [];
+    let index = 0;
+
+    while (index < lines.length) {
+        if (isBlank(lines[index])) {
+            index++;
+            continue;
+        }
+
+        const kind = classifyLine(lines[index]);
+        const startLine = index + 1;
+        if (kind === 'heading') {
+            const match = lines[index].match(/^\s*(#{1,9})\s+(.+?)\s*$/);
+            blocks.push({ type: 'heading', level: match[1].length, text: match[2], markdown: lines[index].trim() });
+            index++;
+            continue;
+        }
+
+        if (kind === 'table') {
+            const tableLines = [];
+            while (index < lines.length && isTableLine(lines[index])) {
+                tableLines.push(lines[index].trim());
+                index++;
+            }
+            const separatorPresent = tableLines.length > 1 && TABLE_SEPARATOR.test(tableLines[1]);
+            const widths = tableLines.filter(line => !TABLE_SEPARATOR.test(line)).map(line => tableCells(line).length);
+            if (!separatorPresent) {
+                issues.push({
+                    severity: 'error',
+                    code: 'TABLE_SEPARATOR_REQUIRED',
+                    line: startLine,
+                    message: 'Markdown tables require a separator row immediately after the header (for example | --- | --- |).'
+                });
+            }
+            if (widths.length < 2) {
+                issues.push({
+                    severity: 'error',
+                    code: 'TABLE_DATA_ROW_REQUIRED',
+                    line: startLine,
+                    message: 'Markdown tables require a header and at least one data row.'
+                });
+            } else if (new Set(widths).size > 1) {
+                issues.push({
+                    severity: 'error',
+                    code: 'TABLE_COLUMN_COUNT_MISMATCH',
+                    line: startLine,
+                    message: `Markdown table rows have inconsistent column counts: ${widths.join(', ')}.`
+                });
+            }
+            blocks.push({
+                type: 'table',
+                columns: widths[0] || 0,
+                rows: Math.max(0, widths.length - 1),
+                hasHeader: separatorPresent,
+                markdown: tableLines.join('\n')
+            });
+            continue;
+        }
+
+        if (kind === 'list') {
+            const listLines = [];
+            while (index < lines.length && classifyLine(lines[index]) === 'list') {
+                listLines.push(lines[index].trimEnd());
+                index++;
+            }
+            blocks.push({ type: 'list', items: listLines.length, markdown: listLines.join('\n') });
+            continue;
+        }
+
+        const paragraphLines = [];
+        while (index < lines.length && classifyLine(lines[index]) === 'paragraph') {
+            paragraphLines.push(lines[index].trim());
+            index++;
+        }
+        const text = paragraphLines.join(' ').trim();
+        blocks.push({ type: 'paragraph', text, markdown: text });
+    }
+
+    const counts = { heading: 0, paragraph: 0, list: 0, table: 0 };
+    for (const block of blocks) counts[block.type] = (counts[block.type] || 0) + 1;
+    const normalizedMarkdown = blocks.map(block => block.markdown).join('\n\n');
+    return {
+        valid: issues.every(issue => issue.severity !== 'error'),
+        normalizedMarkdown,
+        blocks,
+        issues,
+        counts,
+        requiresStructuredContent: blocks.length > 1 || blocks.some(block => block.type === 'heading' || block.type === 'table' || (block.type === 'list' && block.items > 1))
+    };
+}
+
+/**
+ * Builds one atomic full-document replacement operation from validated mixed
+ * Markdown. The operation remains a single target mutation; blocks are not
+ * emitted as a fragile sequence of operations that would invalidate the anchor.
+ *
+ * @param {string|object} target
+ * @param {string} markdown
+ * @param {{ author?: string, generateRedlines?: boolean, existingRevisions?: string }} [options]
+ */
+export function planStructuredReplacement(target, markdown, options = {}) {
+    const analysis = analyzeStructuredContent(markdown);
+    return {
+        ...analysis,
+        operation: analysis.valid ? {
+            type: 'replace',
+            target,
+            modified: analysis.normalizedMarkdown,
+            structuredContent: true,
+            ...(options.author ? { author: options.author } : {}),
+            ...(typeof options.generateRedlines === 'boolean' ? { generateRedlines: options.generateRedlines } : {}),
+            ...(options.existingRevisions ? { existingRevisions: options.existingRevisions } : {})
+        } : null
+    };
+}

package/scripts/apply_changes.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+// Compatibility entrypoint for legacy docx-redline skill invocations.
+// All targeting, transaction, validation, and output behavior is delegated to
+// the supported CLI instead of being reimplemented here.
+import { runCli } from '../node/cli.js';
+
+const legacyArgs = process.argv.slice(2);
+const input = legacyArgs.shift();
+const operations = legacyArgs.shift();
+const output = legacyArgs[0] && !legacyArgs[0].startsWith('--')
+    ? legacyArgs.shift()
+    : null;
+
+const delegatedArgs = ['apply'];
+if (input) delegatedArgs.push(input);
+if (operations) delegatedArgs.push('--operations', operations);
+if (output) delegatedArgs.push('--output', output);
+delegatedArgs.push(...legacyArgs);
+if (!legacyArgs.some(argument => argument === '--author' || argument.startsWith('--author='))) {
+    delegatedArgs.push('--author', process.env.DOCX_REDLINE_AUTHOR || 'Agent');
+}
+if (!legacyArgs.some(argument => argument === '--atomic' || argument === '--no-atomic')) {
+    delegatedArgs.push('--atomic');
+}
+
+process.exitCode = await runCli(delegatedArgs);