outcome-cli 1.0.0

package/src/modules/omnibridge/__tests__/triangulation-engine.property.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Property-Based Tests for Triangulation Engine
+ *
+ * These tests validate the correctness properties defined in the design document.
+ * Each property test runs minimum 100 iterations with randomly generated inputs.
+ *
+ * Requirements: 2.1, 2.2, 2.4, 2.5, 2.6
+ */
+
+import { describe, test, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { TriangulationEngine } from '../core/triangulation-engine.js';
+import type {
+  IntentDocument,
+  IntentElement,
+  AnchorSet,
+  SpatialAnchor,
+  SemanticAnchor,
+  FunctionalAnchor,
+} from '../core/types.js';
+
+const engine = new TriangulationEngine();
+
+// =============================================================================
+// Arbitraries (Test Data Generators)
+// =============================================================================
+
+/**
+ * Generate a valid Intent Element
+ */
+const intentElementArb: fc.Arbitrary<IntentElement> = fc.record({
+  intentId: fc.constantFrom(
+    'ACTION_ID:SUBMIT',
+    'ACTION_ID:LOGIN',
+    'ACTION_ID:SIGNUP',
+    'ACTION_ID:SEARCH',
+    'ACTION_ID:CANCEL',
+    'INPUT_ID:EMAIL_INPUT',
+    'INPUT_ID:PASSWORD_INPUT',
+    'INPUT_ID:NAME_INPUT',
+    'INPUT_ID:SEARCH',
+    'NAV_ID:HOME',
+    'NAV_ID:PROFILE',
+    'NAV_ID:SETTINGS',
+    'NAV_ID:NAVIGATION',
+    'DISPLAY_ID:HEADING',
+    'DISPLAY_ID:ARTICLE',
+    'DISPLAY_ID:SECTION'
+  ),
+  role: fc.constantFrom('action', 'input', 'display', 'navigation') as fc.Arbitrary<'action' | 'input' | 'display' | 'navigation'>,
+  label: fc.lorem({ maxCount: 5 }),
+  ariaRole: fc.option(fc.constantFrom('button', 'link', 'textbox', 'navigation', 'main', 'banner', 'contentinfo'), { nil: undefined }),
+  contextHints: fc.array(fc.lorem({ maxCount: 3 }), { minLength: 0, maxLength: 3 }),
+  tagName: fc.constantFrom('button', 'a', 'input', 'div', 'nav', 'header', 'footer', 'main', 'section', 'article'),
+});
+
+/**
+ * Generate a valid Intent Document with multiple elements
+ */
+const intentDocumentArb: fc.Arbitrary<IntentDocument> = fc.record({
+  elements: fc.array(intentElementArb, { minLength: 1, maxLength: 20 }),
+  forms: fc.constant([]),
+  navigation: fc.constant({ primaryLinks: [], breadcrumbs: undefined }),
+  buildTimeMs: fc.double({ min: 1, max: 100 }),
+  tokenReduction: fc.double({ min: 80, max: 99 }),
+  sourceUrl: fc.webUrl(),
+  createdAt: fc.integer({ min: 1700000000000, max: 1800000000000 }),
+});
+
+/**
+ * Generate a Spatial Anchor
+ */
+const spatialAnchorArb: fc.Arbitrary<SpatialAnchor> = fc.record({
+  region: fc.constantFrom('header', 'main', 'sidebar', 'footer') as fc.Arbitrary<'header' | 'main' | 'sidebar' | 'footer'>,
+  relativePosition: fc.record({
+    x: fc.double({ min: 0, max: 1 }),
+    y: fc.double({ min: 0, max: 1 }),
+  }),
+  nearbyLandmarks: fc.array(fc.constantFrom(
+    'NAV_ID:HOME',
+    'NAV_ID:NAVIGATION',
+    'ACTION_ID:SEARCH',
+    'ACTION_ID:LOGIN'
+  ), { minLength: 0, maxLength: 5 }),
+});
+
+/**
+ * Generate a Semantic Anchor
+ */
+const semanticAnchorArb: fc.Arbitrary<SemanticAnchor> = fc.record({
+  intentId: fc.constantFrom(
+    'ACTION_ID:SUBMIT',
+    'ACTION_ID:LOGIN',
+    'INPUT_ID:EMAIL_INPUT',
+    'NAV_ID:HOME'
+  ),
+  labels: fc.array(fc.lorem({ maxCount: 3 }), { minLength: 1, maxLength: 5 }),
+  ariaRoles: fc.array(fc.constantFrom('button', 'link', 'textbox'), { minLength: 0, maxLength: 2 }),
+  textContent: fc.lorem({ maxCount: 5 }),
+});
+
+/**
+ * Generate a Functional Anchor
+ */
+const functionalAnchorArb: fc.Arbitrary<FunctionalAnchor> = fc.record({
+  eventTypes: fc.array(fc.constantFrom('click', 'input', 'change', 'focus', 'blur', 'submit'), { minLength: 1, maxLength: 4 }),
+  formTarget: fc.option(fc.constant('form'), { nil: undefined }),
+  navigationTarget: fc.option(fc.constantFrom('NAV_ID:HOME', 'NAV_ID:PROFILE'), { nil: undefined }),
+});
+
+/**
+ * Generate a complete AnchorSet
+ */
+const anchorSetArb: fc.Arbitrary<AnchorSet> = fc.record({
+  spatial: spatialAnchorArb,
+  semantic: semanticAnchorArb,
+  functional: functionalAnchorArb,
+});
+
+// =============================================================================
+// Property Tests
+// =============================================================================
+
+describe('Triangulation Engine Property Tests', () => {
+  /**
+   * **Feature: omnibridge, Property 4: Three-Anchor Storage**
+   * **Validates: Requirements 2.1**
+   *
+   * For any element stored by the Triangulation_Engine, the AnchorSet
+   * SHALL contain all three anchor types: Spatial, Semantic, and Functional.
+   */
+  test('Property 4: Three-Anchor Storage - all elements have all three anchor types', () => {
+    fc.assert(
+      fc.property(intentDocumentArb, (document) => {
+        // For each element in the document
+        for (let i = 0; i < document.elements.length; i++) {
+          const element = document.elements[i];
+          const anchors = engine.storeAnchors(element, document, i);
+
+          // Verify all three anchor types exist
+          expect(anchors).toHaveProperty('spatial');
+          expect(anchors).toHaveProperty('semantic');
+          expect(anchors).toHaveProperty('functional');
+
+          // Verify Spatial anchor has required properties
+          expect(anchors.spatial).toHaveProperty('region');
+          expect(anchors.spatial).toHaveProperty('relativePosition');
+          expect(anchors.spatial).toHaveProperty('nearbyLandmarks');
+          expect(['header', 'main', 'sidebar', 'footer']).toContain(anchors.spatial.region);
+          expect(anchors.spatial.relativePosition.x).toBeGreaterThanOrEqual(0);
+          expect(anchors.spatial.relativePosition.x).toBeLessThanOrEqual(1);
+          expect(anchors.spatial.relativePosition.y).toBeGreaterThanOrEqual(0);
+          expect(anchors.spatial.relativePosition.y).toBeLessThanOrEqual(1);
+          expect(Array.isArray(anchors.spatial.nearbyLandmarks)).toBe(true);
+
+          // Verify Semantic anchor has required properties
+          expect(anchors.semantic).toHaveProperty('intentId');
+          expect(anchors.semantic).toHaveProperty('labels');
+          expect(anchors.semantic).toHaveProperty('ariaRoles');
+          expect(anchors.semantic).toHaveProperty('textContent');
+          expect(typeof anchors.semantic.intentId).toBe('string');
+          expect(Array.isArray(anchors.semantic.labels)).toBe(true);
+          expect(Array.isArray(anchors.semantic.ariaRoles)).toBe(true);
+
+          // Verify Functional anchor has required properties
+          expect(anchors.functional).toHaveProperty('eventTypes');
+          expect(Array.isArray(anchors.functional.eventTypes)).toBe(true);
+        }
+
+        return true;
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+
+  /**
+   * **Feature: omnibridge, Property 5: Two-of-Three Healing**
+   * **Validates: Requirements 2.2**
+   *
+   * For any UI change where at least 2 of 3 anchors match, the Triangulation_Engine
+   * SHALL successfully locate the element and return `found: true`.
+   */
+  test('Property 5: Two-of-Three Healing - elements found when 2+ anchors match', () => {
+    fc.assert(
+      fc.property(intentDocumentArb, (document) => {
+        // Skip if document has no elements
+        if (document.elements.length === 0) return true;
+
+        // Pick a random element and store its anchors
+        const elementIndex = Math.floor(Math.random() * document.elements.length);
+        const element = document.elements[elementIndex];
+        const anchors = engine.storeAnchors(element, document, elementIndex);
+
+        // Try to locate the same element in the same document
+        // This should always succeed with 3/3 anchors matching
+        const result = engine.locate(anchors, document);
+
+        // When searching for an element in the same document, it should be found
+        // with high confidence (all 3 anchors should match)
+        expect(result.found).toBe(true);
+        expect(result.matchedAnchors).toBeGreaterThanOrEqual(2);
+
+        return true;
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  /**
+   * **Feature: omnibridge, Property 6: Confidence Threshold Alerting**
+   * **Validates: Requirements 2.4, 2.5**
+   *
+   * For any element identification with confidence below 70%, the result
+   * SHALL include `flaggedForReview: true`.
+   */
+  test('Property 6: Confidence Threshold Alerting - low confidence flagged for review', () => {
+    fc.assert(
+      fc.property(intentDocumentArb, anchorSetArb, (document, randomAnchors) => {
+        // Try to locate using random anchors (likely won't match well)
+        const result = engine.locate(randomAnchors, document);
+
+        // If confidence is below 70%, it should be flagged for review
+        if (result.confidence < 0.7) {
+          expect(result.flaggedForReview).toBe(true);
+        }
+
+        // If confidence is 70% or above, it should NOT be flagged
+        if (result.confidence >= 0.7) {
+          expect(result.flaggedForReview).toBe(false);
+        }
+
+        return true;
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  /**
+   * **Feature: omnibridge, Property 7: Schema Drift Detection**
+   * **Validates: Requirements 2.6**
+   *
+   * For any element lookup where all three anchors fail to match, the
+   * Triangulation_Engine SHALL return an error with `type: 'schema_drift'`.
+   */
+  test('Property 7: Schema Drift Detection - returns schema_drift when all anchors fail', () => {
+    fc.assert(
+      fc.property(intentDocumentArb, (document) => {
+        // Create anchors that definitely won't match anything in the document
+        const unmatchableAnchors: AnchorSet = {
+          spatial: {
+            region: 'sidebar', // Unlikely region
+            relativePosition: { x: 0.99, y: 0.99 },
+            nearbyLandmarks: ['NONEXISTENT_ID:FAKE_ELEMENT', 'NONEXISTENT_ID:ANOTHER_FAKE'],
+          },
+          semantic: {
+            intentId: 'NONEXISTENT_ID:COMPLETELY_FAKE_ELEMENT_THAT_DOES_NOT_EXIST',
+            labels: ['xyzzy_nonexistent_label_12345', 'plugh_fake_label_67890'],
+            ariaRoles: ['nonexistent_role'],
+            textContent: 'xyzzy_plugh_nonexistent_text_content_that_will_never_match',
+          },
+          functional: {
+            eventTypes: ['nonexistent_event_type'],
+            formTarget: 'nonexistent_form_target',
+            navigationTarget: 'NONEXISTENT_ID:FAKE_NAV_TARGET',
+          },
+        };
+
+        const result = engine.locate(unmatchableAnchors, document);
+        const schemaDriftError = engine.detectSchemaDrift(unmatchableAnchors, document);
+
+        // If no anchors matched, we should get a schema_drift error
+        if (result.matchedAnchors === 0) {
+          expect(schemaDriftError).not.toBeNull();
+          if (schemaDriftError && schemaDriftError.type === 'schema_drift') {
+            expect(schemaDriftError.type).toBe('schema_drift');
+            expect(typeof schemaDriftError.details).toBe('string');
+            expect(schemaDriftError.details.length).toBeGreaterThan(0);
+          }
+        }
+
+        // If element was found (some anchors matched), no schema drift
+        if (result.found) {
+          expect(schemaDriftError).toBeNull();
+        }
+
+        return true;
+      }),
+      { numRuns: 100 }
+    );
+  });
+});