@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/validation/compatibility-engine.ts

@@ -0,0 +1,878 @@
+import { createRangeAnchor } from "../core/selection/mapping.ts";
+import type {
+  CanonicalDocumentEnvelope,
+  CompatibilityFeatureEntry,
+  CompatibilityReport,
+  EditorError,
+  EditorWarning,
+} from "../core/state/editor-state.ts";
+import type {
+  BlockNode,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+import {
+  describeOpaqueFragment,
+  describeStructuredWrapperBlock,
+  listOpaqueFragments,
+  listPreservedPackageParts,
+} from "../preservation/store.ts";
+
+export interface BuildCompatibilityReportInput {
+  document: CanonicalDocumentEnvelope;
+  warnings?: readonly EditorWarning[];
+  fatalError?: EditorError;
+  generatedAt: string;
+}
+
+export function buildCompatibilityReport(
+  input: BuildCompatibilityReportInput,
+): CompatibilityReport {
+  const content = normalizeDocumentRoot(input.document.content);
+  const contentFeatures = collectContentFeatures(content);
+  if (hasSupportedRuntimeComments(input.document.review.comments)) {
+    contentFeatures.push(
+      supportedEntry(
+        "comments-single-paragraph",
+        "Single-paragraph review comments stay mappable through runtime selections.",
+      ),
+    );
+  }
+  const featureEntries: CompatibilityFeatureEntry[] = [
+    ...contentFeatures,
+    ...collectStructuredWrapperFeatures(content),
+    ...collectReviewFeatures(input.document),
+    ...collectPreservationFeatures(input.document),
+  ];
+  const warnings = dedupeWarnings([
+    ...(input.warnings ?? []),
+    ...collectDiagnosticWarnings(input.document),
+  ]);
+  const errors = dedupeErrors([
+    ...collectDiagnosticErrors(input.document),
+    ...(input.fatalError ? [input.fatalError] : []),
+  ]);
+
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt: input.generatedAt,
+    blockExport:
+      featureEntries.some((entry) => entry.featureClass === "unsupported-fatal") ||
+      errors.some((error) => error.isFatal),
+    featureEntries,
+    warnings,
+    errors,
+  };
+}
+
+function hasSupportedRuntimeComments(
+  comments: CanonicalDocumentEnvelope["review"]["comments"],
+): boolean {
+  return Object.values(comments).some((comment) => comment.anchor.kind !== "detached");
+}
+
+function collectReviewFeatures(
+  document: CanonicalDocumentEnvelope,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+  const comments = Object.values(document.review.comments ?? {});
+  const revisions = Object.values(document.review.revisions ?? {});
+
+  const multiParagraphComment = comments.find(
+    (comment) => comment.metadata?.detachedReason === "multi-paragraph" && comment.anchor.kind === "detached",
+  );
+  if (multiParagraphComment?.anchor.kind === "detached") {
+    entries.push({
+      featureEntryId: "feature:comments-multi-paragraph-ranges",
+      featureKey: "comments-multi-paragraph-ranges",
+      featureClass: "preserve-only",
+      message:
+        "Cross-paragraph comment anchors remain visible but detached to preserve package truth and export safety.",
+      affectedAnchor: createRangeAnchor(
+        multiParagraphComment.anchor.lastKnownRange.from,
+        multiParagraphComment.anchor.lastKnownRange.to,
+      ),
+      details: {
+        commentId: multiParagraphComment.commentId,
+        detachedReason: multiParagraphComment.metadata?.detachedReason,
+        actionabilityNote: multiParagraphComment.metadata?.actionabilityNote,
+      },
+    });
+  }
+
+  const moveRevision = revisions.find((revision) => revision.kind === "move");
+  if (moveRevision) {
+    entries.push({
+      featureEntryId: "feature:tracked-moves",
+      featureKey: "tracked-moves",
+      featureClass: "preserve-only",
+      message:
+        "Tracked move revisions are preserved for round-trip and review visibility but remain non-actionable in the current runtime.",
+      affectedAnchor: toRevisionAffectedAnchor(moveRevision),
+      details: {
+        revisionId: moveRevision.changeId,
+        moveDirection: moveRevision.metadata?.moveData?.direction,
+        linkedRevisionId: moveRevision.metadata?.moveData?.linkedRevisionId,
+      },
+    });
+  }
+
+  const formattingRevisions = revisions.filter(
+    (revision) =>
+      revision.kind === "formatting" ||
+      (revision.kind === "property-change" && revision.metadata?.propertyChangeData?.xmlTag === "rPrChange"),
+  );
+  if (formattingRevisions.length > 0) {
+    const featureClass = formattingRevisions.some(
+      (revision) => typeof revision.metadata?.preserveOnlyReason === "string" && revision.metadata.preserveOnlyReason.length > 0,
+    )
+      ? "preserve-only"
+      : "supported-roundtrip";
+    entries.push({
+      featureEntryId: "feature:formatting-revisions",
+      featureKey: "formatting-revisions",
+      featureClass,
+      message:
+        featureClass === "preserve-only"
+          ? "Formatting revisions remain visible for review, but at least one formatting-change slice is still preserve-only."
+          : "Formatting-change revisions remain structured and round-trip through the runtime review model.",
+      affectedAnchor: toRevisionAffectedAnchor(formattingRevisions[0]!),
+      details: {
+        revisionCount: formattingRevisions.length,
+      },
+    });
+  }
+
+  const structuralRevisions = revisions.filter(
+    (revision) =>
+      revision.kind === "property-change" &&
+      revision.metadata?.propertyChangeData?.xmlTag !== "rPrChange",
+  );
+  if (structuralRevisions.length > 0) {
+    const featureClass = structuralRevisions.some(
+      (revision) => typeof revision.metadata?.preserveOnlyReason === "string" && revision.metadata.preserveOnlyReason.length > 0,
+    )
+      ? "preserve-only"
+      : "supported-roundtrip";
+    entries.push({
+      featureEntryId: "feature:structural-revisions",
+      featureKey: "structural-revisions",
+      featureClass,
+      message:
+        featureClass === "preserve-only"
+          ? "Structural property revisions are preserved for round-trip, but at least one slice remains non-actionable."
+          : "Structured paragraph, table, or section property revisions remain mapped in the runtime review model.",
+      affectedAnchor: toRevisionAffectedAnchor(structuralRevisions[0]!),
+      details: {
+        revisionCount: structuralRevisions.length,
+        revisionKinds: structuralRevisions.map(
+          (revision) => revision.metadata?.propertyChangeData?.xmlTag ?? revision.kind,
+        ),
+      },
+    });
+  }
+
+  return entries;
+}
+
+function normalizeDocumentRoot(content: unknown): DocumentRootNode {
+  if (content && typeof content === "object" && (content as { type?: string }).type === "doc") {
+    return content as DocumentRootNode;
+  }
+
+  if (Array.isArray(content)) {
+    return {
+      type: "doc",
+      children: content.filter(
+        (value): value is DocumentRootNode["children"][number] =>
+          Boolean(value) &&
+          typeof value === "object" &&
+          ((value as { type?: string }).type === "paragraph" ||
+            (value as { type?: string }).type === "opaque_block"),
+      ),
+    };
+  }
+
+  return {
+    type: "doc",
+    children: [{ type: "paragraph", children: [] }],
+  };
+}
+
+function collectContentFeatures(
+  content: DocumentRootNode,
+): CompatibilityFeatureEntry[] {
+  const flags = {
+    paragraphs: false,
+    runs: false,
+    whitespace: false,
+    headings: false,
+    lists: false,
+    hyperlinks: false,
+    images: false,
+    tables: false,
+    mergedCells: false,
+    sections: false,
+    contentControls: false,
+  };
+
+  for (let index = 0; index < content.children.length; index += 1) {
+    measureBlock(content.children[index], flags);
+  }
+
+  const entries: CompatibilityFeatureEntry[] = [];
+  if (flags.paragraphs) {
+    entries.push(supportedEntry("paragraphs", "Paragraph structure is editable and round-trippable."));
+  }
+  if (flags.runs) {
+    entries.push(supportedEntry("runs", "Runs and inline text are editable through runtime commands."));
+  }
+  if (flags.whitespace) {
+    entries.push(supportedEntry("whitespace", "Whitespace-sensitive text units stay explicit in the runtime model."));
+  }
+  if (flags.headings) {
+    entries.push(supportedEntry("headings", "Heading styles remain attached to paragraph structure."));
+  }
+  if (flags.lists) {
+    entries.push(supportedEntry("lists", "Numbering metadata stays attached to paragraph blocks."));
+  }
+  if (flags.hyperlinks) {
+    entries.push(supportedEntry("hyperlinks", "Hyperlink relationships are preserved and re-serialized."));
+  }
+  if (flags.images) {
+    entries.push(supportedEntry("inline-images", "Inline image placements stay attached to preserved media parts."));
+  }
+  if (flags.tables) {
+    entries.push(
+      supportedEntry(
+        "tables",
+        "Structured tables keep bounded topology and common visual properties through runtime editing and export.",
+      ),
+    );
+  }
+  if (flags.mergedCells) {
+    entries.push(
+      supportedEntry(
+        "merged-cells",
+        "Merged-cell topology survives through the supported table runtime and export path.",
+      ),
+    );
+  }
+  if (flags.sections) {
+    entries.push(
+      supportedEntry(
+        "sections",
+        "Section boundaries and page-layout properties remain structured and export-safe.",
+      ),
+    );
+  }
+  if (flags.contentControls) {
+    entries.push(
+      supportedEntry(
+        "content-controls",
+        "Common content controls render through structured SDT state and round-trip without flattening to opaque placeholders.",
+      ),
+    );
+  }
+  return entries;
+}
+
+function measureBlock(
+  block: BlockNode,
+  flags: {
+    paragraphs: boolean;
+    runs: boolean;
+    whitespace: boolean;
+    headings: boolean;
+    lists: boolean;
+    hyperlinks: boolean;
+    images: boolean;
+    tables: boolean;
+    mergedCells: boolean;
+    sections: boolean;
+    contentControls: boolean;
+  },
+): number {
+  switch (block.type) {
+    case "paragraph":
+      flags.paragraphs = true;
+      if (block.styleId?.toLowerCase().startsWith("heading")) {
+        flags.headings = true;
+      }
+      if (block.numbering) {
+        flags.lists = true;
+      }
+      return measureParagraph(block, flags);
+    case "table":
+      flags.tables = true;
+      if (
+        block.rows.some((row) =>
+          row.cells.some((cell) => (cell.gridSpan ?? 1) > 1 || cell.verticalMerge != null),
+        )
+      ) {
+        flags.mergedCells = true;
+      }
+      return block.rows.reduce(
+        (size, row) =>
+          size +
+          row.cells.reduce(
+            (cellSize, cell) =>
+              cellSize + cell.children.reduce((childSize, child) => childSize + measureBlock(child, flags), 0),
+            0,
+          ),
+        0,
+      );
+    case "sdt":
+      if (describeStructuredWrapperBlock(block)?.featureKey === "content-controls") {
+        return 1;
+      }
+      flags.contentControls = true;
+      return block.children.reduce((size, child) => size + measureBlock(child, flags), 0);
+    case "custom_xml":
+      return 1;
+    case "alt_chunk":
+      return 1;
+    case "section_break":
+      flags.sections = true;
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+function collectStructuredWrapperFeatures(
+  content: DocumentRootNode,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+  let structuredWrapperIndex = 0;
+
+  function visitBlock(block: BlockNode): void {
+    const descriptor = describeStructuredWrapperBlock(block);
+    if (descriptor) {
+      entries.push({
+        featureEntryId: `feature:structured-wrapper:${structuredWrapperIndex}`,
+        featureKey: descriptor.featureKey,
+        featureClass: "preserve-only",
+        message: descriptor.label,
+        details: {
+          detail: descriptor.detail,
+          surface: "structured-wrapper",
+        },
+      });
+      structuredWrapperIndex += 1;
+      return;
+    }
+
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          for (const child of cell.children) {
+            visitBlock(child);
+          }
+        }
+      }
+      return;
+    }
+
+    if (block.type === "sdt") {
+      for (const child of block.children) {
+        visitBlock(child);
+      }
+    }
+  }
+
+  for (const block of content.children) {
+    visitBlock(block);
+  }
+
+  return entries;
+}
+
+function measureParagraph(
+  paragraph: ParagraphNode,
+  flags: {
+    paragraphs: boolean;
+    runs: boolean;
+    whitespace: boolean;
+    hyperlinks: boolean;
+    images: boolean;
+    tables: boolean;
+    sections: boolean;
+    contentControls: boolean;
+  },
+): number {
+  let size = 0;
+  const children = Array.isArray(paragraph.children) ? paragraph.children : [];
+
+  for (const child of children) {
+    size += measureInlineNode(child, flags);
+  }
+
+  return size;
+}
+
+function measureInlineNode(
+  node: InlineNode,
+  flags: {
+    paragraphs: boolean;
+    runs: boolean;
+    whitespace: boolean;
+    hyperlinks: boolean;
+    images: boolean;
+    tables: boolean;
+    sections: boolean;
+    contentControls: boolean;
+  },
+): number {
+  switch (node.type) {
+    case "text":
+      flags.runs = flags.runs || node.text.length > 0;
+      flags.whitespace =
+        flags.whitespace ||
+        /^\s/u.test(node.text) ||
+        /\s$/u.test(node.text) ||
+        node.text.includes("  ");
+      return Array.from(node.text).length;
+    case "tab":
+    case "hard_break":
+      flags.runs = true;
+      flags.whitespace = true;
+      return 1;
+    case "hyperlink":
+      flags.runs = true;
+      flags.hyperlinks = true;
+      return node.children.reduce((size, child) => size + measureInlineNode(child, flags), 0);
+    case "image":
+      flags.images = true;
+      flags.runs = true;
+      return 1;
+    case "opaque_inline":
+      flags.runs = true;
+      return 1;
+    case "column_break":
+    case "symbol":
+    case "field":
+    case "bookmark_start":
+    case "bookmark_end":
+    case "footnote_ref":
+    case "chart_preview":
+    case "smartart_preview":
+    case "shape":
+    case "wordart":
+    case "vml_shape":
+    default:
+      flags.runs = true;
+      return 1;
+  }
+}
+
+function collectPreservationFeatures(
+  document: CanonicalDocumentEnvelope,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+  const structuredSubPartPaths = collectStructuredSubPartPaths(document);
+
+  entries.push(...collectSubPartFeatures(document));
+
+  for (const fragment of listOpaqueFragments(document.preservation as never)) {
+    const descriptor = describeOpaqueFragment(fragment);
+    entries.push({
+      featureEntryId: `feature:${fragment.fragmentId}`,
+      featureKey: descriptor.featureKey,
+      featureClass: "preserve-only",
+      message: descriptor.label,
+      affectedAnchor: createRangeAnchor(
+        fragment.lastKnownRange.from,
+        fragment.lastKnownRange.to,
+      ),
+      details: {
+        fragmentId: fragment.fragmentId,
+        warningId: fragment.warningId,
+        detail: descriptor.detail,
+      },
+    });
+  }
+
+  for (const packagePart of listPreservedPackageParts(document.preservation as never)) {
+    if (structuredSubPartPaths.has(packagePart.packagePartName)) {
+      continue;
+    }
+
+    entries.push({
+      featureEntryId: `feature:package:${packagePart.packagePartName}`,
+      featureKey: "unknown-package-parts",
+      featureClass: "preserve-only",
+      message: `Preserved package part ${packagePart.packagePartName}.`,
+      details: {
+        packagePartName: packagePart.packagePartName,
+        contentType: packagePart.contentType,
+        relationshipIds: packagePart.relationshipIds,
+      },
+    });
+  }
+
+  return entries;
+}
+
+function collectStructuredSubPartPaths(
+  document: CanonicalDocumentEnvelope,
+): ReadonlySet<string> {
+  const subParts = document.subParts;
+  if (!subParts) {
+    return new Set<string>();
+  }
+
+  const paths = new Set<string>();
+
+  for (const header of subParts.headers ?? []) {
+    paths.add(header.partPath);
+  }
+
+  for (const footer of subParts.footers ?? []) {
+    paths.add(footer.partPath);
+  }
+
+  if (subParts.footnoteCollection) {
+    paths.add("/word/footnotes.xml");
+    paths.add("/word/endnotes.xml");
+  }
+
+  if (subParts.theme) {
+    paths.add("/word/theme/theme1.xml");
+  }
+
+  return paths;
+}
+
+function collectSubPartFeatures(
+  document: CanonicalDocumentEnvelope,
+): CompatibilityFeatureEntry[] {
+  const subParts = document.subParts;
+  if (!subParts) {
+    return [];
+  }
+
+  const entries: CompatibilityFeatureEntry[] = collectLossySubPartFeatures(subParts);
+  const hasHeaderFooterContent = (subParts.headers?.length ?? 0) > 0 || (subParts.footers?.length ?? 0) > 0;
+  const noteCount =
+    Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length +
+    Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length;
+  const headerFooterBookmarkCount =
+    [...(subParts.headers ?? []), ...(subParts.footers ?? [])].reduce(
+      (count, subPart) => count + countBookmarksInBlocks(subPart.blocks),
+      0,
+    );
+  const noteBookmarkCount =
+    [
+      ...Object.values(subParts.footnoteCollection?.footnotes ?? {}),
+      ...Object.values(subParts.footnoteCollection?.endnotes ?? {}),
+    ].reduce((count, note) => count + countBookmarksInBlocks(note.blocks), 0);
+
+  if (hasHeaderFooterContent && !entries.some((entry) => entry.featureKey === "headers-footers-lossy")) {
+    entries.push({
+      featureEntryId: "feature:subparts:headers-footers",
+      featureKey: "headers-footers",
+      featureClass: "supported-roundtrip",
+      message: "Headers and footers resolve as structured secondary stories with export-safe ownership.",
+      details: {
+        headerCount: subParts.headers?.length ?? 0,
+        footerCount: subParts.footers?.length ?? 0,
+        bookmarkCount: headerFooterBookmarkCount,
+      },
+    });
+  }
+
+  if (noteCount > 0 && !entries.some((entry) => entry.featureKey === "notes-lossy")) {
+    entries.push({
+      featureEntryId: "feature:subparts:notes",
+      featureKey: "notes",
+      featureClass: "supported-roundtrip",
+      message: "Footnotes and endnotes resolve as structured secondary stories with export-safe ownership.",
+      details: {
+        footnoteCount: Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length,
+        endnoteCount: Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length,
+        bookmarkCount: noteBookmarkCount,
+      },
+    });
+  }
+
+  if (subParts.theme) {
+    entries.push({
+      featureEntryId: "feature:subparts:theme",
+      featureKey: "unknown-package-parts",
+      featureClass: "preserve-only",
+      message: "Theme metadata is preserved through structured sub-part ownership.",
+      details: {
+        surface: "theme-subpart",
+        themeName: subParts.theme.name,
+      },
+    });
+  }
+
+  return entries;
+}
+
+function collectLossySubPartFeatures(
+  subParts: NonNullable<CanonicalDocumentEnvelope["subParts"]>,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+
+  const headerFooterLossy = [
+    ...(subParts.headers ?? []).flatMap((header) =>
+      collectLossyBlocks(header.blocks, `header:${header.partPath}`),
+    ),
+    ...(subParts.footers ?? []).flatMap((footer) =>
+      collectLossyBlocks(footer.blocks, `footer:${footer.partPath}`),
+    ),
+  ];
+  if (headerFooterLossy.length > 0) {
+    entries.push({
+      featureEntryId: "feature:subparts:headers-footers-lossy",
+      featureKey: "headers-footers-lossy",
+      featureClass: "unsupported-fatal",
+      message: "Headers or footers contain content the current sub-part serializer cannot re-emit safely.",
+      details: {
+        issues: headerFooterLossy,
+      },
+    });
+  }
+
+  const noteLossy = [
+    ...Object.values(subParts.footnoteCollection?.footnotes ?? {}).flatMap((note) =>
+      collectLossyBlocks(note.blocks, `footnote:${note.noteId}`),
+    ),
+    ...Object.values(subParts.footnoteCollection?.endnotes ?? {}).flatMap((note) =>
+      collectLossyBlocks(note.blocks, `endnote:${note.noteId}`),
+    ),
+  ];
+  if (noteLossy.length > 0) {
+    entries.push({
+      featureEntryId: "feature:subparts:notes-lossy",
+      featureKey: "notes-lossy",
+      featureClass: "unsupported-fatal",
+      message: "Footnotes or endnotes contain content the current sub-part serializer cannot re-emit safely.",
+      details: {
+        issues: noteLossy,
+      },
+    });
+  }
+
+  return entries;
+}
+
+function countBookmarksInBlocks(blocks: readonly BlockNode[]): number {
+  return blocks.reduce((count, block) => count + countBookmarksInBlock(block), 0);
+}
+
+function countBookmarksInBlock(block: BlockNode): number {
+  switch (block.type) {
+    case "paragraph":
+      return (block.children ?? []).reduce((count, child) => count + countBookmarksInInlineNode(child), 0);
+    case "table":
+      return block.rows.reduce(
+        (count, row) =>
+          count +
+          row.cells.reduce(
+            (cellCount, cell) =>
+              cellCount + cell.children.reduce((childCount, child) => childCount + countBookmarksInBlock(child), 0),
+            0,
+          ),
+        0,
+      );
+    case "sdt":
+    case "custom_xml":
+      return block.children.reduce((count, child) => count + countBookmarksInBlock(child), 0);
+    default:
+      return 0;
+  }
+}
+
+function countBookmarksInInlineNode(node: InlineNode): number {
+  switch (node.type) {
+    case "bookmark_start":
+      return 1;
+    case "hyperlink":
+    case "field":
+      return (node.children ?? []).reduce((count, child) => count + countBookmarksInInlineNode(child), 0);
+    default:
+      return 0;
+  }
+}
+
+function collectLossyBlocks(
+  blocks: readonly BlockNode[],
+  surface: string,
+): string[] {
+  const issues: string[] = [];
+
+  for (const block of blocks) {
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          issues.push(...collectLossyBlocks(cell.children, `${surface}:table-cell`));
+        }
+      }
+      continue;
+    }
+
+    if (block.type !== "paragraph") {
+      issues.push(`${surface}:${block.type}`);
+      continue;
+    }
+
+    if (
+      block.numbering !== undefined ||
+      block.keepNext !== undefined ||
+      block.keepLines !== undefined ||
+      block.outlineLevel !== undefined ||
+      block.pageBreakBefore !== undefined ||
+      block.widowControl !== undefined ||
+      block.borders !== undefined ||
+      block.shading !== undefined ||
+      block.bidi !== undefined ||
+      block.suppressLineNumbers !== undefined ||
+      block.cnfStyle !== undefined
+    ) {
+      issues.push(`${surface}:paragraph-properties`);
+    }
+
+    for (const child of block.children) {
+      issues.push(...collectLossyInlineContent(child, surface));
+    }
+  }
+
+  return [...new Set(issues)];
+}
+
+function collectLossyInlineContent(
+  node: InlineNode,
+  surface: string,
+): string[] {
+  switch (node.type) {
+    case "text": {
+      const allowSecondaryStoryColorMarks =
+        surface.startsWith("header:") || surface.startsWith("footer:");
+      const unsupportedMarks = (node.marks ?? [])
+        .filter(
+          (mark) =>
+            mark.type !== "bold" &&
+            mark.type !== "italic" &&
+            mark.type !== "underline" &&
+            mark.type !== "strikethrough" &&
+            mark.type !== "doubleStrikethrough" &&
+            mark.type !== "fontFamily" &&
+            mark.type !== "fontSize" &&
+            mark.type !== "textColor" &&
+            (!allowSecondaryStoryColorMarks || mark.type !== "backgroundColor") &&
+            (!allowSecondaryStoryColorMarks || mark.type !== "highlight") &&
+            mark.type !== "smallCaps" &&
+            mark.type !== "allCaps",
+        )
+        .map((mark) => `${surface}:mark:${mark.type}`);
+      return unsupportedMarks;
+    }
+    case "tab":
+    case "hard_break":
+    case "footnote_ref":
+    case "field":
+    case "bookmark_start":
+    case "bookmark_end":
+    case "shape":
+    case "wordart":
+    case "vml_shape":
+    case "chart_preview":
+    case "smartart_preview":
+      return [];
+    default:
+      return [`${surface}:${node.type}`];
+  }
+}
+
+function collectDiagnosticWarnings(
+  document: CanonicalDocumentEnvelope,
+): EditorWarning[] {
+  const diagnostics = Array.isArray(document.diagnostics?.warnings)
+    ? document.diagnostics.warnings
+    : [];
+
+  return diagnostics.map((warning) => ({
+    warningId: warning.warningId,
+    code:
+      warning.source === "validation" || warning.source === "export"
+        ? "export_roundtrip_risk"
+        : warning.source === "preservation"
+          ? "unsupported_ooxml_preserved"
+          : "import_normalized",
+    severity: "warning",
+    message: warning.message,
+    source: warning.source,
+  }));
+}
+
+function collectDiagnosticErrors(
+  document: CanonicalDocumentEnvelope,
+): EditorError[] {
+  const diagnostics = Array.isArray(document.diagnostics?.errors)
+    ? document.diagnostics.errors
+    : [];
+
+  return diagnostics.map((error) => ({
+    errorId: error.diagnosticId,
+    code:
+      error.code === "load_failed"
+        ? "import_failed"
+        : error.code,
+    message: error.message,
+    isFatal: error.isFatal,
+    source: error.source,
+  }));
+}
+
+function supportedEntry(
+  featureKey: CompatibilityFeatureEntry["featureKey"],
+  message: string,
+): CompatibilityFeatureEntry {
+  return {
+    featureEntryId: `feature:${featureKey}`,
+    featureKey,
+    featureClass: "supported-roundtrip",
+    message,
+  };
+}
+
+function toRevisionAffectedAnchor(
+  revision: CanonicalDocumentEnvelope["review"]["revisions"][string],
+) {
+  switch (revision.anchor.kind) {
+    case "range":
+      return createRangeAnchor(revision.anchor.range.from, revision.anchor.range.to);
+    case "node":
+      return createRangeAnchor(revision.anchor.at, revision.anchor.at + 1);
+    case "detached":
+      return createRangeAnchor(
+        revision.anchor.lastKnownRange.from,
+        revision.anchor.lastKnownRange.to,
+      );
+  }
+}
+
+function dedupeWarnings(warnings: EditorWarning[]): EditorWarning[] {
+  const byId = new Map<string, EditorWarning>();
+
+  for (const warning of warnings) {
+    byId.set(warning.warningId, warning);
+  }
+
+  return [...byId.values()];
+}
+
+function dedupeErrors(errors: EditorError[]): EditorError[] {
+  const byId = new Map<string, EditorError>();
+
+  for (const error of errors) {
+    byId.set(error.errorId, error);
+  }
+
+  return [...byId.values()];
+}