@beyondwork/docx-react-component 1.0.29 → 1.0.31

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")}`;
+}

package/src/validation/low-priority-word-surfaces.ts

@@ -0,0 +1,373 @@
+/**
+ * Low-Priority Word Surfaces Validation
+ * 
+ * This module defines the explicit bounded stance for Word surfaces that are
+ * intentionally de-prioritized in the current legal review editor scope.
+ * These include OLE objects, embedded objects, macros, and other complex
+ * Word features that are outside the core document editing workflow.
+ */
+
+/**
+ * Classification of low-priority Word surfaces based on legal review importance
+ * and technical complexity.
+ */
+export type LowPriorityWordSurface =
+  | 'ole-objects'
+  | 'embedded-objects' 
+  | 'macros'
+  | 'advanced-word-automation'
+  | 'custom-ribbons'
+  | 'word-addins'
+  | 'external-data-connections'
+  | 'mail-merge-fields'
+  | 'legacy-form-fields'
+  | 'activex-controls'
+  | 'vba-scripts'
+  | 'external-links';
+
+/**
+ * Support stance for each low-priority surface
+ */
+export type SupportStance = 
+  | 'preserve-only'      // Keep intact during round-trip, but no editing
+  | 'blocked'           // Explicitly blocked for security/complexity reasons  
+  | 'unsupported-fatal' // Causes import to fail
+  | 'placeholder-only'; // Render placeholder, preserve original
+
+/**
+ * Detailed policy for each low-priority Word surface
+ */
+export interface LowPrioritySurfacePolicy {
+  surface: LowPriorityWordSurface;
+  stance: SupportStance;
+  rationale: string;
+  fixtureEvidence?: string[];
+  userVisibleBehavior: {
+    onImport: 'preserve' | 'block' | 'fail' | 'placeholder';
+    onEdit: 'locked' | 'blocked' | 'unavailable';
+    onExport: 'preserve' | 'omit' | 'block';
+    warningLevel: 'none' | 'info' | 'warning' | 'error';
+  };
+  wordCompatibility: {
+    roundTripSafe: boolean;
+    wordReopenBehavior: 'normal' | 'repair-prompt' | 'blocked';
+  };
+}
+
+/**
+ * Complete policy matrix for all low-priority Word surfaces
+ */
+export const LOW_PRIORITY_WORD_SURFACE_POLICIES: LowPrioritySurfacePolicy[] = [
+  {
+    surface: 'ole-objects',
+    stance: 'preserve-only',
+    rationale: 'OLE objects are complex binary content that would require format-specific handling. Preservation maintains compatibility without security risks.',
+    fixtureEvidence: ['F20'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'locked',
+      onExport: 'preserve',
+      warningLevel: 'info'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'embedded-objects',
+    stance: 'preserve-only',
+    rationale: 'Embedded objects (Excel charts, PowerPoint slides) are preserved to maintain document integrity but not editable within the text editor scope.',
+    fixtureEvidence: ['F20'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'locked', 
+      onExport: 'preserve',
+      warningLevel: 'info'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'macros',
+    stance: 'blocked',
+    rationale: 'Macros pose security risks and are explicitly blocked. Legal document review workflows should not depend on executable code.',
+    fixtureEvidence: [],
+    userVisibleBehavior: {
+      onImport: 'block',
+      onEdit: 'blocked',
+      onExport: 'omit',
+      warningLevel: 'warning'
+    },
+    wordCompatibility: {
+      roundTripSafe: false,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'vba-scripts',
+    stance: 'blocked',
+    rationale: 'VBA scripts are executable code that poses security risks and is outside the scope of document review workflows.',
+    fixtureEvidence: [],
+    userVisibleBehavior: {
+      onImport: 'block',
+      onEdit: 'blocked', 
+      onExport: 'omit',
+      warningLevel: 'warning'
+    },
+    wordCompatibility: {
+      roundTripSafe: false,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'advanced-word-automation',
+    stance: 'unsupported-fatal',
+    rationale: 'Advanced automation features are complex and outside the legal review scope. Documents depending on them should use Word directly.',
+    fixtureEvidence: [],
+    userVisibleBehavior: {
+      onImport: 'fail',
+      onEdit: 'unavailable',
+      onExport: 'block',
+      warningLevel: 'error'
+    },
+    wordCompatibility: {
+      roundTripSafe: false,
+      wordReopenBehavior: 'blocked'
+    }
+  },
+  {
+    surface: 'custom-ribbons',
+    stance: 'preserve-only',
+    rationale: 'Custom ribbon definitions are UI customizations that can be preserved but are not relevant to document content editing.',
+    fixtureEvidence: ['F20'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'unavailable',
+      onExport: 'preserve', 
+      warningLevel: 'none'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'word-addins',
+    stance: 'preserve-only',
+    rationale: 'Add-in definitions are application-level customizations that can be preserved but are not editable within the document scope.',
+    fixtureEvidence: ['F20'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'unavailable',
+      onExport: 'preserve',
+      warningLevel: 'none'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'external-data-connections',
+    stance: 'blocked',
+    rationale: 'External data connections pose security risks and can create dependencies outside the document. Blocked for legal review workflows.',
+    fixtureEvidence: [],
+    userVisibleBehavior: {
+      onImport: 'block',
+      onEdit: 'blocked',
+      onExport: 'omit',
+      warningLevel: 'warning'
+    },
+    wordCompatibility: {
+      roundTripSafe: false,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'mail-merge-fields',
+    stance: 'preserve-only',
+    rationale: 'Mail merge fields can be preserved as static content but merge operations are outside the document editing scope.',
+    fixtureEvidence: ['F17'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'locked',
+      onExport: 'preserve',
+      warningLevel: 'info'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'legacy-form-fields',
+    stance: 'preserve-only',
+    rationale: 'Legacy form fields are preserved for compatibility but modern content controls (SDTs) are preferred for structured input.',
+    fixtureEvidence: ['F18'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'locked',
+      onExport: 'preserve',
+      warningLevel: 'info'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'activex-controls',
+    stance: 'blocked',
+    rationale: 'ActiveX controls are deprecated and pose security risks. Not appropriate for legal document workflows.',
+    fixtureEvidence: [],
+    userVisibleBehavior: {
+      onImport: 'block',
+      onEdit: 'blocked',
+      onExport: 'omit',
+      warningLevel: 'error'
+    },
+    wordCompatibility: {
+      roundTripSafe: false,
+      wordReopenBehavior: 'normal'
+    }
+  },
+  {
+    surface: 'external-links',
+    stance: 'preserve-only',
+    rationale: 'External links to files or resources outside the document are preserved but not resolved within the editor.',
+    fixtureEvidence: ['F20'],
+    userVisibleBehavior: {
+      onImport: 'preserve',
+      onEdit: 'locked',
+      onExport: 'preserve',
+      warningLevel: 'info'
+    },
+    wordCompatibility: {
+      roundTripSafe: true,
+      wordReopenBehavior: 'normal'
+    }
+  }
+];
+
+/**
+ * Get the policy for a specific low-priority surface
+ */
+export function getLowPrioritySurfacePolicy(surface: LowPriorityWordSurface): LowPrioritySurfacePolicy {
+  const policy = LOW_PRIORITY_WORD_SURFACE_POLICIES.find(p => p.surface === surface);
+  if (!policy) {
+    throw new Error(`No policy defined for surface: ${surface}`);
+  }
+  return policy;
+}
+
+/**
+ * Check if a surface is supported for editing (as opposed to preserve-only)
+ */
+export function isSurfaceEditingSupported(surface: LowPriorityWordSurface): boolean {
+  const policy = getLowPrioritySurfacePolicy(surface);
+  return policy.userVisibleBehavior.onEdit !== 'locked' && 
+         policy.userVisibleBehavior.onEdit !== 'blocked' &&
+         policy.userVisibleBehavior.onEdit !== 'unavailable';
+}
+
+/**
+ * Check if a surface should block document import
+ */
+export function shouldBlockImport(surface: LowPriorityWordSurface): boolean {
+  const policy = getLowPrioritySurfacePolicy(surface);
+  return policy.userVisibleBehavior.onImport === 'block' || 
+         policy.userVisibleBehavior.onImport === 'fail';
+}
+
+/**
+ * Get warning level for a detected surface
+ */
+export function getWarningLevel(surface: LowPriorityWordSurface): 'none' | 'info' | 'warning' | 'error' {
+  const policy = getLowPrioritySurfacePolicy(surface);
+  return policy.userVisibleBehavior.warningLevel;
+}
+
+/**
+ * Generate compatibility report entry for a low-priority surface
+ */
+export interface LowPrioritySurfaceCompatibilityEntry {
+  surface: LowPriorityWordSurface;
+  stance: SupportStance;
+  detected: boolean;
+  userImpact: 'none' | 'locked' | 'blocked' | 'preserved';
+  wordCompatible: boolean;
+  recommendation: string;
+}
+
+/**
+ * Generate compatibility entries for detected low-priority surfaces
+ */
+export function generateCompatibilityEntries(
+  detectedSurfaces: LowPriorityWordSurface[]
+): LowPrioritySurfaceCompatibilityEntry[] {
+  return detectedSurfaces.map(surface => {
+    const policy = getLowPrioritySurfacePolicy(surface);
+    
+    let userImpact: 'none' | 'locked' | 'blocked' | 'preserved';
+    let recommendation: string;
+    
+    switch (policy.stance) {
+      case 'preserve-only':
+        userImpact = 'locked';
+        recommendation = 'Content is preserved but cannot be edited within this editor. Use Microsoft Word for full editing capabilities.';
+        break;
+      case 'blocked':
+        userImpact = 'blocked';
+        recommendation = 'This content type is blocked for security reasons. Remove or replace before importing.';
+        break;
+      case 'unsupported-fatal':
+        userImpact = 'blocked';
+        recommendation = 'This document contains features that cannot be safely handled. Please use Microsoft Word directly.';
+        break;
+      case 'placeholder-only':
+        userImpact = 'preserved';
+        recommendation = 'Content is displayed as a placeholder. Original formatting preserved for export.';
+        break;
+    }
+    
+    return {
+      surface,
+      stance: policy.stance,
+      detected: true,
+      userImpact,
+      wordCompatible: policy.wordCompatibility.roundTripSafe,
+      recommendation
+    };
+  });
+}
+
+/**
+ * Summary statistics for low-priority surface handling
+ */
+export interface LowPrioritySurfaceSummary {
+  totalSurfaces: number;
+  preserveOnlyCount: number;
+  blockedCount: number;
+  unsupportedFatalCount: number;
+  wordCompatibleCount: number;
+  surfacesWithWarnings: number;
+}
+
+/**
+ * Generate summary statistics for the low-priority surface policy matrix
+ */
+export function generatePolicySummary(): LowPrioritySurfaceSummary {
+  const policies = LOW_PRIORITY_WORD_SURFACE_POLICIES;
+  
+  return {
+    totalSurfaces: policies.length,
+    preserveOnlyCount: policies.filter(p => p.stance === 'preserve-only').length,
+    blockedCount: policies.filter(p => p.stance === 'blocked').length,
+    unsupportedFatalCount: policies.filter(p => p.stance === 'unsupported-fatal').length,
+    wordCompatibleCount: policies.filter(p => p.wordCompatibility.roundTripSafe).length,
+    surfacesWithWarnings: policies.filter(p => p.userVisibleBehavior.warningLevel !== 'none').length
+  };
+}