@ansonlai/docx-redline-js 0.8.4 → 0.9.0

package/README.md

@@ -15,14 +15,19 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Comment management: delete comments by author or for all authors
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
+- Reject All verification: every tracked operation is refused unless Word's Reject All of the output reproduces the source
 - Status/error result fields for parse, targeting, and existing-revision failures
 - Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
 - Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
 - Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
 
-## What's New in 0.8.x
+## What's New in 0.9.0 and 0.8.x
 
-The current release is 0.8.4. The CLI contract remains version 8 throughout the 0.8 line.
+0.9.0 moves the CLI contract to version 9 and adds the `list-format` operation (`convert-plain`, `change-format`, `join`),
+`paragraph-format` numbering binding, list-conversion diagnostics, a single numbering allocator and merge, and a Reject All
+revision fidelity verifier that refuses by default (`REVISION_FIDELITY_VIOLATION`). See the
+[0.9.0 release notes](./docs/releases/0.9.0.md) and the [CHANGELOG](./CHANGELOG.md). The CLI contract was version 8
+throughout the 0.8 line.
 
 - **0.8.0, universal document facade:** `openDocx` and `DocxDocument` are exported from the primary entry point and work
   on `Uint8Array` input in any JavaScript runtime. ZIP handling uses `fflate` and SHA-256 is pure JavaScript, so there are no
@@ -311,7 +316,9 @@ marker. Machine `index` and `ref` fields are for targeting and pagination, not
 user-facing Word locations; use `humanReference`, `provision`, or
 `nearestHeading` in reports.
 
-`docx-redline version` reports contract version 8 and the additive
+`docx-redline version` reports contract version 9 (adds the `list-format` operation type). Contract 9 adds the
+capabilities `revision-fidelity-v1`, `list-conversion-diagnostics-v1`, `paragraph-numbering-binding-v1`,
+`list-format-v1` (`convert-plain`) and `list-format-change-v1` (`change-format` and `join`), alongside the additive
 `command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
 `human-document-references-v1`, `batch-start-source-binding`,
 `recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
@@ -320,7 +327,9 @@ user-facing Word locations; use `humanReference`, `provision`, or
 `speculative-search-apply-v1`, `localized-change-summary-v1`, and
 `restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities. Header/footer
 `part` targeting, the `comment_resolve` operation and `delete-comments --comment-id` are advertised as
-`header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`.
+`header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`. The remaining advertised
+capabilities are `atomic-batch-results-on-package-failure`, `baseline-aware-validation`, `compact-mutation-results`,
+`cross-author-revision-slicing`, `document-scoped-list-revision-ids` and `format-text-occurrence-v1`.
 Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
@@ -371,6 +380,9 @@ See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 | `strictTargets` | `boolean` | `true` (CLI/facade) | Requires exact target descriptors (`exactText`, `paragraphId`, `index`, `occurrence`, `fingerprint`) and forbids ambiguous matching. Defaults to `false` in low-level runner for backwards compatibility. |
 | `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
 | `removeFormatting` | `boolean` | `false` | When `true` and the text is unchanged with no Markdown hints, strips existing bold/italic/underline/strikethrough formatting. |
