@ansonlai/docx-redline-js 0.1.4 → 0.2.0

package/index.js

@@ -1,13 +1,13 @@
-/**
- * Standalone reconciliation entrypoint (no Word JS API dependencies).
- */
-
+/**
+ * Standalone reconciliation entrypoint (no Word JS API dependencies).
+ */
+
 // Adapters
 export { configureXmlProvider } from './adapters/xml-adapter.js';
 export { configureLogger } from './adapters/logger.js';
 export { setDefaultAuthor, getDefaultAuthor, setPlatform, getPlatform } from './adapters/config.js';
-
-// Engine
+
+// Engine
 import {
     applyRedlineToOxml as applyRedlineToOxmlEngine,
     sanitizeAiResponse,
@@ -25,27 +25,30 @@ import {
     enforceListBindingOnParagraphNodes,
     stripSingleLineListMarkerPrefix
 } from './orchestration/list-structural-fallback.js';
-
-/**
- * Standalone-safe redline wrapper.
- *
- * In non-Word runtimes, the engine can return `{ useNativeApi: true, hasChanges: true }`
- * without an OOXML payload for some format-only operations. Standalone callers cannot
- * complete that native fallback path, so normalize to a no-op with warnings.
- */
+import { withOoxmlSourceType } from './core/word-xml.js';
+export { containsTrackedChanges } from './core/word-xml.js';
+export { validateRedlineOoxml } from './core/redline-validation.js';
+
+/**
+ * Standalone-safe redline wrapper.
+ *
+ * In non-Word runtimes, the engine can return `{ useNativeApi: true, hasChanges: true }`
+ * without an OOXML payload for some format-only operations. Standalone callers cannot
+ * complete that native fallback path, so normalize to a no-op with warnings.
+ */
 export async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}) {
     const result = await applyRedlineToOxmlEngine(oxml, originalText, modifiedText, options);
     if (result?.useNativeApi && typeof result?.oxml !== 'string') {
         const existingWarnings = Array.isArray(result?.warnings) ? result.warnings : [];
-        return {
-            ...result,
-            oxml,
-            hasChanges: false,
-            warnings: [
-                ...existingWarnings,
-                'Standalone mode cannot execute native Word API fallback for this operation.'
-            ]
-        };
+        return withOoxmlSourceType({
+            ...result,
+            oxml,
+            hasChanges: false,
+            warnings: [
+                ...existingWarnings,
+                'Standalone mode cannot execute native Word API fallback for this operation.'
+            ]
+        });
     }
     return result;
 }
@@ -97,9 +100,9 @@ export async function reconcileMarkdownTableOoxml(oxml, originalText, markdownTa
     };
 }
 
