@veraxhq/verax 0.2.1 → 0.4.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 {Object} 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 {Object} context - Observe context
+ * @param {Object} _runState - Current run state
+ * @returns {Promise<Array<Object>>} 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/page-traversal.js

@@ -0,0 +1,138 @@
+/**
+ * PAGE TRAVERSAL ENGINE
+ * 
+ * Manages page frontier, link discovery, and page-to-page navigation.
+ */
+
+import { isExternalUrl } from './domain-boundary.js';
+
+/**
+ * Discover links on current page
+ * 
+ * @param {Object} page - Playwright page
+ * @param {string} baseOrigin - Base origin URL
+ * @param {Object} silenceTracker - Silence tracker
+ * @returns {Promise<Array>}
+ */
+export async function discoverPageLinks(page, baseOrigin, silenceTracker) {
+  try {
+    // Discover all links on the page
+    const links = await page.locator('a[href]').all();
+    const linkData = [];
+    
+    for (const link of links) {
+      const href = await link.getAttribute('href');
+      if (href) {
+        linkData.push({ href });
+      }
+    }
+    
+    // Filter to same-origin links
+    const sameOriginLinks = linkData.filter(link => {
+      if (!link.href) return false;
+      return !isExternalUrl(link.href, baseOrigin);
+    });
+
+    return sameOriginLinks;
+  } catch (error) {
+    silenceTracker.record('link_discovery_error');
+    return [];
+  }
+}
+
+/**
+ * Get next page URL from frontier
+ * 
+ * @param {Object} frontier - Page frontier object
+ * @returns {string|null}
+ */
+export function getNextPageUrl(frontier) {
+  if (!frontier || !frontier.queue || frontier.queue.length === 0) {
+    return null;
+  }
+
+  const nextUrl = frontier.queue[0];
+  return nextUrl;
+}
+
+/**
+ * Mark page as visited in frontier
+ * 
+ * @param {Object} frontier - Page frontier object
+ * @param {string} url - URL that was visited
+ */
+export function markPageVisited(frontier, url) {
+  if (!frontier) return;
+  
+  // Remove from queue
+  if (frontier.queue && frontier.queue.length > 0) {
+    frontier.queue = frontier.queue.filter(u => u !== url);
+  }
+
+  // Add to visited
+  if (!frontier.visited) {
+    frontier.visited = [];
+  }
+  if (!frontier.visited.includes(url)) {
+    frontier.visited.push(url);
+  }
+}
+
+/**
+ * Add discovered links to frontier queue
+ * 
+ * @param {Object} frontier - Page frontier object
+ * @param {Array} links - Links to add
+ */
+export function addLinksToFrontier(frontier, links) {
+  if (!frontier || !links || links.length === 0) return;
+
+  if (!frontier.queue) {
+    frontier.queue = [];
+  }
+
+  for (const link of links) {
+    if (link.href && !frontier.queue.includes(link.href) && 
+        (!frontier.visited || !frontier.visited.includes(link.href))) {
+      frontier.queue.push(link.href);
+    }
+  }
+}
+
+/**
+ * Check if page limit has been reached
+ * 
+ * @param {number} pagesVisited - Number of pages visited
+ * @param {number} pageLimit - Maximum pages to visit
+ * @returns {boolean}
+ */
+export function isPageLimitReached(pagesVisited, pageLimit) {
+  return pagesVisited >= pageLimit;
+}
+
+/**
+ * Cap frontier to maximum size
+ * 
+ * @param {Object} frontier - Page frontier object
+ * @param {number} maxFrontierSize - Maximum frontier queue size
+ */
+export function capFrontier(frontier, maxFrontierSize) {
+  if (!frontier || !frontier.queue) return;
+
+  if (frontier.queue.length > maxFrontierSize) {
+    frontier.queue = frontier.queue.slice(0, maxFrontierSize);
+  }
+}
+
+/**
+ * Initialize frontier for traversal
+ * 
+ * @param {string} baseUrl - Starting URL
+ * @returns {Object}
+ */
+export function initializeFrontier(baseUrl) {
+  return {
+    queue: [baseUrl],
+    visited: []
+  };
+}

