@beyondwork/docx-react-component 1.0.0

package/test/validation/compatibility-report.test.ts

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+
+import {
+  COMPATIBILITY_FEATURE_KEYS,
+  createCompatibilityReport,
+  mergeCompatibilityReports,
+  summarizeCompatibilityReport,
+} from "../../src/validation/compatibility-report.ts";
+import {
+  COMPATIBILITY_FEATURE_CLASSES,
+  collectWarningIds,
+  createDiagnostics,
+  diagnosticsBlockExport,
+  isCompatibilityFeatureClass,
+} from "../../src/validation/diagnostics.ts";
+
+const FIXTURE_MANIFEST_PATH = new URL(
+  "../fixtures/docx/fixtures.manifest.json",
+  import.meta.url,
+);
+
+test("compatibility report exposes the frozen version and conservative blocking", () => {
+  const report = createCompatibilityReport({
+    generatedAt: "2026-03-26T00:00:00.000Z",
+    featureEntries: [
+      {
+        featureEntryId: "feature:unsupported",
+        featureKey: "unknown-ooxml",
+        featureClass: "unsupported-fatal",
+        message: "Malformed OOXML prevents safe preservation.",
+      },
+    ],
+    warnings: [
+      {
+        warningId: "warning:locked",
+        code: "unsupported_ooxml_locked",
+        severity: "warning",
+        message: "Unsupported OOXML is preserved and locked.",
+        source: "validation",
+        featureEntryId: "feature:unsupported",
+      },
+    ],
+    errors: [],
+  });
+
+  assert.equal(report.reportVersion, "compatibility-report/1");
+  assert.equal(report.blockExport, true);
+  assert.deepEqual(collectWarningIds(report.warnings), ["warning:locked"]);
+});
+
+test("diagnostics helpers summarize feature classes without expanding the taxonomy", () => {
+  const report = createCompatibilityReport({
+    generatedAt: "2026-03-26T00:00:00.000Z",
+    featureEntries: [
+      {
+        featureEntryId: "feature:supported",
+        featureKey: "paragraphs",
+        featureClass: "supported-roundtrip",
+        message: "Paragraphs are within the supported editing baseline.",
+      },
+      {
+        featureEntryId: "feature:preserved",
+        featureKey: "sections",
+        featureClass: "preserve-only",
+        message: "Sections remain preserved outside editable scope.",
+      },
+    ],
+    errors: [],
+    warnings: [],
+  });
+
+  assert.deepEqual(COMPATIBILITY_FEATURE_CLASSES, [
+    "supported-roundtrip",
+    "preserve-only",
+    "unsupported-fatal",
+  ]);
+  assert.ok(COMPATIBILITY_FEATURE_KEYS.includes("paragraphs"));
+  assert.equal(isCompatibilityFeatureClass("preserve-only"), true);
+  assert.equal(isCompatibilityFeatureClass("supported-import-only"), false);
+
+  assert.deepEqual(summarizeCompatibilityReport(report), {
+    generatedAt: "2026-03-26T00:00:00.000Z",
+    blockExport: false,
+    featureClassCounts: {
+      "supported-roundtrip": 1,
+      "preserve-only": 1,
+      "unsupported-fatal": 0,
+    },
+    warningCount: 0,
+    errorCount: 0,
+  });
+});
+
+test("merged reports deduplicate repeated diagnostics and preserve blocking state", () => {
+  const warning = {
+    warningId: "warning:preserved",
+    code: "unsupported_ooxml_preserved" as const,
+    severity: "info" as const,
+    message: "Preserve-only OOXML remains attached for export.",
+    source: "preservation" as const,
+    featureEntryId: "feature:preserved",
+  };
+
+  const blockingReport = createCompatibilityReport({
+    generatedAt: "2026-03-26T00:00:00.000Z",
+    featureEntries: [
+      {
+        featureEntryId: "feature:preserved",
+        featureKey: "custom-xml",
+        featureClass: "preserve-only",
+        message: "Custom XML is preserved without editable semantics.",
+      },
+    ],
+    warnings: [warning],
+    errors: [
+      {
+        errorId: "error:package",
+        code: "package_corrupt",
+        message: "Broken relationship graph blocks safe export.",
+        isFatal: false,
+        source: "validation",
+      },
+    ],
+  });
+
+  const merged = mergeCompatibilityReports(
+    [
+      blockingReport,
+      createCompatibilityReport({
+        generatedAt: "2026-03-26T00:01:00.000Z",
+        featureEntries: blockingReport.featureEntries,
+        warnings: [warning],
+        errors: [],
+      }),
+    ],
+    {
+      generatedAt: "2026-03-26T00:02:00.000Z",
+    },
+  );
+
+  assert.equal(merged.blockExport, true);
+  assert.equal(merged.featureEntries.length, 1);
+  assert.equal(merged.warnings.length, 1);
+  assert.equal(merged.errors.length, 1);
+});
+
+test("diagnosticsBlockExport accepts explicit gating without pretending semantic proof", () => {
+  const diagnostics = createDiagnostics({
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+  });
+
+  assert.equal(diagnosticsBlockExport(diagnostics, false), false);
+  assert.equal(diagnosticsBlockExport(diagnostics, true), true);
+});
+
+test("fixture manifest stays machine-readable and marks the corpus as contract-frozen", () => {
+  const manifest = JSON.parse(readFileSync(FIXTURE_MANIFEST_PATH, "utf8")) as {
+    manifestVersion: string;
+    corpusStatus: string;
+    fixtures: Array<{
+      fixtureId: string;
+      featureClassFocus: string;
+      artifactStatus: string;
+      proofBearingWaves: number[];
+    }>;
+  };
+
+  assert.equal(manifest.manifestVersion, "docx-fixtures/1");
+  assert.equal(manifest.corpusStatus, "contract-frozen");
+  assert.equal(manifest.fixtures.length, 21);
+  assert.deepEqual(
+    manifest.fixtures.slice(0, 3).map((fixture) => fixture.fixtureId),
+    ["F01", "F02", "F03"],
+  );
+  assert.deepEqual(manifest.fixtures.at(-1)?.proofBearingWaves, [7, 10]);
+  assert.equal(manifest.fixtures[0]?.artifactStatus, "baseline-proved");
+  assert.equal(manifest.fixtures[1]?.artifactStatus, "baseline-proved");
+  assert.ok(
+    manifest.fixtures.every(
+      (fixture) =>
+        isCompatibilityFeatureClass(fixture.featureClassFocus) &&
+        ["planned", "baseline-proved"].includes(fixture.artifactStatus),
+    ),
+  );
+});

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

