@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/validation/compatibility-report.ts

@@ -0,0 +1,160 @@
+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",
+] 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 { [key: string]: unknown }>(
+  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,203 @@
+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",
+  "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]);
+}

package/src/validation/import-diagnostics.ts

@@ -0,0 +1,128 @@
+import type {
+  CompatibilityFeatureEntry,
+  EditorError,
+} from "../api/public-types.ts";
+import {
+  createCorruptPackageError,
+  createCorruptPackageDiagnosticsToken,
+  type CorruptPackageIssue,
+} from "../io/opc/corrupt-package.ts";
+import {
+  createDiagnostics,
+  diagnosticsBlockExport,
+  type CompatibilityDiagnostics,
+} from "./diagnostics.ts";
+
+export const IMPORT_FAILURE_STAGES = ["package", "validation"] as const;
+
+export type ImportFailureStage = (typeof IMPORT_FAILURE_STAGES)[number];
+
+export interface ImportDiagnosticsResult {
+  mode: "read-only-diagnostics";
+  readOnly: true;
+  blockExport: true;
+  fatalError: EditorError;
+  diagnostics: CompatibilityDiagnostics;
+  featureEntry: CompatibilityFeatureEntry;
+}
+
+export function createPackageImportDiagnostics(input: {
+  issue: CorruptPackageIssue;
+}): ImportDiagnosticsResult {
+  const fatalError = createCorruptPackageError(input.issue);
+  const featureEntry = {
+    featureEntryId: `feature:${fatalError.errorId}`,
+    featureKey: "malformed-package",
+    featureClass: "unsupported-fatal",
+    message: input.issue.message,
+    details: {
+      stage: "package",
+      reason: input.issue.reason,
+      diagnosticsToken: createCorruptPackageDiagnosticsToken(input.issue),
+    },
+  } satisfies CompatibilityFeatureEntry;
+
+  const diagnostics = createDiagnostics({
+    featureEntries: [featureEntry],
+    warnings: [],
+    errors: [fatalError],
+  });
+
+  return createReadOnlyDiagnosticsResult(featureEntry, diagnostics, fatalError);
+}
+
+export function createValidationImportDiagnostics(input: {
+  message: string;
+  source?: EditorError["source"];
+  details?: Record<string, unknown>;
+}): ImportDiagnosticsResult {
+  const diagnosticsToken = createImportDiagnosticsToken("validation", input.message);
+  const fatalError: EditorError = {
+    errorId: `error:validation_failed:${diagnosticsToken}`,
+    code: "validation_failed",
+    message: input.message,
+    isFatal: true,
+    source: input.source ?? "validation",
+    details: {
+      stage: "validation",
+      diagnosticsToken,
+      ...(input.details ?? {}),
+    },
+  };
+  const featureEntry = {
+    featureEntryId: `feature:${fatalError.errorId}`,
+    featureKey: "openxml-validation",
+    featureClass: "unsupported-fatal",
+    message: input.message,
+    details: {
+      stage: "validation",
+      diagnosticsToken,
+    },
+  } satisfies CompatibilityFeatureEntry;
+  const diagnostics = createDiagnostics({
+    featureEntries: [featureEntry],
+    warnings: [],
+    errors: [fatalError],
+  });
+
+  return createReadOnlyDiagnosticsResult(featureEntry, diagnostics, fatalError);
+}
+
+export function getImportFailureStage(error: Pick<EditorError, "code" | "details">): ImportFailureStage {
+  if (error.code === "package_corrupt") {
+    return "package";
+  }
+
+  const stage = error.details?.stage;
+  return stage === "package" ? "package" : "validation";
+}
+
+function createReadOnlyDiagnosticsResult(
+  featureEntry: CompatibilityFeatureEntry,
+  diagnostics: CompatibilityDiagnostics,
+  fatalError: EditorError,
+): ImportDiagnosticsResult {
+  if (!diagnosticsBlockExport(diagnostics, true)) {
+    throw new Error("Import diagnostics must conservatively block export.");
+  }
+
+  return {
+    mode: "read-only-diagnostics",
+    readOnly: true,
+    blockExport: true,
+    fatalError,
+    diagnostics,
+    featureEntry,
+  };
+}
+
+function createImportDiagnosticsToken(stage: ImportFailureStage, message: string): string {
+  let hash = 2166136261;
+  const text = `${stage}:${message}`;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+
+  return `${stage}-${hash.toString(16).padStart(8, "0")}`;
+}