@ansonlai/docx-redline-js 0.1.0

package/orchestration/route-plan.js

@@ -0,0 +1,160 @@
+/**
+ * Pure routing plan builder used by command-layer Word adapters.
+ *
+ * This module must remain Word-agnostic.
+ */
+
+import { parseTable } from '../pipeline/content-analysis.js';
+import { parseMarkdownListContent } from './list-parsing.js';
+
+export const RoutePlanKind = Object.freeze({
+    STRUCTURED_LIST_DIRECT: 'structured_list_direct',
+    EMPTY_FORMATTED_TEXT: 'empty_formatted_text',
+    EMPTY_HTML: 'empty_html',
+    BLOCK_HTML: 'block_html',
+    OOXML_ENGINE: 'ooxml_engine'
+});
+
+/**
+ * Converts literal escape sequences (for example "\\n") into actual characters.
+ *
+ * @param {string} content - Raw model content
+ * @returns {string}
+ */
+export function normalizeContentEscapesForRouting(content) {
+    if (!content || typeof content !== 'string') return content || '';
+    return content
+        .replace(/\\n/g, '\n')
+        .replace(/\\t/g, '\t')
+        .replace(/\\r/g, '\r');
+}
+
+/**
+ * Builds a deterministic route plan for command-layer application.
+ *
+ * @param {Object} params - Plan input
+ * @param {string} params.originalText - Current paragraph text
+ * @param {string} params.newContent - Requested new content
+ * @returns {Object}
+ */
+export function buildReconciliationPlan(params = {}) {
+    const originalText = params.originalText || '';
+    const normalizedContent = normalizeContentEscapesForRouting(params.newContent || '');
+
+    const parsedListData = parseMarkdownListContent(normalizedContent) || { type: 'text', items: [] };
+    const hasStructuredListContent = normalizedContent.includes('\n') && parsedListData.type !== 'text';
+    if (hasStructuredListContent) {
+        return {
+            kind: RoutePlanKind.STRUCTURED_LIST_DIRECT,
+            normalizedContent,
+            parsedListData,
+            flags: {
+                hasStructuredListContent: true,
+                isOriginalEmpty: isEmpty(originalText),
+                hasInlineFormatting: hasInlineMarkdownFormatting(normalizedContent),
+                hasBlockElements: hasBlockElements(normalizedContent),
+                hasMarkdownTable: hasMarkdownTable(normalizedContent)
+            }
+        };
+    }
+
+    const isOriginalEmpty = isEmpty(originalText);
+    if (isOriginalEmpty) {
+        const hasInlineFormatting = hasInlineMarkdownFormatting(normalizedContent);
+        if (hasInlineFormatting) {
+            return {
+                kind: RoutePlanKind.EMPTY_FORMATTED_TEXT,
+                normalizedContent,
+                parsedListData,
+                flags: {
+                    hasStructuredListContent: false,
+                    isOriginalEmpty: true,
+                    hasInlineFormatting: true,
+                    hasBlockElements: hasBlockElements(normalizedContent),
+                    hasMarkdownTable: hasMarkdownTable(normalizedContent)
+                }
+            };
+        }
+
+        return {
+            kind: RoutePlanKind.EMPTY_HTML,
+            normalizedContent,
+            parsedListData,
+            flags: {
+                hasStructuredListContent: false,
+                isOriginalEmpty: true,
+                hasInlineFormatting: false,
+                hasBlockElements: hasBlockElements(normalizedContent),
+                hasMarkdownTable: hasMarkdownTable(normalizedContent)
+            }
+        };
+    }
+
+    const hasBlocks = hasBlockElements(normalizedContent);
+    if (hasBlocks) {
+        return {
+            kind: RoutePlanKind.BLOCK_HTML,
+            normalizedContent,
+            parsedListData,
+            flags: {
+                hasStructuredListContent: false,
+                isOriginalEmpty: false,
+                hasInlineFormatting: hasInlineMarkdownFormatting(normalizedContent),
+                hasBlockElements: true,
+                hasMarkdownTable: hasMarkdownTable(normalizedContent)
+            }
+        };
+    }
+
+    return {
+        kind: RoutePlanKind.OOXML_ENGINE,
+        normalizedContent,
+        parsedListData,
+        flags: {
+            hasStructuredListContent: false,
+            isOriginalEmpty: false,
+            hasInlineFormatting: hasInlineMarkdownFormatting(normalizedContent),
+            hasBlockElements: false,
+            hasMarkdownTable: hasMarkdownTable(normalizedContent)
+        }
+    };
+}
+
+function isEmpty(text) {
+    return !text || text.trim().length === 0;
+}
+
+function hasMarkdownTable(content) {
+    if (!content || !content.includes('|')) return false;
+    const tableData = parseTable(content);
+    return tableData.rows.length > 0 || tableData.headers.length > 0;
+}
+
+function hasInlineMarkdownFormatting(text) {
+    if (!text) return false;
+    return /(\*\*.+?\*\*|\*.+?\*|__.+?__|_.+?_|`.+?`|~~.+?~~|\+\+.+?\+\+)/.test(text);
+}
+
+function hasBlockElements(content) {
+    if (!content) return false;
+
+    const hasUnorderedList = /^[\s]*[-*+]\s+/m.test(content);
+    const hasOrderedList = /^[\s]*\d+\.\s+/m.test(content);
+    const hasOutlineList = /^[\s]*\d+\.\d+(?:\.\d+)*\.?\s+/m.test(content);
+    const hasAlphaDotList = /^[\s]*[A-Za-z]\.\s+/m.test(content);
+    const hasRomanDotList = /^[\s]*[ivxlcIVXLC]+\.\s+/m.test(content);
+    const hasAlphaList = /^[\s]*\([a-z]\)\s+/m.test(content);
+    const hasTable = /\|.*\|.*\n/.test(content);
+    const hasHeading = /^#{1,9}\s/m.test(content);
+    const hasMultipleLineBreaks = content.includes('\n\n');
+
+    return hasUnorderedList
+        || hasOrderedList
+        || hasOutlineList
+        || hasAlphaDotList
+        || hasRomanDotList
+        || hasAlphaList
+        || hasTable
+        || hasHeading
+        || hasMultipleLineBreaks;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ansonlai/docx-redline-js",
+  "version": "0.1.0",
+  "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./standalone": "./standalone.js",
+    "./adapters/*": "./adapters/*",
+    "./core/*": "./core/*",
+    "./engine/*": "./engine/*",
+    "./pipeline/*": "./pipeline/*",
+    "./services/*": "./services/*",
+    "./orchestration/*": "./orchestration/*"
+  },
+  "files": [
+    "adapters/",
+    "core/",
+    "engine/",
+    "pipeline/",
+    "services/",
+    "orchestration/",
+    "index.js",
+    "standalone.js",
+    "dist/",
+    "ARCHITECTURE.md",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "diff-match-patch": "^1.0.5"
+  },
+  "peerDependencies": {
+    "@xmldom/xmldom": ">=0.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@xmldom/xmldom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "@xmldom/xmldom": "^0.9.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node scripts/run-tests.mjs",
+    "test:isolation": "node tests/no_word_api_standalone_check.mjs && node tests/core_dependency_graph_check.mjs",
+    "prepublishOnly": "npm run test:isolation && npm run build"
+  },
+  "keywords": [
+    "docx",
+    "ooxml",
+    "reconciliation",
+    "track-changes",
+    "redlines",
+    "word",
+    "office",
+    "document",
+    "xml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_ORG/docx-redline-js.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/pipeline/content-analysis.js

@@ -0,0 +1,107 @@
+/**
+ * Content analysis helpers for paragraph/list/table classification.
+ */
+
+import { ContentType } from '../core/types.js';
+import { matchListMarker, stripListMarker } from './list-markers.js';
+
+/**
+ * Parses table from markdown-style table text.
+ *
+ * @param {string} text - Table text
+ * @returns {{ headers: string[], rows: string[][], hasHeader: boolean }}
+ */
+export function parseTable(text) {
+    const lines = text
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.startsWith('|'));
+    if (lines.length === 0) {
+        return { headers: [], rows: [], hasHeader: false };
+    }
+
+    const isSeparatorLine = line => {
+        const normalized = line.replace(/\s+/g, '');
+        return /^\|:?-{3,}:?(\|:?-{3,}:?)+\|?$/.test(normalized);
+    };
+
+    const hasHeader = lines.some(isSeparatorLine);
+    const dataLines = lines.filter(line => !isSeparatorLine(line));
+    const parsedRows = dataLines.map(line =>
+        line
+            .split('|')
+            .slice(1, -1)
+            .map(cell => cell.trim())
+    );
+
+    if (!hasHeader) {
+        return {
+            headers: [],
+            rows: parsedRows,
+            hasHeader: false
+        };
+    }
+
+    return {
+        headers: parsedRows[0] || [],
+        rows: parsedRows.slice(1),
+        hasHeader: true
+    };
+}
+
+/**
+ * Parses list items from markdown-style list text.
+ *
+ * @param {string} text - List text
+ * @returns {Array<{ line: string, text: string, marker: string, indent: number, level: number, listType: 'bullet'|'numbered' }>}
+ */
+export function parseListItems(text) {
+    const lines = text.split('\n').filter(line => line.trim().length > 0);
+    const items = [];
+
+    lines.forEach(line => {
+        const markerMatch = matchListMarker(line, { allowZeroSpaceAfterMarker: true });
+        if (!markerMatch) return;
+
+        const marker = markerMatch[2].trim();
+        const indent = (line.match(/^(\s*)/)?.[1].length) || 0;
+        const listType = /^[-*+•]/.test(marker) ? 'bullet' : 'numbered';
+        const outlineDepth = (marker.match(/\./g) || []).length;
+        const level = outlineDepth > 1 ? Math.min(8, outlineDepth - 1) : Math.min(8, Math.floor(indent / 2));
+
+        items.push({
+            line,
+            text: stripListMarker(line, { allowZeroSpaceAfterMarker: true }),
+            marker,
+            indent,
+            level,
+            listType
+        });
+    });
+
+    return items;
+}
+
+/**
+ * Detects content type from text.
+ *
+ * @param {string} text - Text to classify
+ * @returns {ContentType}
+ */
+export function detectContentType(text) {
+    const normalized = (text || '').trim();
+    if (!normalized) return ContentType.PARAGRAPH;
+
+    const table = parseTable(normalized);
+    if (table.headers.length > 0 || table.rows.length > 0) {
+        return ContentType.TABLE;
+    }
+
+    const listItems = parseListItems(normalized);
+    if (listItems.length > 0) {
+        const hasBullet = listItems.some(item => item.listType === 'bullet');
+        return hasBullet ? ContentType.BULLET_LIST : ContentType.NUMBERED_LIST;
+    }
+
+    return ContentType.PARAGRAPH;
+}

