@ansonlai/docx-redline-js 0.1.6 → 0.2.0

package/ARCHITECTURE.md

@@ -72,6 +72,8 @@ No Word add-in entrypoints or host-specific integration layers are part of this
   - Namespace-safe Word element creation, tracked-change detection, and OOXML payload source-shape helpers.
 - `core/types.js`
   - Shared model enums/types plus revision metadata generation and document-aware revision ID seeding.
+- `core/redline-validation.js`
+  - Runtime structural validation (`validateRedlineOoxml`) mirroring the test-suite invariants: no nested revisions, `w:delText` inside `w:del`, complete revision metadata, unique revision ids, preserved boundary whitespace.
 - `engine/oxml-engine.js`
   - Main reconciliation router, mode selection, existing-revision policy gate, and status/error result handling.
 - `engine/run-builders.js`
@@ -128,6 +130,8 @@ still be re-exported from `index.js`.
 - Do not write unknown `result.oxml` payloads directly into `word/document.xml`;
   normalize with `extractReplacementNodesFromOoxml(...)` or use
   `applyOperationToDocumentXml(...).documentXml` for full-document replacement.
+- Run `validateRedlineOoxml(oxml)` on generated output before packaging it;
+  it reports structural invariant violations as `{ valid, issues }`.
 
 
 ## Build Output
@@ -150,11 +154,23 @@ The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
 - `npm run check:types`
   - Smoke-checks `index.d.ts`.
 - `node scripts/export-validation-fixtures.mjs`
-  - Writes release-time validation fixtures to `tmp/validation-docx/`.
+  - Writes release-time validation fixtures to `tmp/validation-docx/` as
+    `word/document.xml` parts, assembled `.docx` files, and expected-text sidecars.
+- `tests/roundtrip_fuzz_tests.mjs` (part of `npm test`)
+  - Seeded fuzz sweep of the accept/reject round-trip invariant; tune with
+    `FUZZ_SEED` / `FUZZ_ITERATIONS`.
 - `npm run smoke:word -- path/to/file.docx`
   - Optional Windows/Word COM smoke test for a completed `.docx`.
-
-Use these checks before publishing or tagging.
+- `npm run smoke:word:diff`
+  - Windows/Word COM differential test: Word itself accepts/rejects the
+    generated fixtures and the resulting text is compared to expectations.
+- `bash scripts/validate-fixtures-xsd.sh`
+  - Validates exported fixtures against the ECMA-376 transitional `wml.xsd`.
+- `.github/workflows/validation.yml`
+  - Nightly independent-oracle validation: XSD schema check, LibreOffice
+    conversion, and an extended 20k-case fuzz sweep with a fresh seed.
+
+Use these checks before publishing or tagging. See `docs/VALIDATION.md`.
 
 ## Fast Orientation For Contributors
 

package/README.md

@@ -139,6 +139,7 @@ Common result fields:
 | `ingestOoxml(oxml)` | Flatten OOXML into an internal run model with offsets. |
 | `preprocessMarkdown(text)` | Normalize markdown and extract format hints. |
 | `containsTrackedChanges(xmlDoc)` | Detect `w:ins`, `w:del`, move revisions, property changes, and paragraph-mark revision markup in a parsed OOXML document/fragment. |
+| `validateRedlineOoxml(oxml)` | Validate generated redline OOXML against the package's structural invariants (no nested revisions, `w:delText` inside `w:del`, complete metadata, unique revision ids, preserved boundary whitespace). Returns `{ valid, issues }`; run it before writing output into a package. |
 
 ### Services
 
