@veraxhq/verax 0.2.0 → 0.3.0

package/src/verax/observe/observers/safety-observer.js

@@ -0,0 +1,82 @@
+/**
+ * PHASE 21.3 — Safety Observer
+ * 
+ * Responsibilities:
+ * - Network interception (cross-origin blocking, write method blocking)
+ * - NO file I/O
+ * - NO side effects outside its scope
+ */
+
+/**
+ * Setup network interception firewall
+ * 
+ * @param {ObserveContext} context - Observe context
+ * @returns {Promise<void>}
+ */
+export async function setupNetworkInterception(context) {
+  const { page, baseOrigin, safetyFlags, silenceTracker, blockedNetworkWrites, blockedCrossOrigin } = context;
+  const { allowWrites = false, allowCrossOrigin = false } = safetyFlags;
+
+  await page.route('**/*', (route) => {
+    const request = route.request();
+    const method = request.method();
+    const requestUrl = request.url();
+    const resourceType = request.resourceType();
+    
+    // Check cross-origin blocking (skip for file:// URLs)
+    if (!allowCrossOrigin && !requestUrl.startsWith('file://')) {
+      try {
+        const reqOrigin = new URL(requestUrl).origin;
+        if (reqOrigin !== baseOrigin) {
+          blockedCrossOrigin.push({
+            url: requestUrl,
+            origin: reqOrigin,
+            method,
+            resourceType,
+            timestamp: Date.now()
+          });
+          
+          silenceTracker.record({
+            scope: 'safety',
+            reason: 'cross_origin_blocked',
+            description: `Cross-origin request blocked: ${method} ${requestUrl}`,
+            context: { url: requestUrl, origin: reqOrigin, method, baseOrigin },
+            impact: 'request_blocked'
+          });
+          
+          return route.abort('blockedbyclient');
+        }
+      } catch (e) {
+        // Invalid URL, allow and let browser handle
+      }
+    }
+    
+    // Check write method blocking
+    if (!allowWrites && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      // Check if it's a GraphQL mutation (best-effort)
+      const isGraphQLMutation = requestUrl.includes('/graphql') && method === 'POST';
+      
+      blockedNetworkWrites.push({
+        url: requestUrl,
+        method,
+        resourceType,
+        isGraphQLMutation,
+        timestamp: Date.now()
+      });
+      
+      silenceTracker.record({
+        scope: 'safety',
+        reason: 'blocked_network_write',
+        description: `Network write blocked: ${method} ${requestUrl}${isGraphQLMutation ? ' (GraphQL mutation)' : ''}`,
+        context: { url: requestUrl, method, resourceType, isGraphQLMutation },
+        impact: 'write_blocked'
+      });
+      
+      return route.abort('blockedbyclient');
+    }
+    
+    // Allow request
+    route.continue();
+  });
+}
+

package/src/verax/observe/observers/ui-feedback-observer.js