@@ -0,0 +1,282 @@
+/**
+ * Tests for Low-Priority Word Surfaces validation
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  LowPriorityWordSurface,
+  SupportStance,
+  LOW_PRIORITY_WORD_SURFACE_POLICIES,
+  getLowPrioritySurfacePolicy,
+  isSurfaceEditingSupported,
+  shouldBlockImport,
+  getWarningLevel,
+  generateCompatibilityEntries,
+  generatePolicySummary
+} from '../../src/validation/low-priority-word-surfaces.js';
+
+describe('Low-Priority Word Surfaces', () => {
+  describe('Policy Matrix Completeness', () => {
+    it('should define policies for all expected surface types', () => {
+      const expectedSurfaces: 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'
+      ];
+      
+      const definedSurfaces = LOW_PRIORITY_WORD_SURFACE_POLICIES.map(p => p.surface);
+      
+      for (const surface of expectedSurfaces) {
+        assert.ok(definedSurfaces.includes(surface));
+      }
+    });
+    
+    it('should have unique surface definitions', () => {
+      const surfaces = LOW_PRIORITY_WORD_SURFACE_POLICIES.map(p => p.surface);
+      const uniqueSurfaces = [...new Set(surfaces)];
+      
+      assert.equal(surfaces.length, uniqueSurfaces.length);
+    });
+    
+    it('should have valid stance values', () => {
+      const validStances: SupportStance[] = [
+        'preserve-only',
+        'blocked',
+        'unsupported-fatal',
+        'placeholder-only'
+      ];
+      
+      for (const policy of LOW_PRIORITY_WORD_SURFACE_POLICIES) {
+        assert.ok(validStances.includes(policy.stance));
+      }
+    });
+  });
+  
+  describe('Policy Lookup', () => {
+    it('should return policy for existing surfaces', () => {
+      const policy = getLowPrioritySurfacePolicy('ole-objects');
+      
+      assert.ok(policy != null);
+      assert.equal(policy.surface, 'ole-objects');
+      assert.ok(policy.stance != null);
+      assert.ok(policy.rationale != null);
+    });
+    
+    it('should throw error for non-existent surfaces', () => {
+      assert.throws(() => {
+        // @ts-expect-error - testing invalid surface
+        getLowPrioritySurfacePolicy('non-existent-surface');
+      }, { message: 'No policy defined for surface: non-existent-surface' });
+    });
+  });
+  
+  describe('Security-Critical Surfaces', () => {
+    it('should block macros for security', () => {
+      const policy = getLowPrioritySurfacePolicy('macros');
+      
+      assert.equal(policy.stance, 'blocked');
+      assert.equal(policy.userVisibleBehavior.onImport, 'block');
+      assert.equal(policy.userVisibleBehavior.warningLevel, 'warning');
+      assert.equal(policy.wordCompatibility.roundTripSafe, false);
+    });
+    
+    it('should block VBA scripts for security', () => {
+      const policy = getLowPrioritySurfacePolicy('vba-scripts');
+      
+      assert.equal(policy.stance, 'blocked');
+      assert.equal(policy.userVisibleBehavior.onImport, 'block');
+      assert.equal(policy.userVisibleBehavior.warningLevel, 'warning');
+    });
+    
+    it('should block ActiveX controls for security', () => {
+      const policy = getLowPrioritySurfacePolicy('activex-controls');
+      
+      assert.equal(policy.stance, 'blocked');
+      assert.equal(policy.userVisibleBehavior.onImport, 'block');
+      assert.equal(policy.userVisibleBehavior.warningLevel, 'error');
+    });
+    
+    it('should block external data connections', () => {
+      const policy = getLowPrioritySurfacePolicy('external-data-connections');
+      
+      assert.equal(policy.stance, 'blocked');
+      assert.equal(policy.userVisibleBehavior.onImport, 'block');
+      assert.equal(policy.userVisibleBehavior.warningLevel, 'warning');
+    });
+  });
+  
+  describe('Preserve-Only Surfaces', () => {
+    it('should preserve OLE objects safely', () => {
+      const policy = getLowPrioritySurfacePolicy('ole-objects');
+      
+      assert.equal(policy.stance, 'preserve-only');
+      assert.equal(policy.userVisibleBehavior.onImport, 'preserve');
+      assert.equal(policy.userVisibleBehavior.onEdit, 'locked');
+      assert.equal(policy.userVisibleBehavior.onExport, 'preserve');
+      assert.equal(policy.wordCompatibility.roundTripSafe, true);
+    });
+    
+    it('should preserve embedded objects', () => {
+      const policy = getLowPrioritySurfacePolicy('embedded-objects');
+      
+      assert.equal(policy.stance, 'preserve-only');
+      assert.equal(policy.userVisibleBehavior.onEdit, 'locked');
+      assert.equal(policy.wordCompatibility.roundTripSafe, true);
+    });
+    
+    it('should preserve mail merge fields', () => {
+      const policy = getLowPrioritySurfacePolicy('mail-merge-fields');
+      
+      assert.equal(policy.stance, 'preserve-only');
+      assert.ok(policy.fixtureEvidence.includes('F17'));
+      assert.equal(policy.wordCompatibility.roundTripSafe, true);
+    });
+    
+    it('should preserve legacy form fields', () => {
+      const policy = getLowPrioritySurfacePolicy('legacy-form-fields');
+      
+      assert.equal(policy.stance, 'preserve-only');
+      assert.ok(policy.fixtureEvidence.includes('F18'));
+    });
+  });
+  
+  describe('Helper Functions', () => {
+    it('should correctly identify non-editable surfaces', () => {
+      assert.equal(isSurfaceEditingSupported('ole-objects'), false);
+      assert.equal(isSurfaceEditingSupported('macros'), false);
+      assert.equal(isSurfaceEditingSupported('embedded-objects'), false);
+    });
+    
+    it('should identify import-blocking surfaces', () => {
+      assert.equal(shouldBlockImport('macros'), true);
+      assert.equal(shouldBlockImport('vba-scripts'), true);
+      assert.equal(shouldBlockImport('activex-controls'), true);
+      assert.equal(shouldBlockImport('advanced-word-automation'), true);
+      
+      assert.equal(shouldBlockImport('ole-objects'), false);
+      assert.equal(shouldBlockImport('embedded-objects'), false);
+    });
+    
+    it('should return correct warning levels', () => {
+      assert.equal(getWarningLevel('macros'), 'warning');
+      assert.equal(getWarningLevel('activex-controls'), 'error');
+      assert.equal(getWarningLevel('ole-objects'), 'info');
+      assert.equal(getWarningLevel('custom-ribbons'), 'none');
+    });
+  });
+  
+  describe('Compatibility Entries', () => {
+    it('should generate compatibility entries for detected surfaces', () => {
+      const detectedSurfaces: LowPriorityWordSurface[] = [
+        'ole-objects',
+        'macros',
+        'embedded-objects'
+      ];
+      
+      const entries = generateCompatibilityEntries(detectedSurfaces);
+      
+      assert.equal(entries.length, 3);
+      
+      const oleEntry = entries.find(e => e.surface === 'ole-objects');
+      assert.ok(oleEntry != null);
+      assert.equal(oleEntry?.stance, 'preserve-only');
+      assert.equal(oleEntry?.userImpact, 'locked');
+      assert.equal(oleEntry?.wordCompatible, true);
+      
+      const macroEntry = entries.find(e => e.surface === 'macros');
+      assert.ok(macroEntry != null);
+      assert.equal(macroEntry?.stance, 'blocked');
+      assert.equal(macroEntry?.userImpact, 'blocked');
+      assert.equal(macroEntry?.wordCompatible, false);
+    });
+    
+    it('should provide appropriate recommendations', () => {
+      const entries = generateCompatibilityEntries(['ole-objects', 'macros']);
+      
+      const oleEntry = entries.find(e => e.surface === 'ole-objects');
+      assert.ok(oleEntry?.recommendation.includes('preserved but cannot be edited'));
+      
+      const macroEntry = entries.find(e => e.surface === 'macros');
+      assert.ok(macroEntry?.recommendation.includes('blocked for security reasons'));
+    });
+  });
+  
+  describe('Policy Summary', () => {
+    it('should generate accurate summary statistics', () => {
+      const summary = generatePolicySummary();
+      
+      assert.equal(summary.totalSurfaces, LOW_PRIORITY_WORD_SURFACE_POLICIES.length);
+      assert.ok(summary.preserveOnlyCount > 0);
+      assert.ok(summary.blockedCount > 0);
+      assert.ok(summary.wordCompatibleCount > 0);
+      
+      // Verify totals add up
+      assert.ok(summary.preserveOnlyCount + 
+        summary.blockedCount + 
+        summary.unsupportedFatalCount <= summary.totalSurfaces);
+    });
+    
+    it('should count surfaces with warnings', () => {
+      const summary = generatePolicySummary();
+      const policiesWithWarnings = LOW_PRIORITY_WORD_SURFACE_POLICIES.filter(
+        p => p.userVisibleBehavior.warningLevel !== 'none'
+      ).length;
+      
+      assert.equal(summary.surfacesWithWarnings, policiesWithWarnings);
+    });
+  });
+  
+  describe('Fixture Evidence', () => {
+    it('should reference appropriate fixtures for preserve-only surfaces', () => {
+      const olePolicy = getLowPrioritySurfacePolicy('ole-objects');
+      assert.ok(olePolicy.fixtureEvidence.includes('F20'));
+      
+      const mailMergePolicy = getLowPrioritySurfacePolicy('mail-merge-fields');
+      assert.ok(mailMergePolicy.fixtureEvidence.includes('F17'));
+      
+      const formFieldsPolicy = getLowPrioritySurfacePolicy('legacy-form-fields');
+      assert.ok(formFieldsPolicy.fixtureEvidence.includes('F18'));
+    });
+    
+    it('should not claim fixture evidence for blocked surfaces', () => {
+      const macroPolicy = getLowPrioritySurfacePolicy('macros');
+      assert.deepEqual(macroPolicy.fixtureEvidence, []);
+      
+      const vbaPolicy = getLowPrioritySurfacePolicy('vba-scripts');
+      assert.deepEqual(vbaPolicy.fixtureEvidence, []);
+    });
+  });
+  
+  describe('Word Compatibility', () => {
+    it('should mark preserve-only surfaces as Word compatible', () => {
+      const preserveOnlySurfaces = LOW_PRIORITY_WORD_SURFACE_POLICIES
+        .filter(p => p.stance === 'preserve-only');
+      
+      for (const policy of preserveOnlySurfaces) {
+        assert.equal(policy.wordCompatibility.roundTripSafe, true);
+        assert.equal(policy.wordCompatibility.wordReopenBehavior, 'normal');
+      }
+    });
+    
+    it('should mark blocked surfaces appropriately for Word compatibility', () => {
+      const blockedSurfaces = LOW_PRIORITY_WORD_SURFACE_POLICIES
+        .filter(p => p.stance === 'blocked');
+      
+      for (const policy of blockedSurfaces) {
+        // Blocked surfaces may or may not be Word compatible depending on
+        // whether they are stripped or preserved
+        assert.ok(['normal', 'blocked'].includes(policy.wordCompatibility.wordReopenBehavior));
+      }
+    });
+  });
+});

package/test/validation/malformed-doc.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  classifyCorruptPackageError,
+  createBrokenRelationshipIssue,
+  createCorruptPackageError,
+  createMissingPartIssue,
+} from "../../src/io/opc/corrupt-package.ts";
+import { createReadOnlyDiagnosticsRuntime } from "../../src/runtime/read-only-diagnostics-runtime.ts";
+import {
+  createPackageImportDiagnostics,
+  createValidationImportDiagnostics,
+  getImportFailureStage,
+} from "../../src/validation/import-diagnostics.ts";
+
+test("corrupt package helpers classify ZIP, relationship, and missing-part failures conservatively", () => {
+  assert.equal(
+    classifyCorruptPackageError(
+      new Error("Invalid ZIP archive: end of central directory not found."),
+    ).reason,
+    "zip-structure",
+  );
+  assert.equal(
+    classifyCorruptPackageError(
+      new Error("DOCX part /word/document.xml has unresolved relationship rId7 targeting /word/header1.xml."),
+    ).reason,
+    "broken-relationship-graph",
+  );
+  assert.equal(createMissingPartIssue("/word/document.xml").reason, "main-document-missing");
+});
+
+test("package diagnostics stay distinct from validation diagnostics", () => {
+  const packageDiagnostics = createPackageImportDiagnostics({
+    issue: createBrokenRelationshipIssue({
+      relationshipSourcePath: "/word/document.xml",
+      relationshipId: "rIdHeader1",
+      targetPartPath: "/word/header1.xml",
+    }),
+  });
+  const validationDiagnostics = createValidationImportDiagnostics({
+    message: "Open XML validation failed for /word/document.xml.",
+  });
+
+  assert.equal(packageDiagnostics.mode, "read-only-diagnostics");
+  assert.equal(packageDiagnostics.blockExport, true);
+  assert.equal(packageDiagnostics.fatalError.code, "package_corrupt");
+  assert.equal(getImportFailureStage(packageDiagnostics.fatalError), "package");
+  assert.equal(packageDiagnostics.featureEntry.featureKey, "malformed-package");
+  assert.equal(packageDiagnostics.fatalError.details?.reason, "broken-relationship-graph");
+
+  assert.equal(validationDiagnostics.blockExport, true);
+  assert.equal(validationDiagnostics.fatalError.code, "validation_failed");
+  assert.equal(getImportFailureStage(validationDiagnostics.fatalError), "validation");
+  assert.equal(validationDiagnostics.featureEntry.featureKey, "openxml-validation");
+  assert.equal(validationDiagnostics.fatalError.details?.stage, "validation");
+});
+
+test("read-only diagnostics runtime blocks edit commands and export without fabricating editability", async () => {
+  const diagnostics = createPackageImportDiagnostics({
+    issue: createMissingPartIssue("/word/document.xml"),
+  });
+  const runtime = createReadOnlyDiagnosticsRuntime({
+    documentId: "broken-doc",
+    sourceLabel: "F21-malformed-broken-docx.docx",
+    editorBuild: "test",
+    generatedAt: "2026-03-26T00:00:00.000Z",
+    diagnostics,
+  });
+
+  const renderSnapshot = runtime.getRenderSnapshot();
+  const persistedSnapshot = runtime.getPersistedSnapshot();
+
+  assert.equal(renderSnapshot.readOnly, true);
+  assert.equal(renderSnapshot.commandState.readOnly, true);
+  assert.equal(renderSnapshot.compatibility.blockExport, true);
+  assert.equal(renderSnapshot.fatalError?.code, "package_corrupt");
+  assert.equal(renderSnapshot.compatibility.blockExportReasons.length, 1);
+
+  assert.equal(persistedSnapshot.compatibility.blockExport, true);
+  assert.equal(
+    persistedSnapshot.canonicalDocument.metadata.importMode,
+    "read-only-diagnostics",
+  );
+  assert.equal(
+    persistedSnapshot.canonicalDocument.diagnostics.errors[0]?.code,
+    "package_corrupt",
+  );
+
+  assert.throws(
+    () => runtime.dispatch({ type: "text.insert" }),
+    /read-only diagnostics mode/i,
+  );
+  await assert.rejects(
+    () => runtime.exportDocx(),
+    /read-only diagnostics mode/i,
+  );
+});
+
+test("corrupt package errors carry stable package-stage details", () => {
+  const error = createCorruptPackageError(
+    createBrokenRelationshipIssue({
+      relationshipSourcePath: "/word/document.xml",
+      relationshipId: "rId5",
+      targetPartPath: "/word/footer1.xml",
+    }),
+  );
+
+  assert.equal(error.code, "package_corrupt");
+  assert.equal(error.details?.stage, "package");
+  assert.equal(error.details?.relationshipId, "rId5");
+  assert.match(String(error.details?.diagnosticsToken), /^pkg-[0-9a-f]{8}$/u);
+});

package/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}