-export { resolveParagraphRangeByRefs } from './core/paragraph-targeting.js';
-export { inferTableReplacementParagraphBlock, isLikelyStructuredTableSourceParagraph } from './core/table-targeting.js';
-
+export { resolveParagraphRangeByRefs } from './core/paragraph-targeting.js';
+export { inferTableReplacementParagraphBlock, isLikelyStructuredTableSourceParagraph } from './core/table-targeting.js';
+
 /**
  * Applies redline reconciliation, then forces single-line structural list
  * conversion when the redline is a no-op on marker-prefixed list text.
@@ -137,14 +140,14 @@ export async function applyRedlineToOxmlWithListFallback(oxml, originalText, mod
                 numberingXml: fallbackResult.numberingXml
             });
             const fallbackWarnings = Array.isArray(fallbackResult?.warnings) ? fallbackResult.warnings : [];
-            return {
+            return withOoxmlSourceType({
                 oxml: wrappedOxml,
                 hasChanges: true,
                 warnings: fallbackWarnings,
                 listStructuralFallbackApplied: true,
                 listStructuralFallbackKey: fallbackResult.listStructuralFallbackKey || null,
                 listStructuralFallbackNumberingXml: fallbackResult.numberingXml || null
-            };
+            });
         }
         preflightFallbackWarnings = Array.isArray(fallbackResult?.warnings) ? fallbackResult.warnings : [];
     }
@@ -202,7 +205,7 @@ export async function applyRedlineToOxmlWithListFallback(oxml, originalText, mod
     const existingWarnings = Array.isArray(baseResult?.warnings) ? baseResult.warnings : [];
     const fallbackWarnings = Array.isArray(fallbackResult?.warnings) ? fallbackResult.warnings : [];
 
-    return {
+    return withOoxmlSourceType({
         ...baseResult,
         oxml: wrappedOxml,
         hasChanges: true,
@@ -210,7 +213,7 @@ export async function applyRedlineToOxmlWithListFallback(oxml, originalText, mod
         listStructuralFallbackApplied: true,
         listStructuralFallbackKey: fallbackResult.listStructuralFallbackKey || null,
         listStructuralFallbackNumberingXml: fallbackResult.numberingXml || null
-    };
+    });
 }
 
 export { sanitizeAiResponse, parseOoxml, serializeOoxml };
@@ -232,8 +235,8 @@ export { ingestOoxml } from './pipeline/ingestion.js';
 export { ingestWordOoxmlToPlainText, ingestWordOoxmlToMarkdown } from './pipeline/ingestion-export.js';
 export { preprocessMarkdown } from './pipeline/markdown-processor.js';
 export { serializeToOoxml, wrapInDocumentFragment } from './pipeline/serialization.js';
-
-// Comment engine
+
+// Comment engine
 export {
     injectCommentsIntoOoxml,
     injectCommentsIntoPackage,
@@ -245,15 +248,15 @@ export {
     rejectTrackedChangesInOoxml,
     deleteCommentsByAuthorInOoxml
 } from './services/revision-comment-management.js';
-
+
 // Formatting removal utilities
 export {
     removeFormattingFromRPr,
     applyFormattingRemovalToOoxml,
     applyHighlightToOoxml
 } from './engine/formatting-removal.js';
-
-// Table/list tools
+
+// Table/list tools
 export { generateTableOoxml } from './services/table-reconciliation.js';
 export { NumberingService } from './services/numbering-service.js';
 export {
@@ -280,20 +283,20 @@ export {
     enforceListBindingOnParagraphNodes,
     stripSingleLineListMarkerPrefix
 } from './orchestration/list-structural-fallback.js';
-
-// Core types/constants
-export { DiffOp, RunKind, ContainerKind, ContentType, NS_W, escapeXml } from './core/types.js';
-export { extractParagraphIdFromOoxml } from './core/ooxml-identifiers.js';
+
+// Core types/constants
+export { DiffOp, RunKind, ContainerKind, ContentType, NS_W, escapeXml } from './core/types.js';
+export { extractParagraphIdFromOoxml } from './core/ooxml-identifiers.js';
 export {
     WORD_MAIN_NS,
     getParagraphText,
     getDocumentParagraphNodes,
     normalizeWhitespaceForTargeting,
-    isMarkdownTableText,
-    parseParagraphReference,
-    stripLeadingParagraphMarker,
-    splitLeadingParagraphMarker,
-    findContainingWordElement,
+    isMarkdownTableText,
+    parseParagraphReference,
+    stripLeadingParagraphMarker,
+    splitLeadingParagraphMarker,
+    findContainingWordElement,
     findParagraphByReference,
     findParagraphByStrictText,
     findParagraphByBestTextMatch,
@@ -301,7 +304,7 @@ export {
     buildTargetReferenceSnapshot,
     resolveTargetParagraphWithSnapshot
 } from './core/paragraph-targeting.js';
-export { synthesizeTableMarkdownFromMultilineCellEdit } from './core/table-targeting.js';
+export { synthesizeTableMarkdownFromMultilineCellEdit } from './core/table-targeting.js';
 export {
     getParagraphListInfo,
     collectContiguousListParagraphBlock,
@@ -309,5 +312,5 @@ export {
     planListInsertionOnlyEdit,
     stripRedundantLeadingListMarkers
 } from './core/list-targeting.js';
-
-
+
+

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./index.js",
       "default": "./index.js"
     },
@@ -27,7 +29,10 @@
     "pipeline/",
     "services/",
     "orchestration/",
+    "scripts/",
+    "docs/",
     "index.js",
+    "index.d.ts",
     "dist/",
     "ARCHITECTURE.md",
     "AGENTS.md",
@@ -51,6 +56,9 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
+    "check:types": "node scripts/check-types.mjs",
+    "smoke:word": "powershell -File scripts/word-com-smoke.ps1",
+    "smoke:word:diff": "powershell -File scripts/word-com-differential.ps1",
     "test": "node scripts/run-tests.mjs",
     "test:isolation": "node tests/no_word_api_index_check.mjs && node tests/core_dependency_graph_check.mjs",
     "prepublishOnly": "npm run test:isolation && npm run build"
@@ -71,6 +79,6 @@
     "url": "https://github.com/AnsonLai/docx-redline-js.git"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/pipeline/ingestion-export.js

@@ -112,6 +112,7 @@ function collectParagraphSegments(paragraph) {
     const runs = Array.from(paragraph?.getElementsByTagNameNS?.(NS_W, 'r') || []);
     for (const run of runs) {
         if (hasWordAncestorWithin(run, 'del', paragraph)) continue;
+        if (hasWordAncestorWithin(run, 'moveFrom', paragraph)) continue;
         const text = readRunText(run);
         if (!text) continue;
         segments.push({

package/pipeline/ingestion-paragraph.js

@@ -217,13 +217,36 @@ function getNodeHandlers(runModel) {
         return contentResult;
     });
 
-    handlers.set('del', (child, offset) => {
-        const deletionEntry = processDeletion(child, offset);
-        if (deletionEntry) {
-            runModel.push(deletionEntry);
-        }
-        return { offset, text: '' };
-    });
+    handlers.set('del', (child, offset) => {
+        const deletionEntry = processDeletion(child, offset);
+        if (deletionEntry) {
+            runModel.push(deletionEntry);
+        }
+        return { offset, text: '' };
+    });
+
+    handlers.set('moveFrom', (child, offset) => {
+        const deletionEntry = processDeletion(child, offset);
+        if (deletionEntry) {
+            runModel.push(deletionEntry);
+        }
+        return { offset, text: '' };
+    });
+
+    handlers.set('moveTo', (child, offset) => processNodeRecursive(child, offset, runModel));
+
+    for (const markerName of ['moveFromRangeStart', 'moveFromRangeEnd', 'moveToRangeStart', 'moveToRangeEnd']) {
+        handlers.set(markerName, (child, offset) => {
+            runModel.push({
+                kind: RunKind.BOOKMARK,
+                nodeXml: serializeXml(child),
+                startOffset: offset,
+                endOffset: offset,
+                text: ''
+            });
+            return { offset, text: '' };
+        });
+    }
 
     handlers.set('bookmarkStart', (child, offset) => {
         runModel.push({
@@ -320,11 +343,13 @@ function processRun(runElement, startOffset) {
     };
 }
 
-function processDeletion(delElement, offset) {
-    const author = delElement.getAttribute('w:author') || '';
-
-    let text = '';
-    const delTexts = getElementsByTagNS(delElement, NS_W, 'delText');
+function processDeletion(delElement, offset) {
+    const author = delElement.getAttribute('w:author') || '';
+
+    // Deleted text is retained as a zero-width deletion model entry for revision-aware callers.
+    // It is intentionally not added to acceptedText by the w:del handler above.
+    let text = '';
+    const delTexts = getElementsByTagNS(delElement, NS_W, 'delText');
     for (const delText of delTexts) {
         text += delText.textContent || '';
     }

package/pipeline/ingestion-table.js

@@ -20,13 +20,16 @@ import { ingestParagraphElement } from './ingestion-paragraph.js';
  * @param {Element} tableNode - w:tbl element
  * @returns {Object}
  */