@@ -0,0 +1,99 @@
+/**
+ * PHASE 21.3 — UI Feedback Observer
+ * 
+ * Responsibilities:
+ * - DOM mutation observation
+ * - Loading / disabled / feedback signals
+ * - UI settle signals (NO adaptive waiting - that's in settle.js)
+ * 
+ * NO file I/O
+ * NO side effects outside its scope
+ */
+
+import { UISignalSensor } from '../ui-signal-sensor.js';
+import { captureDomSignature } from '../dom-signature.js';
+
+/**
+ * Observe UI feedback and DOM state on current page
+ * 
+ * @param {ObserveContext} context - Observe context
+ * @param {RunState} runState - Current run state
+ * @returns {Promise<Array<Observation>>} Array of UI feedback observations
+ */
+export async function observe(context, runState) {
+  const { page, currentUrl, timestamp } = context;
+  const observations = [];
+  
+  try {
+    // Capture current UI signals
+    const uiSignalSensor = new UISignalSensor();
+    const uiSignals = await uiSignalSensor.snapshot(page);
+    
+    // Capture DOM signature for mutation tracking
+    const domSignature = await captureDomSignature(page);
+    
+    // Create observation for UI signals
+    observations.push({
+      type: 'ui_feedback',
+      scope: 'page',
+      data: {
+        hasLoadingIndicator: uiSignals.hasLoadingIndicator,
+        hasDialog: uiSignals.hasDialog,
+        hasErrorSignal: uiSignals.hasErrorSignal,
+        hasStatusSignal: uiSignals.hasStatusSignal,
+        hasLiveRegion: uiSignals.hasLiveRegion,
+        validationFeedbackDetected: uiSignals.validationFeedbackDetected,
+        disabledElementsCount: uiSignals.disabledElements?.length || 0,
+        explanation: uiSignals.explanation || []
+      },
+      timestamp,
+      url: currentUrl
+    });
+    
+    // Create observation for DOM state
+    observations.push({
+      type: 'dom_state',
+      scope: 'page',
+      data: {
+        domHash: domSignature,
+        hasDom: !!domSignature
+      },
+      timestamp,
+      url: currentUrl
+    });
+    
+    // If there are loading indicators, create specific observation
+    if (uiSignals.hasLoadingIndicator) {
+      observations.push({
+        type: 'ui_loading',
+        scope: 'page',
+        data: {
+          loading: true,
+          explanation: uiSignals.explanation?.filter(e => e.includes('loading') || e.includes('busy')) || []
+        },
+        timestamp,
+        url: currentUrl
+      });
+    }
+    
+    // If there are disabled elements, create observation
+    if (uiSignals.disabledElements && uiSignals.disabledElements.length > 0) {
+      observations.push({
+        type: 'ui_disabled',
+        scope: 'page',
+        data: {
+          disabledCount: uiSignals.disabledElements.length,
+          disabledElements: uiSignals.disabledElements.slice(0, 10) // Limit to 10
+        },
+        timestamp,
+        url: currentUrl
+      });
+    }
+  } catch (error) {
+    // Propagate error - no silent catch
+    throw new Error(`UI feedback observer failed: ${error.message}`);
+  }
+  
+  return observations;
+}
+

package/src/verax/observe/settle.js

@@ -1,6 +1,7 @@
 /**
  * WAVE 2: Deterministic DOM settle logic
  * Waits for page to stabilize after navigation or interaction
+ * @typedef {import('playwright').Page} Page
  */
 
 import { DEFAULT_SCAN_BUDGET } from '../shared/scan-budget.js';

package/src/verax/observe/state-sensor.js

