@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/src/compare/diff-engine.ts

@@ -0,0 +1,530 @@
+import {
+  createCanonicalDocumentSignature,
+  projectCanonicalDocument,
+  type BlockNode,
+  type CanonicalDocument,
+  type HyperlinkNode,
+  type InlineNode,
+  type ParagraphNode,
+  type TextNode,
+} from "../model/canonical-document.ts";
+import type { DocumentVersionSnapshot } from "./snapshot.ts";
+
+export interface CompareVersionRef {
+  versionId: string;
+  name: string;
+  signature: string;
+}
+
+export type CompareChangeKind =
+  | "paragraph-insertion"
+  | "paragraph-deletion"
+  | "structural-insertion"
+  | "structural-deletion";
+
+export interface CompareChange {
+  changeId: string;
+  kind: CompareChangeKind;
+  tracked: boolean;
+  blockType: BlockNode["type"];
+  beforeText?: string;
+  afterText?: string;
+  targetIndex: number;
+}
+
+export interface VersionCompareResult {
+  compareVersion: "version-compare-result/1";
+  comparedAt: string;
+  base: CompareVersionRef;
+  target: CompareVersionRef;
+  changes: CompareChange[];
+  comparedDocument: CanonicalDocument;
+}
+
+export interface CompareDocumentVersionsOptions {
+  comparedAt?: string;
+  authorId?: string;
+}
+
+interface BuildEntry {
+  block: BlockNode;
+  trackChange?: "insertion" | "deletion";
+  tracked: boolean;
+  blockType: BlockNode["type"];
+  beforeText?: string;
+  afterText?: string;
+}
+
+interface PendingRevision {
+  changeId: string;
+  kind: "insertion" | "deletion";
+  paragraphIndex: number;
+}
+
+interface LcsMatch {
+  baseIndex: number;
+  targetIndex: number;
+}
+
+export function compareDocumentSnapshots(
+  base: DocumentVersionSnapshot,
+  target: DocumentVersionSnapshot,
+  options: CompareDocumentVersionsOptions = {},
+): VersionCompareResult {
+  const comparedAt = options.comparedAt ?? target.createdAt;
+  const authorId = options.authorId ?? "Version Compare";
+  const baseDocument = base.canonicalDocument;
+  const targetDocument = target.canonicalDocument;
+  const baseBlocks = baseDocument.content.children;
+  const targetBlocks = targetDocument.content.children;
+  const matches = computeLcs(
+    baseBlocks.map(getComparableBlockKey),
+    targetBlocks.map(getComparableBlockKey),
+  );
+
+  const buildEntries: BuildEntry[] = [];
+  const changes: CompareChange[] = [];
+  let nextBaseIndex = 0;
+  let nextTargetIndex = 0;
+  let nextChangeNumber = 1;
+
+  for (const match of [...matches, { baseIndex: baseBlocks.length, targetIndex: targetBlocks.length }]) {
+    while (nextBaseIndex < match.baseIndex || nextTargetIndex < match.targetIndex) {
+      const deleteBlock = nextBaseIndex < match.baseIndex ? baseBlocks[nextBaseIndex] : undefined;
+      const insertBlock = nextTargetIndex < match.targetIndex ? targetBlocks[nextTargetIndex] : undefined;
+
+      if (deleteBlock && insertBlock) {
+        const deletionId = `change-${nextChangeNumber}`;
+        nextChangeNumber += 1;
+        addTrackedOrStructuralEntry(
+          buildEntries,
+          changes,
+          deletionId,
+          deleteBlock,
+          "deletion",
+          nextTargetIndex,
+        );
+
+        const insertionId = `change-${nextChangeNumber}`;
+        nextChangeNumber += 1;
+        addTrackedOrStructuralEntry(
+          buildEntries,
+          changes,
+          insertionId,
+          insertBlock,
+          "insertion",
+          nextTargetIndex,
+        );
+        nextBaseIndex += 1;
+        nextTargetIndex += 1;
+        continue;
+      }
+
+      if (deleteBlock) {
+        const changeId = `change-${nextChangeNumber}`;
+        nextChangeNumber += 1;
+        addTrackedOrStructuralEntry(
+          buildEntries,
+          changes,
+          changeId,
+          deleteBlock,
+          "deletion",
+          nextTargetIndex,
+        );
+        nextBaseIndex += 1;
+        continue;
+      }
+
+      if (insertBlock) {
+        const changeId = `change-${nextChangeNumber}`;
+        nextChangeNumber += 1;
+        addTrackedOrStructuralEntry(
+          buildEntries,
+          changes,
+          changeId,
+          insertBlock,
+          "insertion",
+          nextTargetIndex,
+        );
+        nextTargetIndex += 1;
+      }
+    }
+
+    if (match.baseIndex < baseBlocks.length && match.targetIndex < targetBlocks.length) {
+      buildEntries.push({
+        block: cloneBlock(targetBlocks[match.targetIndex]),
+        tracked: false,
+        blockType: targetBlocks[match.targetIndex].type,
+        beforeText: getBlockDisplayText(baseBlocks[match.baseIndex]),
+        afterText: getBlockDisplayText(targetBlocks[match.targetIndex]),
+      });
+      nextBaseIndex = match.baseIndex + 1;
+      nextTargetIndex = match.targetIndex + 1;
+    }
+  }
+
+  const built = buildComparedDocument(baseDocument, targetDocument, buildEntries, comparedAt, authorId);
+  return {
+    compareVersion: "version-compare-result/1",
+    comparedAt,
+    base: {
+      versionId: base.versionId,
+      name: base.name,
+      signature: base.documentSignature,
+    },
+    target: {
+      versionId: target.versionId,
+      name: target.name,
+      signature: target.documentSignature,
+    },
+    changes,
+    comparedDocument: built,
+  };
+}
+
+function addTrackedOrStructuralEntry(
+  buildEntries: BuildEntry[],
+  changes: CompareChange[],
+  changeId: string,
+  block: BlockNode,
+  direction: "insertion" | "deletion",
+  targetIndex: number,
+): void {
+  const tracked = block.type === "paragraph";
+  const cloned = cloneBlock(block);
+  const text = getBlockDisplayText(block);
+
+  buildEntries.push({
+    block: cloned,
+    ...(tracked ? { trackChange: direction } : {}),
+    tracked,
+    blockType: cloned.type,
+    ...(direction === "deletion" ? { beforeText: text } : { afterText: text }),
+  });
+
+  changes.push({
+    changeId,
+    kind:
+      block.type === "paragraph"
+        ? direction === "insertion"
+          ? "paragraph-insertion"
+          : "paragraph-deletion"
+        : direction === "insertion"
+          ? "structural-insertion"
+          : "structural-deletion",
+    tracked,
+    blockType: cloned.type,
+    ...(direction === "deletion" ? { beforeText: text } : { afterText: text }),
+    targetIndex,
+  });
+}
+
+function buildComparedDocument(
+  base: CanonicalDocument,
+  target: CanonicalDocument,
+  entries: readonly BuildEntry[],
+  comparedAt: string,
+  authorId: string,
+): CanonicalDocument {
+  const contentChildren: BlockNode[] = [];
+  const pendingRevisions: PendingRevision[] = [];
+  const diagnosticsWarnings = [...target.diagnostics.warnings];
+  let paragraphIndex = 0;
+  let warningNumber = 1;
+
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (!entry) {
+      continue;
+    }
+
+    contentChildren.push(entry.block);
+    if (entry.block.type === "paragraph") {
+      if (entry.trackChange) {
+        pendingRevisions.push({
+          changeId: `change-${pendingRevisions.length + 1}`,
+          kind: entry.trackChange,
+          paragraphIndex,
+        });
+      }
+      paragraphIndex += 1;
+      continue;
+    }
+
+    if (!entry.tracked) {
+      diagnosticsWarnings.push({
+        diagnosticId: `diagnostic:compare-structural-${warningNumber}`,
+        warningId: `warning:compare-structural-${warningNumber}`,
+        source: "review",
+        message: `Version compare preserved a ${entry.blockType} ${entry.beforeText ? "deletion" : "insertion"} without a Word revision wrapper.`,
+      });
+      warningNumber += 1;
+    }
+  }
+
+  const revisions = createParagraphRevisionRecords(
+    contentChildren,
+    pendingRevisions,
+    comparedAt,
+    authorId,
+  );
+
+  return {
+    ...projectCanonicalDocument(target),
+    updatedAt: comparedAt,
+    styles: mergeStyleCatalogs(base.styles, target.styles),
+    numbering: mergeRecordCatalog(base.numbering, target.numbering),
+    media: mergeRecordCatalog(base.media, target.media),
+    content: {
+      type: "doc",
+      children: contentChildren,
+    },
+    review: {
+      comments: {},
+      revisions,
+    },
+    preservation: mergePreservationStores(base.preservation, target.preservation),
+    diagnostics: {
+      warnings: diagnosticsWarnings,
+      errors: [...target.diagnostics.errors],
+    },
+    ...(target.subParts ?? base.subParts ? { subParts: projectValue(target.subParts ?? base.subParts) } : {}),
+  };
+}
+
+function createParagraphRevisionRecords(
+  children: readonly BlockNode[],
+  pendingRevisions: readonly PendingRevision[],
+  createdAt: string,
+  authorId: string,
+): CanonicalDocument["review"]["revisions"] {
+  const positionByParagraphIndex = new Map<number, number>();
+  let cursor = 0;
+  let paragraphIndex = 0;
+  let previousWasParagraph = false;
+
+  for (const block of children) {
+    if (block.type === "paragraph") {
+      if (previousWasParagraph) {
+        cursor += 1;
+      }
+      cursor += getParagraphLength(block);
+      positionByParagraphIndex.set(paragraphIndex, cursor);
+      paragraphIndex += 1;
+      previousWasParagraph = true;
+      continue;
+    }
+
+    cursor += 1;
+    previousWasParagraph = false;
+  }
+
+  return Object.fromEntries(
+    pendingRevisions
+      .map((revision, index) => {
+        const position = positionByParagraphIndex.get(revision.paragraphIndex);
+        if (position === undefined) {
+          return undefined;
+        }
+
+        const changeId = `change-${index + 1}`;
+        return [
+          changeId,
+          {
+            changeId,
+            kind: revision.kind,
+            anchor: {
+              kind: "range" as const,
+              range: { from: position, to: position },
+              assoc: { start: -1 as const, end: 1 as const },
+            },
+            authorId,
+            createdAt,
+            status: "open" as const,
+            warningIds: [],
+            metadata: {
+              source: "runtime" as const,
+              importedRevisionForm:
+                revision.kind === "insertion" ? "paragraph-insertion" : "paragraph-deletion",
+            },
+          },
+        ] as const;
+      })
+      .filter((entry): entry is readonly [string, CanonicalDocument["review"]["revisions"][string]] => Boolean(entry)),
+  );
+}
+
+function getComparableBlockKey(block: BlockNode): string {
+  if (block.type === "paragraph") {
+    return `paragraph:${createCanonicalDocumentSignature({
+      ...block,
+      children: normalizeInlineChildren(block.children),
+    })}`;
+  }
+
+  return `${block.type}:${createCanonicalDocumentSignature(block)}`;
+}
+
+function normalizeInlineChildren(children: readonly InlineNode[]): InlineNode[] {
+  return children.map((child) => {
+    if (child.type === "hyperlink") {
+      return {
+        ...child,
+        children: normalizeInlineChildren(child.children) as HyperlinkNode["children"],
+      };
+    }
+    if (child.type === "field") {
+      return {
+        ...child,
+        children: normalizeInlineChildren(child.children),
+      };
+    }
+    return projectValue(child);
+  });
+}
+
+function computeLcs(baseKeys: readonly string[], targetKeys: readonly string[]): LcsMatch[] {
+  const widths = targetKeys.length + 1;
+  const matrix = Array.from({ length: baseKeys.length + 1 }, () =>
+    Array.from({ length: widths }, () => 0),
+  );
+
+  for (let baseIndex = baseKeys.length - 1; baseIndex >= 0; baseIndex -= 1) {
+    for (let targetIndex = targetKeys.length - 1; targetIndex >= 0; targetIndex -= 1) {
+      matrix[baseIndex][targetIndex] =
+        baseKeys[baseIndex] === targetKeys[targetIndex]
+          ? matrix[baseIndex + 1][targetIndex + 1] + 1
+          : Math.max(matrix[baseIndex + 1][targetIndex], matrix[baseIndex][targetIndex + 1]);
+    }
+  }
+
+  const matches: LcsMatch[] = [];
+  let baseIndex = 0;
+  let targetIndex = 0;
+  while (baseIndex < baseKeys.length && targetIndex < targetKeys.length) {
+    if (baseKeys[baseIndex] === targetKeys[targetIndex]) {
+      matches.push({ baseIndex, targetIndex });
+      baseIndex += 1;
+      targetIndex += 1;
+      continue;
+    }
+
+    if (matrix[baseIndex + 1][targetIndex] >= matrix[baseIndex][targetIndex + 1]) {
+      baseIndex += 1;
+    } else {
+      targetIndex += 1;
+    }
+  }
+
+  return matches;
+}
+
+function getParagraphLength(paragraph: ParagraphNode): number {
+  return paragraph.children.reduce((length, child) => length + getInlineLength(child), 0);
+}
+
+function getInlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+      return node.children.reduce((length, child) => length + getInlineLength(child), 0);
+    case "field":
+      return node.children.reduce((length, child) => length + getInlineLength(child), 0);
+    case "tab":
+    case "hard_break":
+    case "column_break":
+    case "image":
+    case "opaque_inline":
+    case "footnote_ref":
+    case "bookmark_start":
+    case "bookmark_end":
+      return 1;
+  }
+}
+
+function getBlockDisplayText(block: BlockNode): string {
+  switch (block.type) {
+    case "paragraph":
+      return block.children.map(getInlineDisplayText).join("");
+    case "table":
+      return "[Table]";
+    case "sdt":
+      return "[Structured content]";
+    case "custom_xml":
+      return "[Custom XML block]";
+    case "alt_chunk":
+      return "[Alt chunk]";
+    case "section_break":
+      return "[Section break]";
+    case "opaque_block":
+      return "[Preserved block]";
+  }
+}
+
+function getInlineDisplayText(node: InlineNode): string {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "tab":
+      return "\t";
+    case "hard_break":
+    case "column_break":
+      return "\n";
+    case "hyperlink":
+      return node.children.map(getInlineDisplayText).join("");
+    case "field":
+      return node.children.map(getInlineDisplayText).join("");
+    case "image":
+      return node.altText ?? "[Image]";
+    case "opaque_inline":
+      return "[Preserved]";
+    case "footnote_ref":
+      return "[Footnote]";
+    case "bookmark_start":
+    case "bookmark_end":
+      return "";
+  }
+}
+
+function mergeStyleCatalogs(
+  base: CanonicalDocument["styles"],
+  target: CanonicalDocument["styles"],
+): CanonicalDocument["styles"] {
+  return {
+    paragraphs: { ...base.paragraphs, ...target.paragraphs },
+    characters: { ...base.characters, ...target.characters },
+    tables: { ...base.tables, ...target.tables },
+    ...((base.latentStyles || target.latentStyles)
+      ? { latentStyles: { ...(base.latentStyles ?? {}), ...(target.latentStyles ?? {}) } }
+      : {}),
+  };
+}
+
+function mergePreservationStores(
+  base: CanonicalDocument["preservation"],
+  target: CanonicalDocument["preservation"],
+): CanonicalDocument["preservation"] {
+  return {
+    opaqueFragments: {
+      ...base.opaqueFragments,
+      ...target.opaqueFragments,
+    },
+    packageParts: {
+      ...base.packageParts,
+      ...target.packageParts,
+    },
+  };
+}
+
+function mergeRecordCatalog<T extends Record<string, unknown>>(base: T, target: T): T {
+  return projectValue({ ...base, ...target });
+}
+
+function cloneBlock<T extends BlockNode>(block: T): T {
+  return projectValue(block);
+}
+
+function projectValue<T>(value: T): T {
+  return structuredClone(value);
+}