package/pipeline/diff-engine.js

@@ -0,0 +1,204 @@
+/**
+ * OOXML Reconciliation Pipeline - Diff Engine
+ * 
+ * Word-level diffing with offset tracking for precise run splitting.
+ */
+
+import { diff_match_patch } from 'diff-match-patch';
+import { DiffOp } from '../core/types.js';
+
+const DMP = new diff_match_patch();
+
+/**
+ * Converts text into word tokens represented as unique characters.
+ * This allows DMP to diff at word-level instead of character-level.
+ * 
+ * @param {string} text1 - First text to tokenize
+ * @param {string} text2 - Second text to tokenize
+ * @returns {{ chars1: string, chars2: string, wordArray: string[] }}
+ */
+export function wordsToChars(text1, text2) {
+    const wordArray = [];
+    const wordHash = new Map();
+
+    function tokenize(text) {
+        const tokens = [];
+        const regex = /(\S+)(\s*)/g;
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            if (match[1]) tokens.push(match[1]);
+            if (match[2]) tokens.push(match[2]);
+        }
+        return tokens;
+    }
+
+    function mapTokensToChars(tokens) {
+        let chars = '';
+        for (const token of tokens) {
+            if (wordHash.has(token)) {
+                chars += String.fromCharCode(wordHash.get(token));
+            } else {
+                const charCode = wordArray.length;
+                wordArray.push(token);
+                wordHash.set(token, charCode);
+                chars += String.fromCharCode(charCode);
+            }
+        }
+        return chars;
+    }
+
+    const tokens1 = tokenize(text1);
+    const tokens2 = tokenize(text2);
+
+    return {
+        chars1: mapTokensToChars(tokens1),
+        chars2: mapTokensToChars(tokens2),
+        wordArray
+    };
+}
+
+/**
+ * Converts character-encoded diffs back to actual word diffs.
+ * 
+ * @param {Array} diffs - DMP diff array with character codes
+ * @param {string[]} wordArray - Array mapping char codes to words
+ * @returns {Array} DMP-style diff array with actual words
+ */
+export function charsToWords(diffs, wordArray) {
+    const wordDiffs = [];
+
+    for (const [op, chars] of diffs) {
+        const parts = [];
+        for (let i = 0; i < chars.length; i++) {
+            const charCode = chars.charCodeAt(i);
+            if (charCode < wordArray.length) {
+                parts.push(wordArray[charCode]);
+            }
+        }
+        wordDiffs.push([op, parts.join('')]);
+    }
+
+    return wordDiffs;
+}
+
+/**
+ * Computes word-level diff tuples using a shared diff engine instance.
+ *
+ * @param {string} originalText - Original text
+ * @param {string} newText - New text
+ * @param {{ cleanupSemantic?: boolean }} [options={}] - Diff options
+ * @returns {Array<[number, string]>}
+ */
+export function computeWordDiffs(originalText, newText, options = {}) {
+    if (originalText === newText) {
+        return [[0, originalText]];
+    }
+
+    if (!originalText) {
+        return [[1, newText]];
+    }
+
+    if (!newText) {
+        return [[-1, originalText]];
+    }
+
+    const { cleanupSemantic = true } = options;
+
+    const { chars1, chars2, wordArray } = wordsToChars(originalText, newText);
+    const charDiffs = DMP.diff_main(chars1, chars2);
+    if (cleanupSemantic) {
+        DMP.diff_cleanupSemantic(charDiffs);
+    }
+
+    return charsToWords(charDiffs, wordArray);
+}
+
+/**
+ * Computes word-level diff operations with offset tracking.
+ * 
+ * @param {string} originalText - Original text
+ * @param {string} newText - New text
+ * @param {{ cleanupSemantic?: boolean }} [options={}] - Diff options
+ * @returns {import('../core/types.js').DiffOperation[]}
+ */
+export function computeWordLevelDiffOps(originalText, newText, options = {}) {
+    // Handle edge cases
+    if (originalText === newText) {
+        return [{
+            type: DiffOp.EQUAL,
+            startOffset: 0,
+            endOffset: originalText.length,
+            text: originalText
+        }];
+    }
+
+    if (!originalText) {
+        return [{
+            type: DiffOp.INSERT,
+            startOffset: 0,
+            endOffset: 0,
+            text: newText
+        }];
+    }
+
+    if (!newText) {
+        return [{
+            type: DiffOp.DELETE,
+            startOffset: 0,
+            endOffset: originalText.length,
+            text: originalText
+        }];
+    }
+
+    const wordDiffs = computeWordDiffs(originalText, newText, options);
+
+    // Convert to operations with offsets
+    const operations = [];
+    let originalOffset = 0;
+
+    for (const [op, text] of wordDiffs) {
+        if (op === 0) { // EQUAL
+            operations.push({
+                type: DiffOp.EQUAL,
+                startOffset: originalOffset,
+                endOffset: originalOffset + text.length,
+                text
+            });
+            originalOffset += text.length;
+        } else if (op === -1) { // DELETE
+            operations.push({
+                type: DiffOp.DELETE,
+                startOffset: originalOffset,
+                endOffset: originalOffset + text.length,
+                text
+            });
+            originalOffset += text.length;
+        } else if (op === 1) { // INSERT
+            operations.push({
+                type: DiffOp.INSERT,
+                startOffset: originalOffset,
+                endOffset: originalOffset, // Insertions don't span original text
+                text
+            });
+            // Don't advance originalOffset for insertions
+        }
+    }
+
+    return operations;
+}
+
+/**
+ * Collects all unique boundary offsets from diff operations.
+ * 
+ * @param {import('../core/types.js').DiffOperation[]} diffOps - Diff operations
+ * @returns {Set<number>}
+ */
+export function collectDiffBoundaries(diffOps) {
+    const boundaries = new Set();
+    for (const op of diffOps) {
+        boundaries.add(op.startOffset);
+        boundaries.add(op.endOffset);
+    }
+    return boundaries;
+}
+