package/src/verax/observe/snapshot-ops.js

@@ -0,0 +1,94 @@
+/**
+ * SNAPSHOT OPERATIONS MODULE
+ * 
+ * Encapsulates snapshot loading, comparison, building, and saving logic.
+ * Extracted from observe/index.js (STAGE D2.1).
+ * 
+ * Preserves 100% of original behavior:
+ * - Same incremental mode conditions
+ * - Same snapshot JSON shape
+ * - Same load/save timing
+ * - Same trace filtering
+ */
+
+import {
+  loadPreviousSnapshot,
+  buildSnapshot,
+  compareSnapshots,
+  saveSnapshot
+} from '../core/incremental-store.js';
+
+/**
+ * Initialize snapshot operations at the beginning of observation
+ * 
+ * Loads previous snapshot, compares with baseline, determines incremental mode.
+ * Extracted from lines 108-111 of observe/index.js
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} manifest - Loaded manifest object
+ * @returns {Promise<{oldSnapshot: Object|null, snapshotDiff: Object|null, incrementalMode: boolean}>}
+ */
+export async function initializeSnapshot(projectDir, manifest) {
+  let oldSnapshot = null;
+  let snapshotDiff = null;
+  let incrementalMode = false;
+
+  // SCALE INTELLIGENCE: Load previous snapshot for incremental mode
+  oldSnapshot = loadPreviousSnapshot(projectDir);
+  if (oldSnapshot) {
+    const currentSnapshot = buildSnapshot(manifest, []);
+    snapshotDiff = compareSnapshots(oldSnapshot, currentSnapshot);
+    incrementalMode = !snapshotDiff.hasChanges; // Use incremental if nothing changed
+  }
+
+  return {
+    oldSnapshot,
+    snapshotDiff,
+    incrementalMode
+  };
+}
+
+/**
+ * Finalize snapshot operations at the end of observation
+ * 
+ * Builds current snapshot from observed interactions, saves for next run,
+ * and creates incremental metadata for observation object.
+ * Extracted from lines 789-811 of observe/index.js
+ * 
+ * @param {Object} manifest - Loaded manifest object (or null if not provided)
+ * @param {Array} traces - All collected traces
+ * @param {Array} skippedInteractions - Array of skipped interactions
+ * @param {boolean} incrementalMode - Whether incremental mode was enabled
+ * @param {Object} snapshotDiff - Snapshot diff from initialization (or null)
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @param {string} url - Initial URL (fallback for trace.before.url)
+ * @returns {Promise<{enabled: boolean, snapshotDiff: Object, skippedInteractionsCount: number}|null>}
+ */
+export async function finalizeSnapshot(manifest, traces, skippedInteractions, incrementalMode, snapshotDiff, projectDir, runId, url) {
+  let incrementalMetadata = null;
+
+  // SCALE INTELLIGENCE: Save snapshot for next incremental run
+  if (manifest) {
+    // Build snapshot from current run (extract interactions from traces)
+    const observedInteractions = traces
+      .filter(t => t.interaction && !t.incremental)
+      .map(t => ({
+        type: t.interaction?.type,
+        selector: t.interaction?.selector,
+        url: t.before?.url || url
+      }));
+
+    const currentSnapshot = buildSnapshot(manifest, observedInteractions);
+    saveSnapshot(projectDir, currentSnapshot, runId);
+
+    // Add incremental mode metadata to observation
+    incrementalMetadata = {
+      enabled: incrementalMode,
+      snapshotDiff: snapshotDiff,
+      skippedInteractionsCount: skippedInteractions.filter(s => s.reason === 'incremental_unchanged').length
+    };
+  }
+
+  return incrementalMetadata;
+}