@beyondwork/docx-react-component 1.0.1 → 1.0.3

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
+  };
+}