@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/validation/compatibility-report.ts

@@ -0,0 +1,161 @@
+import {
+  type CompatibilityDiagnostics,
+  type CompatibilityFeatureClass,
+  type CompatibilityFeatureEntry,
+  type EditorError,
+  type EditorWarning,
+  createDiagnostics,
+  diagnosticsBlockExport,
+  summarizeFeatureClasses,
+} from "./diagnostics.ts";
+
+export const COMPATIBILITY_REPORT_VERSION = "compatibility-report/1" as const;
+
+export const COMPATIBILITY_FEATURE_KEYS = [
+  "paragraphs",
+  "runs",
+  "whitespace",
+  "headings",
+  "lists",
+  "restart-numbering",
+  "tables",
+  "merged-cells",
+  "inline-images",
+  "hyperlinks",
+  "comments-single-paragraph",
+  "comment-threads",
+  "tracked-insertions",
+  "tracked-deletions",
+  "comments-multi-paragraph-ranges",
+  "tracked-moves",
+  "formatting-revisions",
+  "structural-revisions",
+  "sections",
+  "headers-footers",
+  "notes",
+  "fields",
+  "content-controls",
+  "custom-xml",
+  "alt-chunk",
+  "embedded-objects",
+  "floating-drawings",
+  "alternate-content",
+  "unknown-ooxml",
+  "unknown-package-parts",
+  "package-integrity",
+  "relationship-integrity",
+  "workflow-scopes",
+] as const;
+
+export type CompatibilityFeatureKey =
+  (typeof COMPATIBILITY_FEATURE_KEYS)[number];
+
+export interface CompatibilityReport<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+> extends CompatibilityDiagnostics<FeatureKey, FeatureClass> {
+  reportVersion: typeof COMPATIBILITY_REPORT_VERSION;
+  generatedAt: string;
+  blockExport: boolean;
+}
+
+export interface CreateCompatibilityReportInput<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+> extends Partial<CompatibilityDiagnostics<FeatureKey, FeatureClass>> {
+  generatedAt: string;
+  blockExport?: boolean;
+}
+
+export interface CompatibilityReportSummary {
+  generatedAt: string;
+  blockExport: boolean;
+  featureClassCounts: Record<CompatibilityFeatureClass, number>;
+  warningCount: number;
+  errorCount: number;
+}
+
+export function createCompatibilityReport<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+>(
+  input: CreateCompatibilityReportInput<FeatureKey, FeatureClass>,
+): CompatibilityReport<FeatureKey, FeatureClass> {
+  const diagnostics = createDiagnostics(input);
+
+  return Object.freeze({
+    reportVersion: COMPATIBILITY_REPORT_VERSION,
+    generatedAt: input.generatedAt,
+    blockExport: diagnosticsBlockExport(diagnostics, input.blockExport),
+    featureEntries: diagnostics.featureEntries,
+    warnings: diagnostics.warnings,
+    errors: diagnostics.errors,
+  });
+}
+
+export function mergeCompatibilityReports<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+>(
+  reports: readonly CompatibilityReport<FeatureKey, FeatureClass>[],
+  options: {
+    generatedAt: string;
+    blockExport?: boolean;
+  },
+): CompatibilityReport<FeatureKey, FeatureClass> {
+  return createCompatibilityReport({
+    generatedAt: options.generatedAt,
+    blockExport:
+      options.blockExport ?? reports.some((report) => report.blockExport),
+    featureEntries: flattenUnique(reports.flatMap((report) => report.featureEntries)),
+    warnings: flattenUnique(reports.flatMap((report) => report.warnings)),
+    errors: flattenUnique(reports.flatMap((report) => report.errors)),
+  });
+}
+
+export function summarizeCompatibilityReport<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+>(
+  report: CompatibilityReport<FeatureKey, FeatureClass>,
+): CompatibilityReportSummary {
+  return {
+    generatedAt: report.generatedAt,
+    blockExport: report.blockExport,
+    featureClassCounts: summarizeFeatureClasses(report.featureEntries),
+    warningCount: report.warnings.length,
+    errorCount: report.errors.length,
+  };
+}
+
+export function findFeatureEntry<
+  FeatureKey extends string = CompatibilityFeatureKey,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+>(
+  report: CompatibilityReport<FeatureKey, FeatureClass>,
+  featureEntryId: string,
+): CompatibilityFeatureEntry<FeatureKey, FeatureClass> | undefined {
+  return report.featureEntries.find(
+    (featureEntry) => featureEntry.featureEntryId === featureEntryId,
+  );
+}
+
+export type {
+  CompatibilityDiagnostics,
+  CompatibilityFeatureClass,
+  CompatibilityFeatureEntry,
+  EditorError,
+  EditorWarning,
+} from "./diagnostics.ts";
+
+function flattenUnique<Value extends object>(
+  items: readonly Value[],
+): readonly Value[] {
+  const deduped = new Map<string, Value>();
+
+  for (const item of items) {
+    deduped.set(JSON.stringify(item), item);
+  }
+
+  return Object.freeze([...deduped.values()]);
+}

package/src/validation/diagnostics.ts

