@beyondwork/docx-react-component 1.0.28 → 1.0.29

package/src/validation/README.md

@@ -1,3 +0,0 @@
-# Validation
-
-Compatibility checks, round-trip validation, support classification, and Word reopen evidence helpers belong here.

package/src/validation/compatibility-engine.ts

@@ -1,634 +0,0 @@
-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,
-  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,
-    ...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 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,
-    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 cell topology and common visual properties through runtime editing and export.",
-      ),
-    );
-  }
-  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;
-    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;
-      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":
-      flags.contentControls = true;
-      return block.children.reduce((size, child) => size + measureBlock(child, flags), 0);
-    case "custom_xml":
-      return block.children.reduce((size, child) => size + measureBlock(child, flags), 0);
-    case "section_break":
-      flags.sections = true;
-      return 1;
-    default:
-      return 0;
-  }
-}
-
-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;
-
-  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,
-      },
-    });
-  }
-
-  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,
-      },
-    });
-  }
-
-  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 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 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()];
-}