@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/index.d.ts

@@ -1,10 +1,61 @@
 export type OoxmlSourceType = 'package' | 'document' | 'fragment';
 export type RedlineStatus = 'ok' | 'no-op' | 'error';
-export type ExistingRevisionsPolicy = 'reject-input' | 'accept-all-first' | 'accept-all-first-keep-normalized';
+export type ExistingRevisionsPolicy = 'merge-same-author' | 'reject-input' | 'accept-all-first' | 'accept-all-first-keep-normalized';
+export type RevisionView = 'accepted' | 'rejected';
+
+export interface RevisionTextSegment {
+  text: string;
+  kind: 'baseline' | 'insertion' | 'deletion' | 'move_from' | 'move_to';
+  author?: string;
+  revisionId?: string;
+  acceptedStart: number | null;
+  rejectedStart: number | null;
+}
+
+import type { InsertionAffinity } from './services/standalone-operation-runner.js';
+
+export type {
+  BatchOperationItemResult,
+  CommentDocumentOperation,
+  CommentReplyDocumentOperation,
+  DeleteDocumentOperation,
+  DocumentOperation,
+  DocumentOperationBatchResult,
+  HighlightDocumentOperation,
+  InsertionAffinity,
+  OperationConflict,
+  OperationDependencyPlan,
+  OperationPreflightItemResult,
+  OperationPreflightResult,
+  ParagraphTargetDescriptor,
+  RedlineDocumentOperation,
+  ResolvedCommentAnchor,
+  ResolvedDocumentTarget,
+  StandaloneRunnerOptions
+} from './services/standalone-operation-runner.js';
 
 export interface RedlineError {
-  code: 'PARSE_ERROR' | 'TARGET_NOT_FOUND' | 'EXISTING_REVISIONS' | 'DIFF_TOKEN_LIMIT' | string;
+  code:
+    | 'PARSE_ERROR'
+    | 'TARGET_NOT_FOUND'
+    | 'EXISTING_REVISIONS'
+    | 'DIFF_TOKEN_LIMIT'
+    | 'UNSUPPORTED_REVISION_VIEW_MUTATION'
+    | 'UNSUPPORTED_INSERTION_AFFINITY'
+    | 'UNSAFE_PARAGRAPH_BOUNDARY'
+    | 'TARGET_INDEX_MISMATCH'
+    | 'REVISION_MISMATCH'
+    | 'REVISION_TOKEN_SCOPE_MISMATCH'
+    | 'INVALID_REVISION_TOKEN'
+    | 'DUPLICATE_CAPTURE_KEY'
+    | 'CAPTURE_NOT_FOUND'
+    | 'CAPTURE_DEPENDENCY_CYCLE'
+    | 'AMBIGUOUS_CAPTURE_SELECTION'
+    | 'CAPTURE_STALE'
+    | string;
   message: string;
+  commentIds?: string[];
+  comments?: Array<{ id: string; author: string; text: string }>;
 }
 
 export interface RedlineOptions {
@@ -14,6 +65,9 @@ export interface RedlineOptions {
   existingRevisions?: ExistingRevisionsPolicy;
   removeFormatting?: boolean;
   sanitizeInput?: boolean;
+  structuredContent?: boolean;
+  pairReplacements?: boolean;
+  insertionAffinity?: InsertionAffinity;
   [key: string]: unknown;
 }
 
@@ -78,6 +132,28 @@ export interface IngestionTextResult {
   warnings?: string[];
 }
 
+export interface ParagraphTargetCandidate {
+  paragraph: Element;
+  index: number;
+  inTable: boolean;
+  paragraphId: string | null;
+  fingerprint: string | null;
+  text: string;
+}
+
+export interface ParagraphTargetResolution {
+  paragraph: Element;
+  resolvedBy:
+    | 'ref'
+    | 'paragraph_id'
+    | 'occurrence'
+    | 'fingerprint'
+    | 'strict_text'
+    | 'fuzzy_text'
+    | 'strict_text_after_ref_drift'
+    | 'fuzzy_text_after_ref_drift';
+}
+
 export interface XmlProvider {
   DOMParser: typeof DOMParser;
   XMLSerializer: typeof XMLSerializer;
@@ -94,6 +170,7 @@ export interface DocumentOperationResult {
   hasChanges: boolean;
   numberingXml?: string | null;
   commentsXml?: string | null;
+  commentsExtendedXml?: string | null;
   warnings?: string[];
   status?: RedlineStatus;
   error?: RedlineError;
@@ -128,10 +205,86 @@ export function reconcileMarkdownTableOoxml(
   options?: RedlineOptions
 ): Promise<TableReconciliationResult>;
 
+export interface StructuredContentIssue {
+  severity: 'error' | 'warning';
+  code: string;
+  line: number;
+  message: string;
+}
+export interface StructuredContentBlock {
+  type: 'heading' | 'paragraph' | 'list' | 'table';
+  markdown: string;
+  text?: string;
+  level?: number;
+  items?: number;
+  columns?: number;
+  rows?: number;
+  hasHeader?: boolean;
+}
+export interface StructuredContentAnalysis {
+  valid: boolean;
+  normalizedMarkdown: string;
+  blocks: StructuredContentBlock[];
+  issues: StructuredContentIssue[];
+  counts: Record<'heading' | 'paragraph' | 'list' | 'table', number>;
+  requiresStructuredContent: boolean;
+}
+export function analyzeStructuredContent(markdown: string): StructuredContentAnalysis;
+export function planStructuredReplacement(
+  target: string | import('./services/standalone-operation-runner.js').ParagraphTargetDescriptor,
+  markdown: string,
+  options?: { author?: string; generateRedlines?: boolean; existingRevisions?: ExistingRevisionsPolicy }
+): StructuredContentAnalysis & { operation: import('./services/standalone-operation-runner.js').RedlineDocumentOperation | null };
+
 export function ingestWordOoxmlToPlainText(oxml: string): string;
 export function ingestWordOoxmlToMarkdown(oxml: string): string;
 export function ingestWordOoxmlToPlainTextResult(oxml: unknown): IngestionTextResult;
 export function ingestWordOoxmlToMarkdownResult(oxml: unknown): IngestionTextResult;
+export function extractCanonicalParagraphText(paragraph: Element | null | undefined, options?: { revisionView?: 'accepted' | 'rejected' | 'current' }): string;
+export function extractParagraphRevisionSegments(paragraph: Element | null | undefined, options?: { mergeRuns?: boolean; [key: string]: unknown }): RevisionTextSegment[];
+export function readCanonicalRunText(run: Element, options?: { revisionView?: 'accepted' | 'rejected' | 'current'; boundary?: Element | null }): string;
+export function isNodeVisibleInRevisionView(node: Node, boundary?: Node | null, revisionView?: 'accepted' | 'rejected' | 'current'): boolean;
+export function containsTrackedChanges(xmlDoc: Document | Element | null | undefined): boolean;
+export function getTrackedChangeAuthors(xmlDocOrElement: Document | Element | null | undefined): string[];
+
+export interface InspectedParagraph {
+  index: number; ref: string; paragraphId: string | null; fingerprint: string | null;
+  text: string; exactText: string; excerpt: string; inTable: boolean;
+  humanReference: string; styleId: string | null;
+  table: { tableIndex: number; rowIndex: number; cellIndex: number } | null;
+  structuralReferences: Array<{ type: 'footnote' | 'endnote' | 'comment'; id: string | null }>;
+  headingLevel: number | null; nearestHeading: { level: number; text: string } | null;
+  list: { numId: string; level: number; label: string | null; format: string | null } | null;
+  hasRevisions: boolean; revisionAuthors: string[]; commentIds: string[];
+  segments: RevisionTextSegment[];
+}
+export interface RevisionToken {
+  algorithm: 'sha256';
+  version: 1;
+  scope: 'document-parts' | 'package';
+  value: string;
+  coveredParts?: string[];
+}
+
+export interface InspectedComment { id: string; author: string | null; date: string | null; text: string; paraId?: string | null; parentParaId?: string; parentCommentId?: string | null; done?: boolean; paragraphIndex?: number; targetRef?: string; anchoredText?: string; }
+export interface DocumentInspectionOptions { revisionView?: 'accepted' | 'rejected' | 'current'; excerptLength?: number; revisedOnly?: boolean; inTable?: boolean; skipEmpty?: boolean; search?: string; indexes?: number[]; range?: { start: number; end: number } | [number, number]; digestFn?: (bytes: Uint8Array) => string; }
+export interface DocumentInspectionResult {
+  status: 'ok' | 'error'; paragraphs: InspectedParagraph[]; comments: InspectedComment[];
+  revisionAuthors?: string[]; commentAuthors?: string[]; counts?: { paragraphs: number; comments: number; revisedParagraphs: number };
+  revisionToken?: RevisionToken | null;
+  coveredParts?: string[];
+  warnings: string[]; error?: RedlineError;
+}
+export function inspectDocumentParts(parts: { documentXml: string; commentsXml?: string | null; commentsExtendedXml?: string | null; numberingXml?: string | null; stylesXml?: string | null; parts?: Map<string, unknown>; additionalParts?: Record<string, unknown> }, options?: DocumentInspectionOptions): DocumentInspectionResult;
+export function buildRevisionTokenFraming(options: { scope: string; entries?: unknown }): { framing: Uint8Array; scope: string; version: number; coveredParts: string[] };
+export function computeRevisionToken(options: { scope: string; entries?: unknown; digestFn?: (bytes: Uint8Array) => Promise<string> }): Promise<RevisionToken>;
+export function computeRevisionTokenSync(options: { scope: string; entries?: unknown; digestFn: (bytes: Uint8Array) => string }): RevisionToken;
+export function computeDocumentPartsRevisionToken(parts: unknown, options?: { digestFn?: (bytes: Uint8Array) => Promise<string> }): Promise<RevisionToken>;
+export function validateRevisionToken(token: unknown): { valid: boolean; error?: { code: string; message: string } };
+export function areRevisionTokensEqual(a: string, b: string): boolean;
+export function normalizeOpcEntryName(name: string): string;
+export function extractDocumentPartsEntries(parts: unknown): Array<{ name: string; payload: unknown }>;
+
 export function ingestOoxml(oxml: string): unknown;
 export function preprocessMarkdown(text: string): { cleanText: string; formatHints: unknown[] };
 export function serializeToOoxml(runModel: unknown[], pPrXml?: string | null, formatHints?: unknown[], options?: Record<string, unknown>): string;
@@ -139,6 +292,7 @@ export function wrapInDocumentFragment(rawOoxml: string, options?: Record<string
 
 export function injectCommentsIntoOoxml(oxml: string, comments: unknown[], options?: Record<string, unknown>): unknown;
 export function injectCommentsIntoPackage(packageXml: string, comments: unknown[], options?: Record<string, unknown>): unknown;
+export function applyCommentReplyToParts(options: { commentsXml: string; commentsExtendedXml?: string | null; parentCommentId: string | number; commentId: string | number; commentContent: string; author: string; date?: string }): { status: 'ok' | 'error'; hasChanges?: boolean; commentsXml?: string; commentsExtendedXml?: string; commentsXmlMode?: 'replace'; commentsExtendedXmlMode?: 'replace'; parentCommentId?: string; paraId?: string; parentParaId?: string; error?: RedlineError };
 export function acceptTrackedChangesInOoxml(oxml: string, options?: RevisionFilterOptions): AcceptTrackedChangesResult;
 export function rejectTrackedChangesInOoxml(oxml: string, options?: RevisionFilterOptions): RejectTrackedChangesResult;
 export function deleteCommentsByAuthorInOoxml(oxml: string, options?: RevisionFilterOptions): DeleteCommentsResult;
@@ -174,6 +328,7 @@ export function extractReplacementNodesFromOoxml(oxml: string): unknown;
 export function validateDocxPackage(zip: unknown): Promise<unknown> | unknown;
 export function ensureNumberingArtifactsInZip(zip: unknown, numberingXml: string): Promise<unknown> | unknown;
 export function ensureCommentsArtifactsInZip(zip: unknown, commentsXml: string): Promise<unknown> | unknown;
+export function ensureCommentsExtendedArtifactsInZip(zip: unknown, commentsExtendedXml: string): Promise<unknown> | unknown;
 export function createDynamicNumberingIdState(numberingXml?: string): unknown;
 
 export function parseOoxml(ooxml: string): Document | null;
@@ -231,6 +386,8 @@ export function enforceListBindingOnParagraphNodes(nodes: Node[], options?: Reco
 export function stripSingleLineListMarkerPrefix(text: string): string;
 
 export function getParagraphText(paragraph: Element | null | undefined): string;
+export function getParagraphId(paragraph: Element | null | undefined): string | null;
+export function createParagraphFingerprint(paragraph: Element | null | undefined): string | null;
 export function getDocumentParagraphNodes(xmlDoc: Document | Element | null | undefined): Element[];
 export function normalizeWhitespaceForTargeting(text: string): string;
 export function isMarkdownTableText(text: string): boolean;
@@ -241,10 +398,23 @@ export function findContainingWordElement(node: Node | null, localName: string):
 export function findParagraphByReference(xmlDoc: Document | Element, reference: unknown): Element | null;
 export function findParagraphByStrictText(xmlDoc: Document | Element, text: string): Element | null;
 export function findParagraphByBestTextMatch(xmlDoc: Document | Element, text: string): Element | null;
-export function resolveTargetParagraph(xmlDoc: Document | Element, options?: Record<string, unknown>): Element | null;
-export function buildTargetReferenceSnapshot(paragraph: Element, options?: Record<string, unknown>): Record<string, unknown>;
-export function resolveTargetParagraphWithSnapshot(xmlDoc: Document | Element, snapshot: unknown): Element | null;
-export function resolveParagraphRangeByRefs(xmlDoc: Document | Element, references: unknown[]): Element[];
+export function findStrictTargetCandidates(xmlDoc: Document | Element, text: string): ParagraphTargetCandidate[];
+export function resolveTargetParagraph(xmlDoc: Document | Element, options?: Record<string, unknown>): ParagraphTargetResolution;
+export function buildTargetReferenceSnapshot(xmlDoc: Document | Element): Map<number, {
+  text: string;
+  normalizedText: string;
+  inTable: boolean;
+}>;
+export function resolveTargetParagraphWithSnapshot(
+  xmlDoc: Document | Element,
+  options?: Record<string, unknown>
+): ParagraphTargetResolution;
+export function resolveParagraphRangeByRefs(
+  xmlDoc: Document | Element,
+  startRef: string | number | null,
+  endRef: string | number | null,
+  options?: Record<string, unknown>
+): Element[] | null;
 export function extractParagraphIdFromOoxml(oxml: string): string | null;
 
 export function getParagraphListInfo(paragraph: Element): Record<string, unknown> | null;
@@ -262,3 +432,61 @@ export function insertBodyElementBeforeSectPr(body: Element, element: Element):
 export function normalizeBodySectionOrderStandalone(documentXml: string): string;
 export function sanitizeNestedParagraphsInTables(documentXml: string): string;
 export function getPackagePartName(part: unknown): string | null;
+
+export interface MutationReceiptRevisionItem {
+  id: string;
+  kind: 'ins' | 'del' | 'move_from' | 'move_to' | 'rPrChange' | 'pPrChange' | 'structural';
+  partName: string;
+}
+
+export interface MutationReceipt {
+  operationIndex: number;
+  operationId?: string;
+  attemptedDisposition: 'applied' | 'no_change' | 'refused' | 'not_attempted';
+  finalDisposition: 'applied' | 'no_change' | 'refused' | 'rolled_back' | 'not_attempted';
+  committed: boolean;
+  authorUsed?: string;
+  revisionItems: MutationReceiptRevisionItem[];
+  commentIds: string[];
+  numberingIds: string[];
+  relationshipIds: string[];
+  affectedTargets: unknown[];
+  warnings: string[];
+}
+
+export class ReceiptCollector {
+  constructor();
+  beginOperation(operationIndex: number, operationId?: string | null, authorUsed?: string | null): void;
+  recordRevision(id: string | number, kind?: string, partName?: string): void;
+  recordComment(id: string | number, partName?: string): void;
+  recordNumbering(id: string | number, partName?: string): void;
+  recordRelationship(id: string | number, partName?: string): void;
+  recordAffectedTarget(target: unknown): void;
+  recordWarning(warning: unknown): void;
+  commitOperation(disposition?: string): MutationReceipt | null;
+  abortOperation(disposition?: string): MutationReceipt | null;
+  createSavepoint(): unknown;
+  restoreSavepoint(savepoint: unknown): void;
+  clear(): void;
+  markRolledBack(): void;
+  getReceipts(): MutationReceipt[];
+  getCurrentReceipt(): MutationReceipt | null;
+}
+
+export function createEmptyReceipt(
+  operationIndex: number,
+  operationId?: string | null,
+  authorUsed?: string | null,
+  disposition?: 'applied' | 'no_change' | 'refused' | 'not_attempted'
+): MutationReceipt;
+
+export function reconcileReceiptsAgainstOutput(
+  parts: {
+    documentXml: string;
+    commentsXml?: string | null;
+    numberingXml?: string | null;
+    numberingXmlParts?: string[];
+    relationshipsXml?: string | null;
+  },
+  receipts: MutationReceipt[]
+): { valid: boolean; error?: { code: string; message: string } };

package/index.js

@@ -21,8 +21,9 @@ import {
     executeSingleLineListStructuralFallback
 } from './orchestration/list-structural-fallback.js';
 import { withOoxmlSourceType } from './core/word-xml.js';
-export { containsTrackedChanges } from './core/word-xml.js';
+export { containsTrackedChanges, getTrackedChangeAuthors } from './core/word-xml.js';
 export { validateRedlineOoxml } from './core/redline-validation.js';
+export { analyzeStructuredContent, planStructuredReplacement } from './pipeline/structured-content.js';
 
 /**
  * Standalone-safe redline wrapper.
@@ -237,6 +238,18 @@ export {
     ingestWordOoxmlToPlainTextResult,
     ingestWordOoxmlToMarkdownResult
 } from './pipeline/ingestion-export.js';
+export { extractCanonicalParagraphText, readCanonicalRunText, isNodeVisibleInRevisionView, extractParagraphRevisionSegments } from './core/paragraph-text.js';
+export { inspectDocumentParts } from './services/document-inspection.js';
+export {
+    buildRevisionTokenFraming,
+    computeRevisionToken,
+    computeRevisionTokenSync,
+    computeDocumentPartsRevisionToken,
+    validateRevisionToken,
+    areRevisionTokensEqual,
+    normalizeOpcEntryName,
+    extractDocumentPartsEntries
+} from './services/revision-token.js';
 export { preprocessMarkdown } from './pipeline/markdown-processor.js';
 export { serializeToOoxml, wrapInDocumentFragment } from './pipeline/serialization.js';
 
@@ -247,6 +260,7 @@ export {
     buildCommentElement,
     buildCommentsPartXml
 } from './services/comment-engine.js';
+export { applyCommentReplyToParts } from './services/comment-replies.js';
 export {
     acceptTrackedChangesInOoxml,
     rejectTrackedChangesInOoxml,
@@ -272,6 +286,7 @@ export {
     extractReplacementNodesFromOoxml,
     ensureNumberingArtifactsInZip,
     ensureCommentsArtifactsInZip,
+    ensureCommentsExtendedArtifactsInZip,
     validateDocxPackage
 } from './services/standalone-docx-plumbing.js';
 export { buildReconciliationPlan, RoutePlanKind, normalizeContentEscapesForRouting } from './orchestration/route-plan.js';
@@ -293,6 +308,8 @@ export { extractParagraphIdFromOoxml } from './core/ooxml-identifiers.js';
 export {
     WORD_MAIN_NS,
     getParagraphText,
+    getParagraphId,
+    createParagraphFingerprint,
     getDocumentParagraphNodes,
     normalizeWhitespaceForTargeting,
     isMarkdownTableText,
@@ -303,6 +320,7 @@ export {
     findParagraphByReference,
     findParagraphByStrictText,
     findParagraphByBestTextMatch,
+    findStrictTargetCandidates,
     resolveTargetParagraph,
     buildTargetReferenceSnapshot,
     resolveTargetParagraphWithSnapshot
@@ -315,3 +333,8 @@ export {
     planListInsertionOnlyEdit,
     stripRedundantLeadingListMarkers
 } from './core/list-targeting.js';
+export {
+    ReceiptCollector,
+    createEmptyReceipt,
+    reconcileReceiptsAgainstOutput
+} from './services/receipt-collector.js';