@@ -0,0 +1,204 @@
+export const COMPATIBILITY_FEATURE_CLASSES = [
+  "supported-roundtrip",
+  "preserve-only",
+  "unsupported-fatal",
+] as const;
+
+export type CompatibilityFeatureClass =
+  (typeof COMPATIBILITY_FEATURE_CLASSES)[number];
+
+export const EDITOR_WARNING_CODES = [
+  "unsupported_ooxml_preserved",
+  "unsupported_ooxml_locked",
+  "import_normalized",
+  "export_roundtrip_risk",
+  "comment_anchor_detached",
+  "revision_anchor_detached",
+  "large_document_degraded",
+  "font_substitution",
+  "image_missing",
+] as const;
+
+export type EditorWarningCode = (typeof EDITOR_WARNING_CODES)[number];
+
+export const EDITOR_WARNING_SOURCES = [
+  "import",
+  "runtime",
+  "review",
+  "preservation",
+  "validation",
+  "export",
+] as const;
+
+export type EditorWarningSource = (typeof EDITOR_WARNING_SOURCES)[number];
+
+export const EDITOR_ERROR_CODES = [
+  "import_failed",
+  "export_failed",
+  "package_corrupt",
+  "validation_failed",
+  "datastore_failed",
+  "internal_invariant",
+] as const;
+
+export type EditorErrorCode = (typeof EDITOR_ERROR_CODES)[number];
+
+export const EDITOR_ERROR_SOURCES = [
+  "import",
+  "runtime",
+  "validation",
+  "datastore",
+  "host",
+  "export",
+] as const;
+
+export type EditorErrorSource = (typeof EDITOR_ERROR_SOURCES)[number];
+
+export type EditorAnchorProjection =
+  | {
+      kind: "range";
+      from: number;
+      to: number;
+      assoc: {
+        start: -1 | 1;
+        end: -1 | 1;
+      };
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: {
+        from: number;
+        to: number;
+      };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+    };
+
+export interface EditorWarning {
+  warningId: string;
+  code: EditorWarningCode;
+  severity: "info" | "warning";
+  message: string;
+  source: EditorWarningSource;
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface EditorError {
+  errorId: string;
+  code: EditorErrorCode;
+  message: string;
+  isFatal: boolean;
+  source: EditorErrorSource;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityFeatureEntry<
+  FeatureKey extends string = string,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+> {
+  featureEntryId: string;
+  featureKey: FeatureKey;
+  featureClass: FeatureClass;
+  message: string;
+  affectedAnchor?: EditorAnchorProjection;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityDiagnostics<
+  FeatureKey extends string = string,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+> {
+  featureEntries: readonly CompatibilityFeatureEntry<FeatureKey, FeatureClass>[];
+  warnings: readonly EditorWarning[];
+  errors: readonly EditorError[];
+}
+
+const EXPORT_BLOCKING_ERROR_CODES = new Set<EditorErrorCode>([
+  "import_failed",
+  "export_failed",
+  "package_corrupt",
+  "validation_failed",
+]);
+
+export function isCompatibilityFeatureClass(
+  value: string,
+): value is CompatibilityFeatureClass {
+  return COMPATIBILITY_FEATURE_CLASSES.includes(
+    value as CompatibilityFeatureClass,
+  );
+}
+
+export function isEditorWarningCode(value: string): value is EditorWarningCode {
+  return EDITOR_WARNING_CODES.includes(value as EditorWarningCode);
+}
+
+export function isEditorErrorCode(value: string): value is EditorErrorCode {
+  return EDITOR_ERROR_CODES.includes(value as EditorErrorCode);
+}
+
+export function createDiagnostics<
+  FeatureKey extends string = string,
+  FeatureClass extends CompatibilityFeatureClass = CompatibilityFeatureClass,
+>(
+  input: Partial<CompatibilityDiagnostics<FeatureKey, FeatureClass>> = {},
+): CompatibilityDiagnostics<FeatureKey, FeatureClass> {
+  return {
+    featureEntries: freezeArray(input.featureEntries ?? []),
+    warnings: freezeArray(input.warnings ?? []),
+    errors: freezeArray(input.errors ?? []),
+  };
+}
+
+export function collectWarningIds(warnings: readonly EditorWarning[]): string[] {
+  return warnings.map((warning) => warning.warningId);
+}
+
+export function summarizeFeatureClasses<
+  FeatureKey extends string,
+  FeatureClass extends CompatibilityFeatureClass,
+>(
+  featureEntries: readonly CompatibilityFeatureEntry<FeatureKey, FeatureClass>[],
+): Record<CompatibilityFeatureClass, number> {
+  return featureEntries.reduce<Record<CompatibilityFeatureClass, number>>(
+    (counts, entry) => {
+      counts[entry.featureClass] += 1;
+      return counts;
+    },
+    {
+      "supported-roundtrip": 0,
+      "preserve-only": 0,
+      "unsupported-fatal": 0,
+    },
+  );
+}
+
+export function diagnosticsBlockExport<
+  FeatureKey extends string,
+  FeatureClass extends CompatibilityFeatureClass,
+>(
+  diagnostics: CompatibilityDiagnostics<FeatureKey, FeatureClass>,
+  explicitBlockExport = false,
+): boolean {
+  if (explicitBlockExport) {
+    return true;
+  }
+
+  return (
+    diagnostics.featureEntries.some(
+      (entry) => entry.featureClass === "unsupported-fatal",
+    ) ||
+    diagnostics.errors.some(
+      (error) => error.isFatal || EXPORT_BLOCKING_ERROR_CODES.has(error.code),
+    )
+  );
+}
+
+function freezeArray<Value>(items: readonly Value[]): readonly Value[] {
+  return Object.freeze([...items]);
+}