+| `verifyRevisionFidelity` | `'enforce' \| 'warn' \| 'off'` | `'enforce'` | Post-apply Reject All check described under [Reject All verification](#reject-all-verification). CLI: `--revision-fidelity`; the agent profile rejects `off`. |
+| `listMarkers` | `'literal'` | unset | Per operation. 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 that operation. |
+| `strictListConversion` | `boolean` | `atomic` | Makes `UNSUPPORTED_LIST_CONVERSION` and `UNSUPPORTED_LIST_FORMAT_CHANGE` errors instead of warnings (capability `list-conversion-diagnostics-v1`). The CLI agent profile and `--atomic` set it; an operation's `listMarkers: 'literal'` wins. |
 | `sanitizeInput` | `boolean` | `false` | Opt-in removal of standalone leading assistant-preface lines. Literal dollar signs and `\n` sequences are always preserved. |
 
 Same-author revision merging refuses paragraphs containing comment anchors with
@@ -437,6 +449,58 @@ for it. For a complete `word/document.xml`, prefer
 `applyOperationToDocumentXml(...)` so replacement nodes and numbering artifacts
 are imported at the correct scope.
 
+### List operations (`list-format`)
+
+Text edits never create or restyle list structure. Typed markers such as `1.` or `A.` stay literal text, and a
+`list-change` that retypes markers keeps the old numbering (it warns `LIST_FORMAT_NOT_APPLIED`, or fails
+`UNSUPPORTED_LIST_FORMAT_CHANGE` under the strict policy, with a `list-format` request in `recovery.suggestedOperation`).
+Structure changes use the `list-format` operation. Every mode records each paragraph's previous `w:numPr` in a tracked
+`w:pPrChange`, so Reject All restores the original labels exactly and Accept All shows the new ones. The shared numbering
+definitions in `numbering.xml` are never edited in place: new definitions come from one allocator and are merged by one numbering
+merge, and an id that already exists with different content fails with `NUMBERING_ID_CONFLICT`. `paragraph-format`
+`properties.numbering` binds or removes a list on a paragraph the same way (tracked `w:pPrChange`). Unknown
+`paragraph-format.properties` keys are rejected with `INVALID_OPERATION`. The CLI advertises `list-format-v1` (contract version 9) for
+`convert-plain` and `list-format-change-v1` for `change-format` and `join`.
+
+```js
+const doc = openDocx(bytes);
+const result = await doc.applyOperations([
+  // Typed headers "A. Scope" .. "C. Fees" become a real A./B./C. list. Each marker is a tracked deletion, and body
+  // paragraphs in the range stay plain. A typed start value ("C.") is kept.
+  { type: 'list-format', target: { exactText: 'A. Scope' }, targetEnd: { exactText: 'C. Fees' },
+    list: { mode: 'convert-plain' } },
+  // Bullets become 1., 2., 3. A new definition copies the list's levels and indentation.
+  { type: 'list-format', target: { exactText: 'Photo identification' },
+    list: { mode: 'change-format', format: 'decimal' } },
+  // A later list continues an earlier one (1. 2. / 1. 2. becomes 1. 2. / 3. 4.).
+  { type: 'list-format', target: { exactText: 'Confidentiality' },
+    list: { mode: 'join', continueFrom: { exactText: 'Termination' } } }
+], { author: 'Editor' });
+```
+
+A changed-text header (`1. Old Terms` -> `1. New Terms`) takes two operations on the same paragraph in one batch: a
+`redline` of the text that keeps the typed marker exactly, and a `list-format` that converts the paragraph. The batch
+compiler allows this pair and always runs the redline first, whatever the batch order. The list-format then strips the
+unchanged marker. Accept All shows label `1.` with `New Terms`, and Reject All shows the literal `1. Old Terms`:
+
+```js
+await doc.applyOperations([
+  { type: 'redline', target: { exactText: '1. Old Terms' }, replacements: [{ find: 'Old', replace: 'New' }] },
+  { type: 'list-format', target: { exactText: '1. Old Terms' }, list: { mode: 'convert-plain' } }
+], { author: 'Editor' });
+```
+
+A redline in that pair that adds, removes or changes the marker is refused before anything is written, with
+`LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: 'marker-changed'`). So is a redline that spans paragraphs or leaves the text
+unchanged. To give a paragraph without a typed marker a label, use `strip: 'none'` with `format` (and `start`). A
+`change-format` or `join` with `scope: 'list'` (the default) also writes every other item of the list. In the same batch,
+each of those items accepts only a single-paragraph `redline`; any other write to them fails with
+`LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: 'list-rebind'`).
+Style-linked lists (heading numbering), mid-list splits, and markers inside hyperlinks or fields are refused with a
+recovery envelope. They are not approximated. Removing a list binding is `paragraph-format` with `properties.numbering:
+null`. A `list-format` `detach` mode is not available yet. See the
+[knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#operation-model-choose-by-output-shape) for every mode, field and refusal.
+
 ### Planning large mixed-content insertions
 
 For an attachment or schedule containing several kinds of content, use
@@ -509,7 +573,7 @@ an earlier block has already replaced.
 | `deleteCommentsByAuthorInOoxml(oxml, { author?, allAuthors? })` | Delete matching comment definitions and anchors present in the supplied OOXML payload. Real `.docx` packages require updating both `word/comments.xml` and `word/document.xml`. |
 | `generateTableOoxml(headers, rows, options)` | Generate a `w:tbl` from tabular data. |
 | `createDynamicNumberingIdState(numberingXml)` | Allocate numbering IDs without collisions. |
-| `ensureNumberingArtifactsInZip(zip, numberingXml, options)` | Add numbering artifacts to a `.docx` package. Replacement of existing numbering without `mergeNumberingXmlBySchemaOrder` is deprecated and will throw in the next major version. |
+| `ensureNumberingArtifactsInZip(zip, numberingXml, options)` | Add numbering artifacts to a `.docx` package. Always merges into an existing `word/numbering.xml` through the package's single numbering merge (`mergeNumberingParts`); an incoming id that already exists with different content fails with `NUMBERING_ID_CONFLICT`. The former `mergeNumberingXml` option is ignored. |
 | `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. |
 | `ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml)` | Add or replace modern Word comment-thread metadata in a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
@@ -556,8 +620,9 @@ identities. Independent edits therefore do not need to be manually sorted when
 an earlier structural rewrite changes later paragraph indexes or fingerprints.
 Targets that deliberately refer to uniquely created paragraph text are compiled
 into an internal capture dependency. True overlap is not guessed: incompatible
-writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS` or
-`REVISION_ORDER_CONFLICT`, and mutating capture fan-out without distinct
+writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS`,
+`REVISION_ORDER_CONFLICT` or `LIST_FORMAT_COMPOSITION_CONFLICT` (the one composed pair, a
+marker-preserving `redline` plus a `list-format`, runs redline first), and mutating capture fan-out without distinct
 selectors fails with `CAPTURE_FANOUT_CONFLICT`.
 
 Threaded replies use a comment operation with no body target:
@@ -667,6 +732,57 @@ chooses among multiple candidate paragraphs heuristically, it emits an
 guidance. Callers should pass `{ strictTargets: true }` and use strict descriptors
 (`paragraphId`, `index`, `occurrence`, or `fingerprint`) to prepare for v1.0.0.
 
+### Reject All verification
+
+A tracked edit only adds revisions, so rejecting every revision in the output
+must give back the source document. After each operation the library projects
+Word's Reject All and Accept All of the output (`core/word-revision-semantics.js`,
+validated against recorded desktop Word results) and checks these invariants:
+
+- `REJECT_PARAGRAPH_COUNT`, `REJECT_PARAGRAPH_TEXT` (including tabs and breaks),
+  `REJECT_PARAGRAPH_PROPS`, `REJECT_NUMBERING_REFS` (list membership `numId`/`ilvl`)
+  and `REJECT_WRAPPERS` (hyperlink, field and content-control membership):
+  Reject All of the output equals Reject All of the source (under accept-first
+  `existingRevisions` policies the target range is compared with the source's
+  accepted view). `REJECT_NUMBERING_REFS` also refuses a `numId` that the output
+  binds, or Reject All restores (including inside `w:pPrChange`), when the source
+  did not already use it and no `w:num` -> `w:abstractNum` -> `w:lvl` in the
+  available numbering defines it.
+- `ACCEPT_INTENT`: a tracked plain-text `redline` with complete `modified` (no
+  Markdown, list-marker or table syntax; a single paragraph or a `targetEnd`
+  range) is refused when Accept All of its target would not read as `modified`.
+- `ACCEPT_NEIGHBORS`: an untracked edit (`generateRedlines: false`) may not
+  change a paragraph outside its target in the Accept All or Reject All view.
+- `UNTRACKED_CREATED_REVISION`: an untracked edit may not create a tracked
+  revision that was not in the source (fragments of a sliced source revision
+  keep their element, author and date and are allowed).
+
+A localized replacement is also checked before it is committed: the target's
+accepted text must equal the compiled replacement text, otherwise the operation
+is refused with `PATCH_ROUNDTRIP_MISMATCH` rather than dropping content.
+
+By default a violation is refused with `REVISION_FIDELITY_VIOLATION`; the
+document is unchanged, `status` is `error`, and the receipt is `refused`. The
+error payload contains:
+
+- `violations[]`, each with `invariant` (`REJECT_PARAGRAPH_COUNT`,
+  `REJECT_PARAGRAPH_TEXT`, `REJECT_PARAGRAPH_PROPS`, `REJECT_NUMBERING_REFS`,
+  `REJECT_WRAPPERS`, `ACCEPT_INTENT`, `ACCEPT_NEIGHBORS` or
+  `UNTRACKED_CREATED_REVISION`), a plain-language `explanation`,
+  `expected`/`actual` excerpts, and `source.sourceParagraphIndex` (the 1-based
+  paragraph index from extraction) with a text excerpt;
+- `recovery.retryGuidance`, one retry instruction per reported invariant, for
+  example use `replacements` for a literal edit, keep breaks and hyperlink
+  boundaries, or move formatting and list changes into their own operation.
+
+Control it with the `verifyRevisionFidelity` option (`'enforce'` default,
+`'warn'`, `'off'`) or `--revision-fidelity enforce|warn|off` on the CLI. `warn`
+applies the edit and appends the same text to `warnings`. The `--profile agent`
+profile rejects `off`. A narrower retry that is also refused indicates an
+unsupported shape; report it rather than disabling verification. Recovery
+details are in the `REVISION_FIDELITY_VIOLATION` row of
+[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md).
+
 ### Mutation Receipts
 
 Both single-operation (`applyOperationToDocumentXml`) and batch
@@ -722,7 +838,7 @@ Different APIs return different OOXML shapes. Use this as a packaging safety che
   ID. Generated bullet and numbered paragraphs must reference a positive ID
   whose definition is merged into `word/numbering.xml`.
 - Do use `extractReplacementNodesFromOoxml(...)` when you are consuming `result.oxml` from paragraph/range/table APIs.
-- Do merge numbering/comments artifacts with `ensureNumberingArtifactsInZip(...)` and `ensureCommentsArtifactsInZip(...)` when those parts are present. Supply `mergeNumberingXmlBySchemaOrder` when numbering already exists.
+- Do merge numbering/comments artifacts with `ensureNumberingArtifactsInZip(...)` and `ensureCommentsArtifactsInZip(...)` when those parts are present. Numbering is always merged, never replaced; pass `numberingXml` or a shared `numberingIdState` to every call so generated ids cannot collide.
 - Don't write payloads that start with `<pkg:package` directly into `word/document.xml`.
 - Don't assume every `result.oxml` payload is a raw paragraph fragment.
 
@@ -744,7 +860,6 @@ import {
   applyRedlineToOxml,
   extractReplacementNodesFromOoxml,
   ensureNumberingArtifactsInZip,
-  mergeNumberingXmlBySchemaOrder,
   validateDocxPackage
 } from '@ansonlai/docx-redline-js';
 import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/standalone-runner';
@@ -807,9 +922,7 @@ const normalized = extractReplacementNodesFromOoxml(fragmentResult.oxml);
 // If sourceType === 'package', merge extracted content/artifacts instead of
 // writing the raw pkg:package payload into word/document.xml.
 if (normalized.numberingXml) {
-  await ensureNumberingArtifactsInZip(zip, normalized.numberingXml, {
-    mergeNumberingXml: mergeNumberingXmlBySchemaOrder
-  });
+  await ensureNumberingArtifactsInZip(zip, normalized.numberingXml);
 }
 
 await validateDocxPackage(zip);

package/core/current-properties.js

@@ -0,0 +1,136 @@
+/**
+ * Single accessor for CURRENT paragraph/run properties.
+ *
+ * Descendant lookups (`getElementsByTagNameNS`, `getWordDescendants`, ...) cross `w:pPrChange` and
+ * `w:rPrChange`, so a historical `numPr`/`pStyle`/`b` snapshot looks like a current value. Everything in
+ * this module reads direct children of `w:pPr` / `w:rPr` only. The `*PrChange` snapshot is reachable
+ * only through the explicit `getHistorical*` functions (reject simulation, restore).
+ *
+ * Depends only on `core/types.js`.
+ */
+
+import { NS_W } from './types.js';
+
+function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    const name = String(node.localName || node.nodeName || '').replace(/^.*:/, '');
+    if (localName != null && name !== localName) return false;
+    return !node.namespaceURI || node.namespaceURI === NS_W;
+}
+
+/** First direct child element with the given WordprocessingML local name. */
+export function getDirectWordChild(node, localName) {
+    if (!node) return null;
+    for (const child of Array.from(node.childNodes || [])) {
+        if (isWordElement(child, localName)) return child;
+    }
+    return null;
+}
+
+/** Direct child elements with the given local name (all direct Word elements when omitted). */
+export function getDirectWordChildren(node, localName) {
+    if (!node) return [];
+    return Array.from(node.childNodes || []).filter(child => isWordElement(child, localName));
+}
+
+/** Direct child of a properties element; never descends into `*PrChange` snapshots. */
+export function getCurrentChild(propsEl, localName) {
+    return getDirectWordChild(propsEl, localName);
+}
+
+function readVal(el) {
+    if (!el) return null;
+    const value = (typeof el.getAttributeNS === 'function' && el.getAttributeNS(NS_W, 'val'))
+        || el.getAttribute?.('w:val')
+        || el.getAttribute?.('val')
+        || null;
+    return value === '' ? null : value;
+}
+
+function readNumPr(propsEl) {
+    const numPr = getDirectWordChild(propsEl, 'numPr');
+    if (!numPr) return null;
+    return {
+        element: numPr,
+        numId: readVal(getDirectWordChild(numPr, 'numId')),
+        ilvl: readVal(getDirectWordChild(numPr, 'ilvl')),
+        numIdElement: getDirectWordChild(numPr, 'numId'),
+        ilvlElement: getDirectWordChild(numPr, 'ilvl')
+    };
+}
+
+function readParagraphProps(pPr) {
+    const pStyleEl = getDirectWordChild(pPr, 'pStyle');
+    const outlineEl = getDirectWordChild(pPr, 'outlineLvl');
+    return {
+        pPr: pPr || null,
+        numPr: readNumPr(pPr),
+        pStyle: readVal(pStyleEl),
+        pStyleElement: pStyleEl,
+        outlineLvl: readVal(outlineEl),
+        outlineLvlElement: outlineEl
+    };
+}
+
+/** Current paragraph properties: the paragraph's direct `w:pPr` only. */
+export function getCurrentParagraphProperties(p) {
+    return readParagraphProps(getDirectWordChild(p, 'pPr'));
+}
+
+/** Current run properties: the run's direct `w:rPr` (null when absent). */
+export function getCurrentRunProperties(r) {
+    return getDirectWordChild(r, 'rPr');
+}
+
+/** Paragraph-mark run properties (`w:pPr/w:rPr`), distinct from any run's `rPr`. */
+export function getParagraphMarkProperties(p) {
+    return getDirectWordChild(getDirectWordChild(p, 'pPr'), 'rPr');
+}
+
+/**
+ * Historical paragraph properties: the `w:pPrChange/w:pPr` snapshot. Explicit opt-in; shape matches
+ * `getCurrentParagraphProperties`. Returns null when the paragraph has no tracked property change.
+ */
+export function getHistoricalParagraphProperties(p) {
+    const change = getDirectWordChild(getDirectWordChild(p, 'pPr'), 'pPrChange');
+    const snapshot = getDirectWordChild(change, 'pPr');
+    return snapshot ? readParagraphProps(snapshot) : null;
+}
+
+/** Historical run properties: the `w:rPrChange/w:rPr` snapshot, or null. */
+export function getHistoricalRunProperties(r) {
+    const change = getDirectWordChild(getDirectWordChild(r, 'rPr'), 'rPrChange');
+    return getDirectWordChild(change, 'rPr');
+}
+
+/** All `w:p` elements at or under `root` (the paragraph itself when `root` is one). */
+function paragraphsUnder(root) {
+    if (!root || root.nodeType !== 1) return [];
+    const out = isWordElement(root, 'p') ? [root] : [];
+    if (typeof root.getElementsByTagNameNS === 'function') {
+        out.push(...Array.from(root.getElementsByTagNameNS(NS_W, 'p')));
+    }
+    return out;
+}
+
+/**
+ * Current `w:numId` elements (direct `pPr/numPr/numId`) of every paragraph at or under `root`.
+ * Excludes `pPrChange` snapshots, so Reject still restores the snapshot numId.
+ */
+export function getCurrentNumIdElements(root) {
+    const out = [];
+    for (const p of paragraphsUnder(root)) {
+        const el = getCurrentParagraphProperties(p).numPr?.numIdElement;
+        if (el) out.push(el);
+    }
+    return out;
+}
+
+/**
+ * Every `w:numId` element referenced anywhere under `root`, INCLUDING `pPrChange` snapshots. Explicitly
+ * historical-inclusive: used when a numbering part must define every id the content can ever reference.
+ */
+export function getAllReferencedNumIdElements(root) {
+    if (!root || typeof root.getElementsByTagNameNS !== 'function') return [];
+    return Array.from(root.getElementsByTagNameNS(NS_W, 'numId'));
+}