@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/engine/table-mode.js

@@ -2,30 +2,30 @@
  * Table-specific reconciliation and transformation flows.
  */
 
-import {
-    NS_W,
-    createRevisionMetadata,
-    getRevisionIdAllocatorForDocument,
-    setRevisionIdAllocatorForDocument
-} from '../core/types.js';
-import {
-    getElementsByTagNS,
-    getElementsByTagNSOrTag,
-    getFirstElementByTagNS,
-    getFirstElementByTagNSOrTag,
-    getXmlParseError
-} from '../core/xml-query.js';
-import { parseOoxmlSafe } from '../adapters/xml-adapter.js';
-import { log, error } from '../adapters/logger.js';
-import { diffTablesWithVirtualGrid, serializeVirtualGridToOoxml, generateTableOoxml } from '../services/table-reconciliation.js';
-import { parseTable } from '../pipeline/pipeline.js';
-import { ingestTableToVirtualGrid } from '../pipeline/ingestion.js';
-import { createWordElement, withOoxmlSourceType } from '../core/word-xml.js';
-import { markParagraphMarkDeleted } from './run-builders.js';
-
-function noChanges(serializer, xmlDoc) {
-    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges: false });
-}
+import {
+    NS_W,
+    createRevisionMetadata,
+    getRevisionIdAllocatorForDocument,
+    setRevisionIdAllocatorForDocument
+} from '../core/types.js';
+import {
+    getElementsByTagNS,
+    getElementsByTagNSOrTag,
+    getFirstElementByTagNS,
+    getFirstElementByTagNSOrTag,
+    getXmlParseError
+} from '../core/xml-query.js';
+import { parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { log, error } from '../adapters/logger.js';
+import { diffTablesWithVirtualGrid, serializeVirtualGridToOoxml, generateTableOoxml } from '../services/table-reconciliation.js';
+import { parseTable } from '../pipeline/pipeline.js';
+import { ingestTableToVirtualGrid } from '../pipeline/ingestion.js';
+import { createWordElement, withOoxmlSourceType } from '../core/word-xml.js';
+import { markParagraphDeleted } from './paragraph-mark-revisions.js';
+
+function noChanges(serializer, xmlDoc) {
+    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges: false });
+}
 
 /**
  * Applies structural reconciliation to tables using Virtual Grid.
@@ -38,8 +38,8 @@ function noChanges(serializer, xmlDoc) {
  * @param {boolean} [generateRedlines=true] - Track change toggle
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines = true) {
-    const tableNodes = getElementsByTagNSOrTag(xmlDoc, NS_W, 'tbl');
+export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines = true) {
+    const tableNodes = getElementsByTagNSOrTag(xmlDoc, NS_W, 'tbl');
     const newTableData = parseTable(modifiedText);
     const hasNewContent = newTableData.rows.length > 0 || newTableData.headers.length > 0;
 
@@ -55,15 +55,15 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
         return noChanges(serializer, xmlDoc);
     }
 
-    const options = {
-        generateRedlines,
-        author,
-        revisionIdAllocator: getRevisionIdAllocatorForDocument(xmlDoc)
-    };
+    const options = {
+        generateRedlines,
+        author,
+        revisionIdAllocator: getRevisionIdAllocatorForDocument(xmlDoc)
+    };
     const reconciledOxml = serializeVirtualGridToOoxml(oldGrid, operations, options);
     const wrappedOxml = `<root xmlns:w="${NS_W}">${reconciledOxml}</root>`;
-    const reconciledDoc = parseOoxmlSafe(wrappedOxml, 'application/xml').doc;
-    if (!reconciledDoc) return noChanges(serializer, xmlDoc);
+    const reconciledDoc = parseOoxmlSafe(wrappedOxml, 'application/xml').doc;
+    if (!reconciledDoc) return noChanges(serializer, xmlDoc);
 
     const parseError = getXmlParseError(reconciledDoc);
     if (parseError) {
@@ -71,7 +71,7 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
         return noChanges(serializer, xmlDoc);
     }
 
-    const newTableNode = getFirstElementByTagNSOrTag(reconciledDoc, NS_W, 'tbl');
+    const newTableNode = getFirstElementByTagNSOrTag(reconciledDoc, NS_W, 'tbl');
     if (!newTableNode) {
         error('[OxmlEngine] No table found in reconciled OOXML');
         return noChanges(serializer, xmlDoc);
@@ -80,7 +80,7 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
     const importedTable = xmlDoc.importNode(newTableNode, true);
     targetTable.parentNode.replaceChild(importedTable, targetTable);
 
-    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges: true });
+    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges: true });
 }
 
 /**
@@ -94,17 +94,17 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
  * @param {boolean} generateRedlines - Track change toggle
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines) {
-    const revisionIdAllocator = getRevisionIdAllocatorForDocument(xmlDoc);
+export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines) {
+    const revisionIdAllocator = getRevisionIdAllocatorForDocument(xmlDoc);
     const tableData = parseTable(modifiedText);
     if (!tableData || (tableData.rows.length === 0 && tableData.headers.length === 0)) {
         log('[OxmlEngine] Failed to parse table data from Markdown');
         return noChanges(serializer, xmlDoc);
     }
 
-    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author, revisionIdAllocator });
-    const tableDoc = parseOoxmlSafe(`<root xmlns:w="${NS_W}">${tableOoxml}</root>`, 'application/xml').doc;
-    if (!tableDoc) return noChanges(serializer, xmlDoc);
+    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author, revisionIdAllocator, trackAsBlock: true });
+    const tableDoc = parseOoxmlSafe(`<root xmlns:w="${NS_W}">${tableOoxml}</root>`, 'application/xml').doc;
+    if (!tableDoc) return noChanges(serializer, xmlDoc);
 
     const tableParseError = getXmlParseError(tableDoc);
     if (tableParseError) {
@@ -132,16 +132,16 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
     let parent = firstParagraph.parentNode;
 
     if (parent && parent.nodeType === 9) {
-        const wrappedDoc = parseOoxmlSafe(
-            `<w:document xmlns:w="${NS_W}"><w:body/></w:document>`,
-            'application/xml'
-        ).doc;
-        if (!wrappedDoc) return noChanges(serializer, workingDoc);
+        const wrappedDoc = parseOoxmlSafe(
+            `<w:document xmlns:w="${NS_W}"><w:body/></w:document>`,
+            'application/xml'
+        ).doc;
+        if (!wrappedDoc) return noChanges(serializer, workingDoc);
         const wrappedBody = getFirstElementByTagNS(wrappedDoc, NS_W, 'body');
         paragraphs.forEach(p => wrappedBody.appendChild(wrappedDoc.importNode(p, true)));
 
-        workingDoc = wrappedDoc;
-        setRevisionIdAllocatorForDocument(workingDoc, revisionIdAllocator);
+        workingDoc = wrappedDoc;
+        setRevisionIdAllocatorForDocument(workingDoc, revisionIdAllocator);
         paragraphs = getElementsByTagNS(workingDoc, NS_W, 'p');
         firstParagraph = paragraphs[0];
         parent = firstParagraph.parentNode;
@@ -149,26 +149,26 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
 
     const importedTable = workingDoc.importNode(newTableElement, true);
 
-    if (generateRedlines) {
-        paragraphs.forEach(p => {
-            markParagraphMarkDeleted(workingDoc, p, author);
-            const runs = getElementsByTagNS(p, NS_W, 'r');
-            runs.forEach(run => {
+    if (generateRedlines) {
+        paragraphs.forEach(p => {
+            markParagraphDeleted(p, { author, revisionIdAllocator: workingDoc });
+            const runs = getElementsByTagNS(p, NS_W, 'r');
+            runs.forEach(run => {
                 const textNodes = getElementsByTagNS(run, NS_W, 't');
                 textNodes.forEach(t => {
                     const text = t.textContent || '';
                     if (text.trim()) {
-                        const delText = createWordElement(workingDoc, 'w:delText');
-                        delText.textContent = text;
-                        t.parentNode.replaceChild(delText, t);
+                        const delText = createWordElement(workingDoc, 'w:delText');
+                        delText.textContent = text;
+                        t.parentNode.replaceChild(delText, t);
                     }
                 });
-
-                const del = createWordElement(workingDoc, 'w:del');
-                const metadata = createRevisionMetadata(author, workingDoc, 'del');
-                del.setAttribute('w:id', String(metadata.id));
-                del.setAttribute('w:author', metadata.author);
-                del.setAttribute('w:date', metadata.date);
+
+                const del = createWordElement(workingDoc, 'w:del');
+                const metadata = createRevisionMetadata(author, workingDoc, 'del');
+                del.setAttribute('w:id', String(metadata.id));
+                del.setAttribute('w:author', metadata.author);
+                del.setAttribute('w:date', metadata.date);
                 run.parentNode.insertBefore(del, run);
                 del.appendChild(run);
             });
@@ -183,5 +183,5 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
     }
 
     log('[OxmlEngine] Text-to-table transformation complete');
-    return withOoxmlSourceType({ oxml: serializer.serializeToString(workingDoc), hasChanges: true });
-}
+    return withOoxmlSourceType({ oxml: serializer.serializeToString(workingDoc), hasChanges: true });
+}

package/index.d.ts

@@ -30,6 +30,16 @@ export type {
   DocumentOperationBatchResult,
   HighlightDocumentOperation,
   InsertionAffinity,
+  ListConversionDiagnostic,
+  ListFormatDocumentOperation,
+  ListFormatRequest,
+  ListFormatConvertPlainRequest,
+  ListFormatChangeFormatRequest,
+  ListFormatJoinRequest,
+  ListFormatResult,
+  ListFormatConvertPlainResult,
+  ListFormatRebindResult,
+  ListNumberFormat,
   LocalizedReplacement,
   LocalizedReplacementChange,
   OperationConflict,
@@ -52,6 +62,13 @@ export interface RedlineError {
     | 'DIFF_TOKEN_LIMIT'
     | 'UNSUPPORTED_REVISION_VIEW_MUTATION'
     | 'UNSUPPORTED_INSERTION_AFFINITY'
+    | 'UNSUPPORTED_LIST_CONVERSION'
+    | 'UNSUPPORTED_LIST_FORMAT_CHANGE'
+    | 'LIST_MARKER_NOT_FOUND'
+    | 'LIST_MARKER_AMBIGUOUS'
+    | 'LIST_MARKER_UNSUPPORTED'
+    | 'LIST_FORMAT_TARGET_IS_LIST'
+    | 'LIST_FORMAT_STYLE_NUMBERED'
     | 'UNSAFE_PARAGRAPH_BOUNDARY'
     | 'FOREIGN_PARAGRAPH_MARK_DELETION'
     | 'RESTORATION_STATE_REQUIRED'
@@ -80,6 +97,11 @@ export interface RedlineError {
   recoveryVersion?: number;
   category?: 'request_fixable' | 'target_refresh_required' | 'candidate_selection_required' | 'policy_choice_required' | 'user_authorization_required' | 'source_conflict' | 'library_or_builder_failure' | 'manual_document_resolution' | string;
   context?: Record<string, unknown>;
+  /** List-conversion errors: the literal marker, the requested list kind/format and the kept source definition. */
+  listMarker?: string;
+  requestedList?: { kind: 'bullet' | 'numbered'; format: string };
+  sourceList?: { numId: string; level: number; kind: 'bullet' | 'numbered'; format: string };
+  targetExcerpt?: string;
   recovery?: {
     action: string;
     sameArgumentsSafe: boolean;
@@ -87,6 +109,8 @@ export interface RedlineError {
     requiresUserAuthorization: boolean;
     field?: string;
     recommendedValue?: unknown;
+    allowedValue?: unknown;
+    hint?: string;
   };
   expectedRevision?: RevisionToken;
   currentRevision?: RevisionToken;
@@ -105,6 +129,10 @@ export interface RedlineOptions {
   structuredContent?: boolean;
   pairReplacements?: boolean;
   insertionAffinity?: InsertionAffinity;
+  /** Source numbering part; generated list definitions are remapped to IDs that do not collide with it. */
+  numberingXml?: string | null;
+  /** Shared numbering ID state (from `createDynamicNumberingIdState`) for allocation across calls. */
+  numberingIdState?: unknown;
   [key: string]: unknown;
 }
 
@@ -433,7 +461,29 @@ export function overwriteParagraphNumIds(oxml: string, numId: string | number):
 export function extractFirstParagraphNumId(oxml: string): string | null;
 export function buildExplicitDecimalMultilevelNumberingXml(options?: Record<string, unknown>): string;
 export function remapNumberingPayloadForDocument(numberingXml: string, state: unknown): unknown;
-export function mergeNumberingXmlBySchemaOrder(baseXml: string, incomingXml: string): string;
+export interface NumberingIdConflict { kind: 'abstractNum' | 'num'; id: number }
+export interface NumberingMergeOptions { onConflict?: (conflict: NumberingIdConflict) => void }
+export interface NumberingIntegrityIssue { code: string; severity: 'error'; message: string; numId?: number; abstractNumId?: number; ilvl?: number }
+export function mergeNumberingXmlBySchemaOrder(baseXml: string, incomingXml: string, options?: NumberingMergeOptions): string;
+export function mergeNumberingParts(existingXml: string | null | undefined, incomingParts: string | Array<string | null | undefined> | null | undefined, options?: NumberingMergeOptions): string;
+export function allocateNumberingDefinition(params: {
+    numberingIdState: unknown;
+    sourceNumberingXml?: string | null;
+    sourceNumId?: number | string | null;
+    levels?: Array<{ ilvl: number; numFmt?: string; lvlText?: string; start?: number }>;
+    startOverrides?: Record<number | string, number>;
+}): { numId: number; abstractNumId: number; numberingXml: string } | null;
+export function allocateNumberingForReplacement(params: {
+    numberingXml: string | null;
+    replacementNodes: unknown[];
+    sourceParagraphs?: unknown[];
+    numberingIdState?: unknown;
+    allowContinueSource?: boolean;
+}): { policy: 'continue-source' | 'allocate' | 'passthrough'; numberingXml: string | null; replacementNodes: unknown[]; numId?: number };
+export function applyStartOverridesToNum(numElement: unknown, startOverrides: Record<number | string, number>): void;
+export function copyLevelGeometry(sourceLvl: unknown, targetLvl: unknown): void;
+export function canonicalNumberingDefinition(numbering: unknown, numId: string | number): string | null;
+export function validateNumberingIntegrity(documentXml: unknown, numberingXml?: unknown): NumberingIntegrityIssue[];
 
 export function buildListMarkdown(items: unknown[], options?: Record<string, unknown>): string;
 export function inferNumberingStyleFromMarker(marker: string): string;

package/index.js

@@ -21,10 +21,44 @@ import {
     executeSingleLineListStructuralFallback
 } from './orchestration/list-structural-fallback.js';
 import { withOoxmlSourceType } from './core/word-xml.js';
+import { createDynamicNumberingIdState, remapNumberingPayloadForDocument } from './services/numbering-helpers.js';
 export { containsTrackedChanges, getTrackedChangeAuthors } from './core/word-xml.js';
 export { validateRedlineOoxml } from './core/redline-validation.js';
 export { analyzeStructuredContent, planStructuredReplacement } from './pipeline/structured-content.js';
 
+/**
+ * When the caller supplies the source `numberingXml` (or a numbering ID state), generated list
+ * definitions are remapped to IDs that cannot collide with any existing `w:num`/`w:abstractNum`.
+ */
+function remapGeneratedNumberingForSource(result, options) {
+    const sourceNumbering = typeof options?.numberingXml === 'string' && options.numberingXml.trim()
+        ? options.numberingXml
+        : null;
+    const state = options?.numberingIdState && typeof options.numberingIdState === 'object'
+        ? options.numberingIdState
+        : (sourceNumbering ? createDynamicNumberingIdState(sourceNumbering) : null);
+    if (!state || !result?.hasChanges || typeof result.oxml !== 'string' || !result.oxml.includes('/word/numbering.xml')) {
+        return result;
+    }
+    const pkgDoc = parseOoxml(result.oxml);
+    const parts = Array.from(pkgDoc.getElementsByTagNameNS('*', 'part'));
+    const payloadOf = name => {
+        const part = parts.find(candidate => (candidate.getAttribute('pkg:name') || candidate.getAttribute('name')) === name);
+        const xmlData = part?.getElementsByTagNameNS('*', 'xmlData')[0];
+        return xmlData ? Array.from(xmlData.childNodes).find(node => node.nodeType === 1) || null : null;
+    };
+    const numberingNode = payloadOf('/word/numbering.xml');
+    const body = payloadOf('/word/document.xml')?.getElementsByTagNameNS('*', 'body')[0];
+    if (!numberingNode || !body) return result;
+
+    const bodyNodes = Array.from(body.childNodes).filter(node => node.nodeType === 1 && node.localName !== 'sectPr');
+    const remapped = remapNumberingPayloadForDocument(serializeOoxml(numberingNode), bodyNodes, state);
+    const newNumbering = pkgDoc.importNode(parseOoxml(remapped.numberingXml).documentElement, true);
+    numberingNode.parentNode.replaceChild(newNumbering, numberingNode);
+    bodyNodes.forEach((node, index) => body.replaceChild(remapped.replacementNodes[index], node));
+    return { ...result, oxml: serializeOoxml(pkgDoc) };
+}
+
 /**
  * Standalone-safe redline wrapper.
  *
@@ -33,7 +67,8 @@ export { analyzeStructuredContent, planStructuredReplacement } from './pipeline/
  * 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);
+    const rawResult = await applyRedlineToOxmlEngine(oxml, originalText, modifiedText, options);
+    const result = remapGeneratedNumberingForSource(rawResult, options);
     if (result?.useNativeApi && typeof result?.oxml !== 'string') {
         const existingWarnings = Array.isArray(result?.warnings) ? result.warnings : [];
         return withOoxmlSourceType({
@@ -225,9 +260,18 @@ export {
     overwriteParagraphNumIds,
     extractFirstParagraphNumId,
     buildExplicitDecimalMultilevelNumberingXml,
-    remapNumberingPayloadForDocument,
-    mergeNumberingXmlBySchemaOrder
+    remapNumberingPayloadForDocument
 } from './services/numbering-helpers.js';
+export {
+    allocateNumberingDefinition,
+    allocateNumberingForReplacement,
+    applyStartOverridesToNum,
+    canonicalNumberingDefinition,
+    copyLevelGeometry,
+    mergeNumberingParts,
+    mergeNumberingXmlBySchemaOrder,
+    validateNumberingIntegrity
+} from './services/numbering-allocation.js';
 
 // Pipeline components
 export { ReconciliationPipeline } from './pipeline/pipeline.js';

package/node/cli-help.js

@@ -144,6 +144,7 @@ export const CLI_COMMAND_HELP = Object.freeze({
             option('textToComment', '--text-to-comment <text>', 'Anchor an inline comment to an exact subspan.'),
             option('targetRef', '--target-ref <N>', 'Disambiguate an inline target with a 1-based machine index.'),
             option('existingRevisions', '--existing-revisions <policy>', 'Select revision handling; cross-author slicing must be deliberate.'),
+            option('revisionFidelity', '--revision-fidelity <enforce|warn|off>', 'Reject All verification of each tracked operation (default enforce: refuse with REVISION_FIDELITY_VIOLATION); the agent profile rejects off.'),
             option('atomic', '--atomic[=true|false]', 'Choose all-or-nothing or progressive batch execution.'),
             option('generateRedlines', '--generate-redlines[=true|false]', 'Control tracked-change generation.'),
             option('noRedlines', '--no-redlines', 'Apply clean text without tracked-change markup.'),