-export function ingestTableToVirtualGrid(tableNode) {
-    const tblGrid = getFirstElementByTagNS(tableNode, NS_W, 'tblGrid');
-    const gridCols = tblGrid ? getElementsByTagNS(tblGrid, NS_W, 'gridCol') : [];
-    const colCount = gridCols.length;
-
-    const trElements = getElementsByTagNS(tableNode, NS_W, 'tr');
-    const rowCount = trElements.length;
+export function ingestTableToVirtualGrid(tableNode) {
+    const tblGrid = getFirstElementByTagNS(tableNode, NS_W, 'tblGrid');
+    const gridCols = tblGrid ? getElementsByTagNS(tblGrid, NS_W, 'gridCol') : [];
+    const trElements = getElementsByTagNSOrTag(tableNode, NS_W, 'tr');
+    const rowCount = trElements.length;
+    const inferredColCount = trElements.reduce((max, tr) => {
+        const tcElements = getElementsByTagNSOrTag(tr, NS_W, 'tc');
+        return Math.max(max, tcElements.length);
+    }, 0);
+    const colCount = gridCols.length || inferredColCount;
 
     const grid = Array.from({ length: rowCount }, () =>
         Array.from({ length: colCount }, () => null)
@@ -36,7 +39,7 @@ export function ingestTableToVirtualGrid(tableNode) {
 
     for (let rowIdx = 0; rowIdx < trElements.length; rowIdx++) {
         const tr = trElements[rowIdx];
-        const tcElements = getElementsByTagNS(tr, NS_W, 'tc');
+        const tcElements = getElementsByTagNSOrTag(tr, NS_W, 'tc');
         let gridCol = 0;
 
         for (let tcIdx = 0; tcIdx < tcElements.length; tcIdx++) {

package/scripts/build.mjs

@@ -0,0 +1,40 @@
+import { build } from 'esbuild';
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entryPoint = resolve(repoRoot, 'index.js');
+const distDir = resolve(repoRoot, 'dist');
+const pkg = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8'));
+
+// ESM bundle with diff-match-patch inlined (for CDN/browser <script type="module">)
+await build({
+  entryPoints: [entryPoint],
+  bundle: true,
+  format: 'esm',
+  outfile: resolve(distDir, 'docx-redline-js.esm.js'),
+  platform: 'neutral',         // no Node builtins assumed
+  target: 'es2020',
+  minify: false,                // keep readable for debugging
+  sourcemap: true,
+  banner: {
+    js: `// @ansonlai/docx-redline-js v${pkg.version} — https://github.com/AnsonLai/docx-redline-js`
+  },
+  external: ['@xmldom/xmldom']  // never bundle the Node-only XML parser
+});
+
+// Minified version for production CDN use
+await build({
+  entryPoints: [entryPoint],
+  bundle: true,
+  format: 'esm',
+  outfile: resolve(distDir, 'docx-redline-js.esm.min.js'),
+  platform: 'neutral',
+  target: 'es2020',
+  minify: true,
+  sourcemap: true,
+  external: ['@xmldom/xmldom']
+});
+
+console.log('Build complete: dist/docx-redline-js.esm.js, dist/docx-redline-js.esm.min.js');

package/scripts/check-types.mjs

@@ -0,0 +1,29 @@
+import { readFileSync } from 'fs';
+
+const dts = readFileSync(new URL('../index.d.ts', import.meta.url), 'utf8');
+
+const requiredSnippets = [
+  'export interface RedlineOptions',
+  'export interface RedlineResult',
+  'export function applyRedlineToOxml',
+  'export function acceptTrackedChangesInOoxml',
+  'export function rejectTrackedChangesInOoxml',
+  'export function deleteCommentsByAuthorInOoxml',
+  'export function validateRedlineOoxml'
+];
+
+for (const snippet of requiredSnippets) {
+  if (!dts.includes(snippet)) {
+    throw new Error(`Missing declaration snippet: ${snippet}`);
+  }
+}
+
+let balance = 0;
+for (const char of dts) {
+  if (char === '{') balance += 1;
+  if (char === '}') balance -= 1;
+  if (balance < 0) throw new Error('index.d.ts has unbalanced braces');
+}
+if (balance !== 0) throw new Error('index.d.ts has unbalanced braces');
+
+console.log('PASS: index.d.ts declaration smoke check');

package/scripts/export-validation-fixtures.mjs

@@ -0,0 +1,125 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+import { configureXmlProvider } from '../adapters/xml-adapter.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { applyOperationToDocumentXml } from '../services/standalone-operation-runner.js';
+import { buildMinimalDocx } from './lib/minimal-zip.mjs';
+
+const { DOMParser, XMLSerializer } = await import('@xmldom/xmldom');
+configureXmlProvider({ DOMParser, XMLSerializer });
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const outputDir = join(process.cwd(), 'tmp', 'validation-docx');
+mkdirSync(outputDir, { recursive: true });
+
+const baseDocument = text => `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="${NS_W}">
+  <w:body>
+    <w:p><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>
+    <w:sectPr/>
+  </w:body>
+</w:document>`;
+
+const cases = [
+  {
+    name: 'simple-redline',
+    original: 'The old sentence.',
+    modified: 'The new sentence.'
+  },
+  {
+    name: 'paragraph-insert',
+    original: 'one',
+    modified: 'one\ntwo'
+  },
+  {
+    name: 'format-only',
+    original: 'Make word bold',
+    modified: 'Make **word** bold'
+  },
+  {
+    name: 'whitespace-heavy',
+    original: 'Alpha beta gamma delta.',
+    modified: 'Alpha  beta REPLACED delta.'
+  },
+  {
+    name: 'unicode-replace',
+    original: 'Term 条款 applies to café.',
+    modified: 'Term 合同 applies to café 🚀.'
+  }
+];
+
+let failures = 0;
+
+for (const testCase of cases) {
+  const result = await applyOperationToDocumentXml(
+    baseDocument(testCase.original),
+    { type: 'redline', target: testCase.original, modified: testCase.modified },
+    'Validation',
+    null,
+    { generateRedlines: true }
+  );
+
+  if (!result?.hasChanges || result?.status === 'error') {
+    console.error(`FAIL ${testCase.name}: redline did not apply (status=${result?.status}, error=${result?.error?.message})`);
+    failures++;
+    continue;
+  }
+
+  const validation = validateRedlineOoxml(result.documentXml);
+  const validationErrors = validation.issues.filter(issue => issue.severity === 'error');
+  if (validationErrors.length > 0) {
+    console.error(`FAIL ${testCase.name}: validateRedlineOoxml reported ${validationErrors.map(issue => issue.code).join(', ')}`);
+    failures++;
+    continue;
+  }
+
+  writeFileSync(join(outputDir, `${testCase.name}.document.xml`), result.documentXml, 'utf8');
+  if (result.numberingXml) {
+    writeFileSync(join(outputDir, `${testCase.name}.numbering.xml`), result.numberingXml, 'utf8');
+  }
+
+  const docx = buildMinimalDocx(result.documentXml, { numberingXml: result.numberingXml || null });
+  writeFileSync(join(outputDir, `${testCase.name}.docx`), docx);
+
+  // Expected text is derived from edit *intent*, not from this library's
+  // accept/reject transforms, so external consumers (Word COM, LibreOffice)
+  // act as independent oracles.
+  const expected = {
+    name: testCase.name,
+    expectedAcceptedText: preprocessMarkdown(testCase.modified).cleanText,
+    expectedRejectedText: testCase.original
+  };
+  writeFileSync(join(outputDir, `${testCase.name}.expected.json`), `${JSON.stringify(expected, null, 2)}\n`, 'utf8');
+
+  console.log(`wrote ${testCase.name}: .document.xml, .docx, .expected.json`);
+}
+
+writeFileSync(join(outputDir, 'README.md'), `# Validation Fixtures
+
+Generated by \`node scripts/export-validation-fixtures.mjs\`.
+
+Each case produces:
+
+- \`<name>.document.xml\` — the generated \`word/document.xml\` payload (for
+  XSD validation and manual inspection).
+- \`<name>.docx\` — a minimal package assembled by release tooling only (the
+  published library still has no zip dependency).
+- \`<name>.expected.json\` — the accept-all / reject-all plain-text outcomes
+  derived from edit intent, used by external-consumer differential checks.
+
+Validation entry points:
+
+- Word (differential accept/reject): \`npm run smoke:word:diff\`
+- LibreOffice parse check: \`soffice --headless --convert-to pdf *.docx\`
+- Schema check: \`xmllint --noout --schema wml.xsd *.document.xml\`
+  (transitional schemas from ECMA-376 Part 4; see docs/VALIDATION.md)
+`, 'utf8');
+
+if (failures > 0) {
+  console.error(`\n${failures} fixture case(s) failed.`);
+  process.exit(1);
+}
+
+console.log(`Wrote validation fixtures to ${outputDir}`);