@ansonlai/docx-redline-js 0.8.4 → 0.10.0

package/services/standalone-operation-runner.d.ts

@@ -42,6 +42,43 @@ export type HeaderFooterPartSelector =
   | string
   | { kind: 'header' | 'footer'; type?: 'default' | 'first' | 'even'; section?: number };
 
+/**
+ * Structured list-conversion diagnostic (`list-conversion-diagnostics-v1`). Warnings appear in
+ * `diagnostics` (and as `CODE: message` strings in `warnings`) on an operation that succeeded;
+ * the same details appear on `error` when the strict policy refuses the operation. They are
+ * unrelated to `REVISION_FIDELITY_VIOLATION`.
+ */
+export interface ListConversionDiagnostic {
+  code:
+    | 'LIST_MARKER_NOT_BOUND'
+    | 'UNSUPPORTED_LIST_CONVERSION'
+    | 'LIST_FORMAT_NOT_APPLIED'
+    | 'UNSUPPORTED_LIST_FORMAT_CHANGE'
+    | 'UNKNOWN_PARAGRAPH_FORMAT_PROPERTY';
+  severity: 'warning' | 'error';
+  message: string;
+  /** The literal marker text (for example `A.`) the edit introduced. */
+  listMarker?: string;
+  requestedList?: { kind: 'bullet' | 'numbered'; format: string };
+  /** The numbering definition the list item keeps (format-change diagnostics). */
+  sourceList?: { numId: string; level: number; kind: 'bullet' | 'numbered'; format: string };
+  targetExcerpt?: string;
+  operationIndex?: number;
+  /** Rejected `paragraph-format.properties` keys (UNKNOWN_PARAGRAPH_FORMAT_PROPERTY). */
+  properties?: string[];
+  recovery?: {
+    action: string;
+    hint?: string;
+    field?: string;
+    allowedValue?: string;
+    /**
+     * The list-format operation to send (add a target): convert-plain for LIST_MARKER_NOT_BOUND /
+     * UNSUPPORTED_LIST_CONVERSION, change-format (scope "list") for LIST_FORMAT_NOT_APPLIED / UNSUPPORTED_LIST_FORMAT_CHANGE.
+     */
+    suggestedOperation?: { type: 'list-format'; list: ListFormatRequest };
+  };
+}
+
 export interface DocumentOperationBase {
   operationId?: string;
   /** Target a header or footer instead of the body. Comments are not supported there. */
@@ -54,6 +91,11 @@ export interface DocumentOperationBase {
   existingRevisions?: ExistingRevisionsPolicy;
   pairReplacements?: boolean;
   insertionAffinity?: InsertionAffinity;
+  /**
+   * `'literal'` accepts list-marker text as literal text and suppresses LIST_MARKER_NOT_BOUND,
+   * UNSUPPORTED_LIST_CONVERSION, LIST_FORMAT_NOT_APPLIED and UNSUPPORTED_LIST_FORMAT_CHANGE for this operation.
+   */
+  listMarkers?: 'literal';
 }
 
 interface RedlineDocumentOperationCommon extends DocumentOperationBase {
@@ -148,12 +190,19 @@ export interface CharacterFormatProperties {
   fontFamily?: string | null;
 }
 
+/** Closed set. Unknown keys are rejected with INVALID_OPERATION (field `properties.<key>`) since 0.9.0. */
 export interface ParagraphFormatProperties {
   alignment?: 'left' | 'center' | 'right' | 'both';
   keepNext?: boolean;
   keepLines?: boolean;
   pageBreakBefore?: boolean;
   style?: string | null;
+  /**
+   * Binds the paragraph to an EXISTING list (`numId` and `level` as reported by inspect), or `null` to remove its direct
+   * list binding. Tracked as `w:pPrChange`; refuses `PARAGRAPH_NUMBERING_NOT_FOUND` when the numId/level is not defined.
+   * Capability `paragraph-numbering-binding-v1`.
+   */
+  numbering?: { numId: number | string; level?: number } | null;
 }
 
 export interface HighlightDocumentOperation extends DocumentOperationBase {
@@ -176,6 +225,108 @@ export interface ParagraphFormatDocumentOperation extends DocumentOperationBase
   properties: ParagraphFormatProperties;
 }
 
+export type ListNumberFormat = 'decimal' | 'upperLetter' | 'lowerLetter' | 'upperRoman' | 'lowerRoman' | 'bullet';
+
+/** `list-format` request. `convert-plain`: `list-format-v1` (CLI contract version 9); `change-format` and `join`: `list-format-change-v1`. */
+export type ListFormatRequest = ListFormatConvertPlainRequest | ListFormatChangeFormatRequest | ListFormatJoinRequest;
+
+/** `convert-plain` (`list-format-v1`): bind plain paragraphs to a NEW list. */
+export interface ListFormatConvertPlainRequest {
+  mode: 'convert-plain';
+  kind?: 'bullet' | 'numbered';
+  /** Required with `strip: 'none'`; with `strip: 'marker'` it must match the typed markers (and disambiguates `I.`/`C.`). */
+  format?: 'decimal' | 'upperLetter' | 'lowerLetter' | 'upperRoman' | 'lowerRoman' | 'bullet';
+  /** 0-8, default 0. */
+  level?: number;
+  /** `'marker'` (default) removes the typed marker as a tracked deletion; `'none'` keeps the text and only binds. */
+  strip?: 'marker' | 'none';
+  /** `strip: 'none'` only. Defaults to continuing the batch's previous converted list of the same format, else 1. */
+  start?: number;
+}
+
+/**
+ * `change-format` (`list-format-change-v1`): change the numbering format of the target's list. Allocates a NEW
+ * definition (copying the source levels and geometry, one level redefined) and rebinds the items with tracked
+ * `w:pPrChange`s; the shared definition is never edited, so Reject All restores the original labels.
+ */
+export interface ListFormatChangeFormatRequest {
+  mode: 'change-format';
+  kind?: 'bullet' | 'numbered';
+  /** The new format of the level (`kind: 'numbered'` alone is refused: name the format). */
+  format?: ListNumberFormat;
+  /** Level text: numbered `%1`..`%9` with the level's own placeholder (`"%1."`, `"(%2)"`); bullet: the bullet character. */
+  lvlText?: string;
+  /** Restart value of the level (the new definition's `w:start`); scope `'list'` only. */
+  start?: number;
+  /** The level to redefine; default: the one level the target paragraphs use. */
+  level?: number;
+  /** `'list'` (default): every live item of the list; `'range'`: the target range, which must run to the end of the list. */
+  scope?: 'list' | 'range';
+}
+
+/** `join` (`list-format-change-v1`): the target list (or a range running to its end) continues an earlier list. */
+export interface ListFormatJoinRequest {
+  mode: 'join';
+  /** An item of the earlier list to continue; bound at batch start like `target`. */
+  continueFrom: ParagraphTargetDescriptor;
+  scope?: 'list' | 'range';
+}
+
+/**
+ * Binds plain paragraphs (target, or target..targetEnd in one container) to a NEW list definition in place. The
+ * binding is a tracked `w:pPrChange`; the stripped marker is a tracked `w:del`. Each typed marker's value is the
+ * item's value, so Accept All renders the labels the text showed. Body only (no `part`); text changes belong in a
+ * separate single-paragraph `redline` of the same paragraph that keeps the typed marker exactly: the batch compiler
+ * lets that pair share one batch and runs the redline first ("1. Old" -> "1. New": redline the text, convert-plain
+ * strips "1. "); other pairs fail LIST_FORMAT_COMPOSITION_CONFLICT. Refusals: LIST_MARKER_NOT_FOUND, LIST_MARKER_AMBIGUOUS, LIST_MARKER_UNSUPPORTED,
+ * LIST_FORMAT_TARGET_IS_LIST, LIST_FORMAT_STYLE_NUMBERED, PARAGRAPH_FORMAT_REVISION_CONFLICT.
+ *
+ * `change-format` / `join` (`list-format-change-v1`) rebind existing list items with tracked `w:pPrChange`s. With
+ * `scope: 'list'` every rebound item counts as a write of the operation in the batch compiler: only a single-paragraph
+ * `redline` per item composes with it (LIST_FORMAT_COMPOSITION_CONFLICT `reason: list-rebind` otherwise).
+ * Refusals: LIST_FORMAT_TARGET_NOT_LIST, LIST_FORMAT_MIXED_RANGE, LIST_FORMAT_STYLE_LINKED, LIST_FORMAT_STYLE_NUMBERED,
+ * LIST_FORMAT_SPLIT_UNSUPPORTED, LIST_FORMAT_DEFINITION_UNSUPPORTED, LIST_FORMAT_JOIN_INVALID,
+ * PARAGRAPH_FORMAT_REVISION_CONFLICT; a no-op is `ok` with a LIST_FORMAT_UNCHANGED warning.
+ */
+export interface ListFormatDocumentOperation extends Omit<DocumentOperationBase, 'part'> {
+  type: 'list-format';
+  list: ListFormatRequest;
+  targetEnd?: ParagraphTargetDescriptor;
+  targetEndRef?: number | string | null;
+}
+
+/** What a `list-format` operation bound or rebound (`result.list`). */
+export type ListFormatResult = ListFormatConvertPlainResult | ListFormatRebindResult;
+
+/** `convert-plain` result. */
+export interface ListFormatConvertPlainResult {
+  mode: 'convert-plain';
+  format: 'decimal' | 'upperLetter' | 'lowerLetter' | 'upperRoman' | 'lowerRoman' | 'bullet';
+  level: number;
+  strip: 'marker' | 'none';
+  items: Array<{ paragraphIndex: number; paragraphId: string | null; marker: string | null; value: number | null; numId: string }>;
+  /** Paragraphs of the range left as they were: empty, or (strip 'marker') body text without a marker. */
+  skipped: Array<{ paragraphIndex: number; reason: 'empty' | 'no-marker' }>;
+}
+
+/** `change-format` / `join` result: every paragraph rebound (scope `'list'` includes items outside the target). */
+export interface ListFormatRebindResult {
+  mode: 'change-format' | 'join';
+  scope: 'list' | 'range';
+  sourceNumId: string;
+  /** change-format: the newly allocated numId; join: the continued list's numId. */
+  numId: string;
+  format?: ListNumberFormat;
+  level?: number;
+  lvlText?: string;
+  /** change-format: per-level `w:start` values of the new definition (carried restarts, split continuation, `start`). */
+  levelStarts?: Record<string, number>;
+  continueFrom?: { paragraphIndex: number | null; numId: string };
+  items: Array<{ paragraphIndex: number | null; paragraphId: string | null; level: number; numId: string; sourceNumId: string; inTarget: boolean }>;
+  /** Tracked-deleted paragraphs in the range keep their binding. */
+  skipped: Array<{ paragraphIndex: number | null; reason: 'tracked-deleted' }>;
+}
+
 export type DocumentOperation =
   | RedlineDocumentOperation
   | RestoreDocumentOperation
@@ -185,7 +336,8 @@ export type DocumentOperation =
   | CommentResolveDocumentOperation
   | HighlightDocumentOperation
   | CharacterFormatDocumentOperation
-  | ParagraphFormatDocumentOperation;
+  | ParagraphFormatDocumentOperation
+  | ListFormatDocumentOperation;
 
 export interface ResolvedDocumentTarget {
   index: number;
@@ -221,6 +373,20 @@ export interface StandaloneRunnerOptions {
   generateRedlines?: boolean;
   existingRevisions?: ExistingRevisionsPolicy;
   strictTargets?: boolean;
+  /**
+   * Make list-conversion diagnostics errors (UNSUPPORTED_LIST_CONVERSION, UNSUPPORTED_LIST_FORMAT_CHANGE)
+   * instead of warnings. Defaults to `atomic`; the CLI agent profile sets it. An operation's
+   * `listMarkers: 'literal'` always wins.
+   */
+  strictListConversion?: boolean;
+  /**
+   * Post-apply check that Word's Reject All of each tracked operation's output equals the source
+   * (paragraph count, text, properties, numbering, wrapper membership). Default `'enforce'` refuses
+   * the operation with `REVISION_FIDELITY_VIOLATION` (per-invariant `violations[]` and
+   * `recovery.retryGuidance`); `'warn'` applies it and appends the same message to `warnings`;
+   * `'off'` is for diagnosis only.
+   */
+  verifyRevisionFidelity?: 'enforce' | 'warn' | 'off';
   expectedRevision?: RevisionToken;
   pairReplacements?: boolean;
   insertionAffinity?: InsertionAffinity;
@@ -288,30 +454,36 @@ export interface DocumentOperationResult {
   commentsXmlMode?: 'merge' | 'replace';
   commentsExtendedXmlMode?: 'merge' | 'replace';
   warnings?: string[];
+  diagnostics?: ListConversionDiagnostic[];
   status?: RedlineStatus;
   error?: RedlineError;
-  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format';
+  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format' | 'list-format';
   authorUsed: string;
   resolvedBy?: string;
   resolvedTarget?: ResolvedDocumentTarget;
   resolvedAnchor?: ResolvedCommentAnchor;
   receipt?: MutationReceipt;
   change?: LocalizedReplacementChange;
+  /** `list-format` operations: what was bound. */
+  list?: ListFormatResult;
 }
 
 export interface BatchOperationItemResult {
   index: number;
   type: string;
-  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format';
+  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format' | 'list-format';
   status: 'applied' | 'no_change' | 'error';
   authorUsed: string;
   resolvedBy?: string;
   resolvedTarget?: ResolvedDocumentTarget;
   resolvedAnchor?: ResolvedCommentAnchor;
   warnings?: string[];
+  diagnostics?: ListConversionDiagnostic[];
   error?: RedlineError;
   receipt?: MutationReceipt;
   change?: LocalizedReplacementChange;
+  /** `list-format` operations: what was bound. */
+  list?: ListFormatResult;
 }
 
 export interface DocumentOperationBatchResult {
@@ -347,7 +519,7 @@ export interface MutationRetryPlan {
 export interface OperationPreflightItemResult {
   index: number;
   type: string;
-  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format';
+  operationType: 'redline' | 'comment' | 'comment_reply' | 'comment_resolve' | 'highlight' | 'format' | 'paragraph-format' | 'list-format';
   status: 'ready' | 'deferred' | 'error';
   authorUsed: string;
   resolvedBy?: string;
@@ -375,10 +547,15 @@ export interface OperationPreflightItemResult {
 }
 
 export interface OperationConflict {
-  code: 'OVERLAPPING_SOURCE_TARGETS' | 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | 'CAPTURE_FANOUT_CONFLICT' | string;
+  code: 'OVERLAPPING_SOURCE_TARGETS' | 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | 'LIST_FORMAT_COMPOSITION_CONFLICT' | 'CAPTURE_FANOUT_CONFLICT' | string;
   message: string;
   operationIndexes: number[];
   target: ResolvedDocumentTarget;
+  /** LIST_FORMAT_COMPOSITION_CONFLICT: why the redline and the list-format do not compose. */
+  reason?: 'marker-changed' | 'redline-unchanged' | 'redline-shape' | 'list-rebind' | string;
+  sourceMarker?: string | null;
+  modifiedMarker?: string | null;
+  rebindingOperationIndexes?: number[];
   recoveryVersion?: number;
   category?: string;
   recovery?: RedlineError['recovery'];

package/services/table-reconciliation.js

@@ -8,7 +8,8 @@ import { computeWordLevelDiffOps } from '../pipeline/diff-engine.js';
 import { splitRunsAtDiffBoundaries, applyPatches } from '../pipeline/patching.js';
 import { serializeToOoxml } from '../pipeline/serialization.js';
 import { createRevisionMetadata, escapeXml, RunKind } from '../core/types.js';
-import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { paragraphMarkPPrXml } from '../engine/paragraph-mark-revisions.js';
 
 /**
  * Generates a new w:tbl OOXML structure from Markdown table data.
@@ -75,10 +76,7 @@ export function generateTableOoxml(tableData, options = {}) {
                 endOffset: cleanText.length
             }];
 
-            const cellMarkMeta = trackRows ? createRevisionMetadata(author, revisionIdAllocator) : null;
-            const cellPPr = cellMarkMeta
-                ? `<w:pPr><w:rPr><w:ins w:id="${cellMarkMeta.id}" w:author="${escapeXml(cellMarkMeta.author)}" w:date="${cellMarkMeta.date}"/></w:rPr></w:pPr>`
-                : null;
+            const cellPPr = trackRows ? paragraphMarkPPrXml('ins', { author, revisionIdAllocator }) : null;
             const runsOoxml = serializeToOoxml(runModel, cellPPr, formatHints, {
                 author,
                 generateRedlines,
@@ -153,8 +151,9 @@ export function diffTablesWithVirtualGrid(oldGrid, newTableData) {
             if (col > oldCell.gridCol) continue;
 
             if (newCellText !== undefined) {
-                const oldText = oldCell.getText();
-                if (oldText !== newCellText) {
+                // Markdown cannot represent a cell's trailing empty paragraphs, so they do not count as a change.
+                const oldText = trimTrailingNewlines(oldCell.getText());
+                if (oldText !== trimTrailingNewlines(newCellText)) {
                     operations.push({
                         type: 'cell_modify',
                         gridRow: row,
@@ -311,7 +310,60 @@ function buildTableOperationIndex(operations) {
     };
 }
 
+function trimTrailingNewlines(text) {
+    return typeof text === 'string' ? text.replace(/\n+$/, '') : text;
+}
+
+/**
+ * Reconciles a multi-paragraph cell paragraph by paragraph so unchanged paragraphs (including
+ * empty ones the Markdown cell text cannot express) are preserved exactly.
+ */
+function reconcileMultiBlockCellContent(cell, newText, options) {
+    const { generateRedlines, author, revisionIdAllocator = null } = options;
+    const lines = String(newText ?? '').split('\n');
+    // Trailing blank lines carry no content; never create inserted paragraphs from them.
+    while (lines.length > cell.blocks.length && lines[lines.length - 1] === '') lines.pop();
+    let out = '';
+
+    cell.blocks.forEach((block, index) => {
+        const line = lines[index];
+        if (line === undefined || line === block.acceptedText) {
+            if (line === undefined && block.acceptedText !== '') {
+                // Markdown dropped this paragraph's text: track the text deletion.
+                const diffOps = computeWordLevelDiffOps(block.acceptedText, '');
+                const model = applyPatches(splitRunsAtDiffBoundaries(block.runModel, diffOps), diffOps, {
+                    generateRedlines, author, formatHints: []
+                });
+                out += serializeToOoxml(model, block.pPr, [], { author, generateRedlines, revisionIdAllocator });
+            } else {
+                out += serializeToOoxml(block.runModel, block.pPr, [], {});
+            }
+            return;
+        }
+        const { cleanText, formatHints } = preprocessMarkdown(line);
+        const diffOps = computeWordLevelDiffOps(block.acceptedText, cleanText);
+        const model = applyPatches(splitRunsAtDiffBoundaries(block.runModel, diffOps), diffOps, {
+            generateRedlines, author, formatHints
+        });
+        out += serializeToOoxml(model, block.pPr, formatHints, { author, generateRedlines, revisionIdAllocator });
+    });
+
+    for (let i = cell.blocks.length; i < lines.length; i++) {
+        const { cleanText, formatHints } = preprocessMarkdown(lines[i]);
+        const runModel = [{
+            kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
+            text: cleanText, rPrXml: '', author, startOffset: 0, endOffset: cleanText.length
+        }];
+        const pPr = generateRedlines ? paragraphMarkPPrXml('ins', { author, revisionIdAllocator }) : null;
+        out += serializeToOoxml(runModel, pPr, formatHints, { author, generateRedlines, revisionIdAllocator });
+    }
+    return out;
+}
+
 function reconcileCellContent(cell, newText, options) {
+    if (cell.blocks.length > 1) {
+        return reconcileMultiBlockCellContent(cell, newText, options);
+    }
     const { generateRedlines, author, revisionIdAllocator = null } = options;
     const { cleanText, formatHints } = preprocessMarkdown(newText);