@@ -259,6 +260,20 @@ On Windows with desktop Word installed, you can smoke-test a completed `.docx`:
 npm run smoke:word -- path/to/file.docx
 ```
 
+To validate against Word as an independent oracle (Word itself accepts and
+rejects the generated revisions and the resulting text is compared to the
+expected outcomes):
+
+```bash
+node scripts/export-validation-fixtures.mjs
+npm run smoke:word:diff
+```
+
+A nightly GitHub Actions workflow additionally validates generated fixtures
+against the ECMA-376 transitional schemas (`xmllint`), opens them with
+LibreOffice, and runs an extended fuzz sweep of the accept/reject round-trip
+invariant with a fresh seed. See [docs/VALIDATION.md](./docs/VALIDATION.md).
+
 ## Architecture
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for module layout, data flow, and contributor guidance.

package/core/redline-validation.js

@@ -0,0 +1,156 @@
+/**
+ * Runtime structural validation for generated redline OOXML.
+ *
+ * Mirrors the invariants enforced by the test-suite round-trip harness so
+ * downstream consumers can verify output before writing it into a package:
+ * no nested revisions, deleted text uses w:delText, revision metadata is
+ * complete, revision ids are unique, and boundary whitespace is preserved.
+ */
+
+import { parseXml } from '../adapters/xml-adapter.js';
+import { NS_W } from './types.js';
+
+const REVISION_ID_ELEMENTS = new Set(['ins', 'del', 'rPrChange', 'pPrChange']);
+const REVISION_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T/;
+
+function localNameOf(node) {
+    return String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
+}
+
+function elementsByLocalName(root, name) {
+    return Array.from(root.getElementsByTagName('*')).filter(el => localNameOf(el) === name);
+}
+
+function wordAttribute(node, name) {
+    return node.getAttribute(`w:${name}`) || node.getAttribute(name) || '';
+}
+
+function xmlSpaceAttribute(node) {
+    return node.getAttribute('xml:space') ||
+        node.getAttribute('space') ||
+        node.getAttributeNS?.('http://www.w3.org/XML/1998/namespace', 'space') ||
+        '';
+}
+
+function isParagraphMarkRevision(node) {
+    return localNameOf(node.parentNode) === 'rPr';
+}
+
+function parseOoxmlForValidation(oxml) {
+    const attempt = xml => {
+        const doc = parseXml(xml);
+        const parseError = doc.getElementsByTagName('parsererror')[0];
+        if (parseError) {
+            throw new Error(parseError.textContent || 'XML parse error');
+        }
+        return doc;
+    };
+
+    try {
+        return { doc: attempt(oxml) };
+    } catch {
+        try {
+            return { doc: attempt(`<w:root xmlns:w="${NS_W}">${oxml}</w:root>`) };
+        } catch (error) {
+            return { error: error?.message || 'XML parse error' };
+        }
+    }
+}
+
+/**
+ * Validates redline OOXML against the package's structural invariants.
+ *
+ * Issue severities: 'error' issues indicate output Word may repair or
+ * mis-resolve; 'warning' issues are suspicious but tolerated by Word.
+ *
+ * @param {string} oxml - OOXML string (fragment, document, or package scope)
+ * @returns {{ valid: boolean, issues: Array<{ code: string, severity: 'error'|'warning', message: string }> }}
+ */
+export function validateRedlineOoxml(oxml) {
+    const issues = [];
+    const addIssue = (code, severity, message) => issues.push({ code, severity, message });
+
+    if (typeof oxml !== 'string' || oxml.trim() === '') {
+        addIssue('PARSE_ERROR', 'error', 'Input is not a non-empty OOXML string.');
+        return { valid: false, issues };
+    }
+
+    const { doc, error } = parseOoxmlForValidation(oxml);
+    if (!doc) {
+        addIssue('PARSE_ERROR', 'error', `OOXML does not parse as XML: ${error}`);
+        return { valid: false, issues };
+    }
+
+    const insElements = elementsByLocalName(doc, 'ins');
+    const delElements = elementsByLocalName(doc, 'del');
+    const revisions = insElements.concat(delElements);
+
+    // No w:ins/w:del nested inside another w:ins/w:del.
+    for (const revision of revisions) {
+        const nested = Array.from(revision.getElementsByTagName('*'))
+            .filter(el => el !== revision && ['ins', 'del'].includes(localNameOf(el)));
+        if (nested.length > 0) {
+            addIssue('NESTED_REVISION', 'error',
+                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") contains nested <${nested[0].nodeName}>.`);
+        }
+    }
+
+    // Deleted runs must carry w:delText, never w:t.
+    for (const del of delElements) {
+        const plainTextNodes = elementsByLocalName(del, 't');
+        if (plainTextNodes.length > 0) {
+            addIssue('DEL_CONTAINS_T', 'error',
+                `<w:del> (w:id="${wordAttribute(del, 'id')}") contains <w:t>; deleted text must use <w:delText>.`);
+        }
+    }
+
+    // Every revision needs complete metadata.
+    for (const revision of revisions) {
+        const missing = [];
+        if (!wordAttribute(revision, 'id')) missing.push('w:id');
+        if (!wordAttribute(revision, 'author')) missing.push('w:author');
+        if (!REVISION_DATE_PATTERN.test(wordAttribute(revision, 'date'))) missing.push('w:date');
+        if (missing.length > 0) {
+            addIssue('MISSING_REVISION_METADATA', 'error',
+                `<${revision.nodeName}> is missing or has malformed ${missing.join(', ')}.`);
+        }
+    }
+
+    // Revision ids must be unique among ins/del/rPrChange/pPrChange.
+    const seenIds = new Set();
+    for (const node of Array.from(doc.getElementsByTagName('*'))) {
+        if (!REVISION_ID_ELEMENTS.has(localNameOf(node))) continue;
+        const id = wordAttribute(node, 'id');
+        if (!id) continue;
+        if (seenIds.has(id)) {
+            addIssue('DUPLICATE_REVISION_ID', 'error', `Revision id ${id} appears more than once.`);
+        }
+        seenIds.add(id);
+    }
+
+    // Boundary whitespace requires xml:space="preserve".
+    const textNodes = elementsByLocalName(doc, 't').concat(elementsByLocalName(doc, 'delText'));
+    for (const node of textNodes) {
+        const text = node.textContent || '';
+        if (/^\s|\s$/.test(text) && xmlSpaceAttribute(node) !== 'preserve') {
+            addIssue('MISSING_SPACE_PRESERVE', 'error',
+                `<${node.nodeName}> has boundary whitespace without xml:space="preserve".`);
+        }
+        if (text === '') {
+            addIssue('EMPTY_TEXT_ELEMENT', 'warning', `<${node.nodeName}> is empty.`);
+        }
+    }
+
+    // Empty w:ins/w:del wrappers (paragraph-mark revisions inside w:rPr are
+    // legitimately empty and excluded).
+    for (const revision of revisions) {
+        if (isParagraphMarkRevision(revision)) continue;
+        const hasElementChild = Array.from(revision.childNodes || []).some(child => child.nodeType === 1);
+        if (!hasElementChild) {
+            addIssue('EMPTY_REVISION_WRAPPER', 'warning',
+                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") wraps no content.`);
+        }
+    }
+
+    return { valid: !issues.some(issue => issue.severity === 'error'), issues };
+}

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.1.6 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.2.0 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -7715,6 +7715,129 @@ async function executeSingleLineListStructuralFallback(plan, options = {}) {
   };
 }
 