package/src/compare/export-redlines.ts

@@ -0,0 +1,162 @@
+import { TextEncoder } from "node:util";
+
+import type { OpcRelationship } from "../io/ooxml/part-manifest.ts";
+import { serializeMainDocument } from "../io/export/serialize-main-document.ts";
+import {
+  WORD_NUMBERING_CONTENT_TYPE,
+  serializeNumberingXml,
+} from "../io/export/serialize-numbering.ts";
+import { serializeRuntimeRevisionsIntoDocumentXml } from "../io/export/serialize-runtime-revisions.ts";
+import { createExportSession } from "../io/export/export-session.ts";
+import {
+  DOCX_DOCUMENT_CONTENT_TYPE,
+  DOCX_MIME_TYPE,
+  writeDocxPackage,
+} from "../io/opc/docx-package.ts";
+import type { OpcPackage } from "../io/opc/package-reader.ts";
+import { readOpcPackage } from "../io/opc/package-reader.ts";
+import type { RevisionRecord as ReviewRevisionRecord } from "../review/store/revision-types.ts";
+import type { VersionCompareResult } from "./diff-engine.ts";
+
+const MAIN_DOCUMENT_PATH = "/word/document.xml";
+const NUMBERING_PART_PATH = "/word/numbering.xml";
+const NUMBERING_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+
+export interface ExportComparedDocumentOptions {
+  fileName?: string;
+  sourcePackage?: OpcPackage;
+}
+
+export interface ExportComparedDocumentResult {
+  bytes: Uint8Array;
+  mimeType: string;
+  fileName: string;
+}
+
+export function exportComparedDocumentRedlines(
+  result: VersionCompareResult,
+  options: ExportComparedDocumentOptions = {},
+): ExportComparedDocumentResult {
+  const sourcePackage =
+    options.sourcePackage ??
+    readOpcPackage(
+      writeDocxPackage({
+        documentXml: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p/><w:sectPr/></w:body></w:document>`,
+      }),
+    );
+  const existingRelationships =
+    sourcePackage.parts.get(MAIN_DOCUMENT_PATH)?.relationships ?? [];
+
+  const serialized = serializeMainDocument(
+    result.comparedDocument.content,
+    result.comparedDocument.preservation,
+    existingRelationships,
+    {
+      media: result.comparedDocument.media,
+    },
+  );
+  const actionableRevisions = toReviewRevisionRecords(result.comparedDocument.review.revisions);
+  const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
+    serialized.documentXml,
+    actionableRevisions,
+    serialized.paragraphBoundaries,
+  );
+  if (revisionDocument.skippedRevisionIds.length > 0) {
+    throw new Error(
+      `Compare export skipped ${revisionDocument.skippedRevisionIds.length} revision markers.`,
+    );
+  }
+
+  const numberingXml = hasNumberingEntries(result.comparedDocument.numbering)
+    ? serializeNumberingXml(result.comparedDocument.numbering)
+    : undefined;
+  const relationships = withOptionalNumberingRelationship(
+    serialized.relationships,
+    existingRelationships,
+    Boolean(numberingXml),
+  );
+  const exportSession = createExportSession(sourcePackage, [
+    MAIN_DOCUMENT_PATH,
+    ...(numberingXml ? [NUMBERING_PART_PATH] : []),
+  ]);
+
+  exportSession.replaceOwnedPart({
+    path: MAIN_DOCUMENT_PATH,
+    bytes: new TextEncoder().encode(revisionDocument.documentXml),
+    contentType: DOCX_DOCUMENT_CONTENT_TYPE,
+    relationships,
+  });
+
+  if (numberingXml) {
+    exportSession.replaceOwnedPart({
+      path: NUMBERING_PART_PATH,
+      bytes: new TextEncoder().encode(numberingXml),
+      contentType:
+        sourcePackage.parts.get(NUMBERING_PART_PATH)?.contentType ?? WORD_NUMBERING_CONTENT_TYPE,
+    });
+  }
+
+  return {
+    bytes: exportSession.serialize(),
+    mimeType: DOCX_MIME_TYPE,
+    fileName: options.fileName ?? `${result.target.name}-compared.docx`,
+  };
+}
+
+function toReviewRevisionRecords(
+  revisions: VersionCompareResult["comparedDocument"]["review"]["revisions"],
+): ReviewRevisionRecord[] {
+  return Object.values(revisions).map((revision) => ({
+    revisionId: revision.changeId,
+    kind: revision.kind,
+    anchor: revision.anchor,
+    authorId: revision.authorId ?? "Version Compare",
+    createdAt: revision.createdAt,
+    warningIds: [...(revision.warningIds ?? [])],
+    metadata: {
+      source: revision.metadata?.source ?? "runtime",
+      preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+      importedRevisionForm: revision.metadata?.importedRevisionForm,
+      originalRevisionType: revision.metadata?.originalRevisionType,
+      ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+    },
+    status: revision.status === "open" ? "active" : revision.status,
+  }));
+}
+
+function hasNumberingEntries(
+  numbering: VersionCompareResult["comparedDocument"]["numbering"],
+): boolean {
+  return (
+    Object.keys(numbering.abstractDefinitions).length > 0 ||
+    Object.keys(numbering.instances).length > 0
+  );
+}
+
+function withOptionalNumberingRelationship(
+  relationships: readonly OpcRelationship[],
+  existingRelationships: readonly OpcRelationship[],
+  includeNumbering: boolean,
+): OpcRelationship[] {
+  const next = relationships.map((relationship) => ({ ...relationship }));
+  if (!includeNumbering) {
+    return next;
+  }
+
+  const existing = next.find((relationship) => relationship.type === NUMBERING_RELATIONSHIP_TYPE);
+  if (existing) {
+    return next;
+  }
+
+  const fallbackId =
+    existingRelationships.find((relationship) => relationship.type === NUMBERING_RELATIONSHIP_TYPE)?.id ??
+    `rId${next.length + 1}`;
+  next.push({
+    id: fallbackId,
+    type: NUMBERING_RELATIONSHIP_TYPE,
+    target: "numbering.xml",
+    targetMode: "internal",
+  });
+  return next;
+}