@@ -58,7 +58,10 @@ class ReduxSensor {
             resolve();
           } else {
             // Wait up to 5 seconds for store initialization
-            const timeout = setTimeout(() => resolve(), 5000);
+            const timeout = setTimeout(() => {
+              clearInterval(check);
+              resolve();
+            }, 5000);
             const check = setInterval(() => {
               if (window.__REDUX_STORE__) {
                 clearInterval(check);
@@ -125,7 +128,7 @@ class ReduxSensor {
               // Shallow copy of top-level keys only (privacy: no values)
               const snapshot = {};
               for (const key in state) {
-                if (state.hasOwnProperty(key)) {
+                if (Object.prototype.hasOwnProperty.call(state, key)) {
                   snapshot[key] = '[REDACTED]'; // Never store values, only keys
                 }
               }
@@ -222,8 +225,9 @@ class ZustandSensor {
         // Look for common Zustand patterns in window object
         for (const key in window) {
           if (key.startsWith('use') && typeof window[key] === 'function') {
-            const store = window[key];
-            if (store.getState && typeof store.getState === 'function') {
+            // Dynamic property access on window for Zustand store detection (runtime property)
+            const store = /** @type {any} */ (window[key]);
+            if (store && typeof store === 'object' && 'getState' in store && typeof store.getState === 'function') {
               return true;
             }
           }

package/src/verax/observe/state-ui-sensor.js

@@ -22,13 +22,14 @@ export class StateUISensor {
    */
   async snapshot(page, contextSelector = null) {
     try {
-      const snapshot = await page.evaluate(({ selector }) => {
+      const snapshot = await page.evaluate(() => {
         const signals = {};
         const rawSnapshot = {};
 
         // 1. Dialog/Modal signals
         signals.dialogs = [];
         const dialogs = document.querySelectorAll('[role="dialog"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const dialog of dialogs) {
           const isVisible = dialog.offsetParent !== null || dialog.hasAttribute('open');
           const ariaModal = dialog.getAttribute('aria-modal');
@@ -46,6 +47,7 @@ export class StateUISensor {
         // 2. Expansion state (aria-expanded)
         signals.expandedElements = [];
         const expandables = document.querySelectorAll('[aria-expanded]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const el of expandables) {
           const expanded = el.getAttribute('aria-expanded') === 'true';
           signals.expandedElements.push({
@@ -58,6 +60,7 @@ export class StateUISensor {
         // 3. Tab selection (role=tab with aria-selected)
         signals.selectedTabs = [];
         const tabs = document.querySelectorAll('[role="tab"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const tab of tabs) {
           const selected = tab.getAttribute('aria-selected') === 'true';
           signals.selectedTabs.push({
@@ -70,6 +73,7 @@ export class StateUISensor {
         // 4. Checkbox/toggle state (aria-checked)
         signals.checkedElements = [];
         const checkables = document.querySelectorAll('[aria-checked]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const el of checkables) {
           const checked = el.getAttribute('aria-checked') === 'true';
           signals.checkedElements.push({
@@ -82,6 +86,7 @@ export class StateUISensor {
         // 5. Alert/Status changes (role=alert, role=status)
         signals.alerts = [];
         const alerts = document.querySelectorAll('[role="alert"], [role="status"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const alert of alerts) {
           const text = alert.textContent?.trim() || '';
           signals.alerts.push({
@@ -96,6 +101,7 @@ export class StateUISensor {
         // Count visible nodes and text nodes (excluding style/comment nodes)
         const countMeaningfulNodes = () => {
           let count = 0;
+          // @ts-expect-error - NodeListOf is iterable in browser context
           for (const node of document.querySelectorAll('*')) {
             if (node.offsetParent !== null) { // Visible
               count++;

package/src/verax/observe/traces-writer.js

@@ -1,7 +1,23 @@
-import { resolve } from 'path';
 import { writeFileSync, mkdirSync } from 'fs';
 import { getArtifactPath, getRunArtifactDir } from '../core/run-id.js';
 
+/**
+ * @typedef {Object} WriteTracesResult
+ * @property {number} version
+ * @property {string} observedAt
+ * @property {string} url
+ * @property {Array} traces
+ * @property {Array} [observedExpectations]
+ * @property {Object} [coverage]
+ * @property {Array} [warnings]
+ * @property {Object} [silences] - Added by writeTraces if silenceTracker provided
+ * @property {string} tracesPath
+ * @property {Object} observeTruth
+ * @property {Object} [expectationExecution] - Added by caller after writeTraces
+ * @property {Array} [expectationCoverageGaps] - Added by caller after writeTraces
+ * @property {Object} [incremental] - Added by caller after writeTraces
+ */
+
 /**
  * SILENCE TRACKING: Write observation traces with explicit silence tracking.
  * All gaps, skips, caps, and unknowns must be recorded and surfaced.
@@ -11,24 +27,19 @@ import { getArtifactPath, getRunArtifactDir } from '../core/run-id.js';
  * @param {string} projectDir - Project directory
  * @param {string} url - URL observed
  * @param {Array} traces - Execution traces
- * @param {Object} coverage - Coverage data (if capped, this is a silence)
- * @param {Array} warnings - Warnings (caps are silences)
- * @param {Array} observedExpectations - Observed expectations
- * @param {Object} silenceTracker - Silence tracker (optional)
- * @param {string} runId - Run identifier (Phase 5)
+ * @param {Object} [coverage] - Coverage data (if capped, this is a silence)
+ * @param {Array} [warnings] - Warnings (caps are silences)
+ * @param {Array} [observedExpectations] - Observed expectations
+ * @param {Object} [silenceTracker] - Silence tracker (optional)
+ * @param {string} [runId] - Run identifier (Phase 5) - required but optional in signature for type compatibility
+ * @returns {WriteTracesResult}
  */
 export function writeTraces(projectDir, url, traces, coverage = null, warnings = [], observedExpectations = [], silenceTracker = null, runId = null) {
-  // PHASE 5: Use deterministic artifact path if runId provided, otherwise fall back to old path
-  let observeDir, tracesPath;
-  if (runId) {
-    observeDir = getRunArtifactDir(projectDir, runId);
-    tracesPath = getArtifactPath(projectDir, runId, 'traces.json');
-  } else {
-    // Backwards compatibility for tests
-    observeDir = resolve(projectDir, '.veraxverax', 'observe');
-    tracesPath = resolve(observeDir, 'observation-traces.json');
+  if (!runId) {
+    throw new Error('runId is required');
   }
-  
+  const observeDir = getRunArtifactDir(projectDir, runId);
+  const tracesPath = getArtifactPath(projectDir, runId, 'traces.json');
   mkdirSync(observeDir, { recursive: true });
   
   const observation = {