+// core/redline-validation.js
+var REVISION_ID_ELEMENTS = /* @__PURE__ */ new Set(["ins", "del", "rPrChange", "pPrChange"]);
+var REVISION_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T/;
+function localNameOf(node) {
+  return String(node?.localName || node?.nodeName || "").replace(/^.*:/, "");
+}
+function elementsByLocalName(root, name) {
+  return Array.from(root.getElementsByTagName("*")).filter((el) => localNameOf(el) === name);
+}
+function wordAttribute(node, name) {
+  return node.getAttribute(`w:${name}`) || node.getAttribute(name) || "";
+}
+function xmlSpaceAttribute(node) {
+  return node.getAttribute("xml:space") || node.getAttribute("space") || node.getAttributeNS?.("http://www.w3.org/XML/1998/namespace", "space") || "";
+}
+function isParagraphMarkRevision(node) {
+  return localNameOf(node.parentNode) === "rPr";
+}
+function parseOoxmlForValidation(oxml) {
+  const attempt = (xml) => {
+    const doc = parseXml(xml);
+    const parseError = doc.getElementsByTagName("parsererror")[0];
+    if (parseError) {
+      throw new Error(parseError.textContent || "XML parse error");
+    }
+    return doc;
+  };
+  try {
+    return { doc: attempt(oxml) };
+  } catch {
+    try {
+      return { doc: attempt(`<w:root xmlns:w="${NS_W}">${oxml}</w:root>`) };
+    } catch (error2) {
+      return { error: error2?.message || "XML parse error" };
+    }
+  }
+}
+function validateRedlineOoxml(oxml) {
+  const issues = [];
+  const addIssue = (code, severity, message) => issues.push({ code, severity, message });
+  if (typeof oxml !== "string" || oxml.trim() === "") {
+    addIssue("PARSE_ERROR", "error", "Input is not a non-empty OOXML string.");
+    return { valid: false, issues };
+  }
+  const { doc, error: error2 } = parseOoxmlForValidation(oxml);
+  if (!doc) {
+    addIssue("PARSE_ERROR", "error", `OOXML does not parse as XML: ${error2}`);
+    return { valid: false, issues };
+  }
+  const insElements = elementsByLocalName(doc, "ins");
+  const delElements = elementsByLocalName(doc, "del");
+  const revisions = insElements.concat(delElements);
+  for (const revision of revisions) {
+    const nested = Array.from(revision.getElementsByTagName("*")).filter((el) => el !== revision && ["ins", "del"].includes(localNameOf(el)));
+    if (nested.length > 0) {
+      addIssue(
+        "NESTED_REVISION",
+        "error",
+        `<${revision.nodeName}> (w:id="${wordAttribute(revision, "id")}") contains nested <${nested[0].nodeName}>.`
+      );
+    }
+  }
+  for (const del of delElements) {
+    const plainTextNodes = elementsByLocalName(del, "t");
+    if (plainTextNodes.length > 0) {
+      addIssue(
+        "DEL_CONTAINS_T",
+        "error",
+        `<w:del> (w:id="${wordAttribute(del, "id")}") contains <w:t>; deleted text must use <w:delText>.`
+      );
+    }
+  }
+  for (const revision of revisions) {
+    const missing = [];
+    if (!wordAttribute(revision, "id")) missing.push("w:id");
+    if (!wordAttribute(revision, "author")) missing.push("w:author");
+    if (!REVISION_DATE_PATTERN.test(wordAttribute(revision, "date"))) missing.push("w:date");
+    if (missing.length > 0) {
+      addIssue(
+        "MISSING_REVISION_METADATA",
+        "error",
+        `<${revision.nodeName}> is missing or has malformed ${missing.join(", ")}.`
+      );
+    }
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const node of Array.from(doc.getElementsByTagName("*"))) {
+    if (!REVISION_ID_ELEMENTS.has(localNameOf(node))) continue;
+    const id = wordAttribute(node, "id");
+    if (!id) continue;
+    if (seenIds.has(id)) {
+      addIssue("DUPLICATE_REVISION_ID", "error", `Revision id ${id} appears more than once.`);
+    }
+    seenIds.add(id);
+  }
+  const textNodes = elementsByLocalName(doc, "t").concat(elementsByLocalName(doc, "delText"));
+  for (const node of textNodes) {
+    const text = node.textContent || "";
+    if (/^\s|\s$/.test(text) && xmlSpaceAttribute(node) !== "preserve") {
+      addIssue(
+        "MISSING_SPACE_PRESERVE",
+        "error",
+        `<${node.nodeName}> has boundary whitespace without xml:space="preserve".`
+      );
+    }
+    if (text === "") {
+      addIssue("EMPTY_TEXT_ELEMENT", "warning", `<${node.nodeName}> is empty.`);
+    }
+  }
+  for (const revision of revisions) {
+    if (isParagraphMarkRevision(revision)) continue;
+    const hasElementChild = Array.from(revision.childNodes || []).some((child) => child.nodeType === 1);
+    if (!hasElementChild) {
+      addIssue(
+        "EMPTY_REVISION_WRAPPER",
+        "warning",
+        `<${revision.nodeName}> (w:id="${wordAttribute(revision, "id")}") wraps no content.`
+      );
+    }
+  }
+  return { valid: !issues.some((issue) => issue.severity === "error"), issues };
+}
+
 // core/table-targeting.js
 function getDirectWordChildren(element, localName) {
   if (!element) return [];
@@ -9578,6 +9701,7 @@ export {
   synthesizeExpandedListScopeEdit,
   synthesizeTableMarkdownFromMultilineCellEdit,
   validateDocxPackage,
+  validateRedlineOoxml,
   wrapInDocumentFragment
 };
 //# sourceMappingURL=docx-redline-js.esm.js.map