@veraxhq/verax 0.3.0 → 0.4.0

package/src/verax/observe/network-firewall.js

@@ -0,0 +1,86 @@
+/**
+ * NETWORK SAFETY FIREWALL
+ * 
+ * Handles network request interception and blocking:
+ * - Cross-origin blocking (unless --allow-cross-origin)
+ * - Read-only mode (blocks POST/PUT/PATCH/DELETE unconditionally)
+ * - Safety tracking via SilenceTracker
+ */
+
+/**
+ * Setup network interception firewall for safety mode
+ * 
+ * @param {Object} page - Playwright page object
+ * @param {string} baseOrigin - Base origin URL for cross-origin checks
+ * @param {boolean} allowCrossOrigin - Whether to allow cross-origin requests
+ * @param {Object} silenceTracker - Silence tracker instance
+ * @returns {Promise<{blockedNetworkWrites: Array, blockedCrossOrigin: Array}>}
+ */
+export async function setupNetworkFirewall(page, baseOrigin, allowCrossOrigin, silenceTracker) {
+  const blockedNetworkWrites = [];
+  const blockedCrossOrigin = [];
+
+  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
+      }
+    }
+    
+    // CONSTITUTIONAL: Block all write methods (read-only mode enforced)
+    if (['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();
+  });
+  
+  return { blockedNetworkWrites, blockedCrossOrigin };
+}

package/src/verax/observe/observation-builder.js

@@ -0,0 +1,169 @@
+/**
+ * OBSERVATION BUILDER
+ * 
+ * Constructs observation object from traces, calculates coverage, and generates warnings.
+ */
+
+/**
+ * Build observation object from collected traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @param {Array} coverage - Coverage information
+ * @param {Array} warnings - Warning messages
+ * @param {Object} safetyStats - Safety mode statistics
+ * @returns {Object}
+ */
+export function buildObservation(traces, coverage, warnings, safetyStats) {
+  const observation = {
+    timestamp: new Date().toISOString(),
+    traces: traces,
+    coverage: coverage || [],
+    warnings: warnings || [],
+    safetyStats: safetyStats || {}
+  };
+
+  return observation;
+}
+
+/**
+ * Calculate coverage gaps from traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @param {Array} discoveredInteractions - All interactions discovered during scan
+ * @returns {Array}
+ */
+export function calculateCoverageGaps(traces, discoveredInteractions) {
+  if (!discoveredInteractions || discoveredInteractions.length === 0) {
+    return [];
+  }
+
+  const executedSelectors = new Set(
+    traces
+      .filter(t => t.interaction && t.interaction.selector)
+      .map(t => t.interaction.selector)
+  );
+
+  const gaps = discoveredInteractions
+    .filter(interaction => !executedSelectors.has(interaction.selector))
+    .map(interaction => ({
+      selector: interaction.selector,
+      type: interaction.type,
+      reason: 'budget_exhausted_or_skipped'
+    }));
+
+  return gaps;
+}
+
+/**
+ * Generate warnings from observation data
+ * 
+ * @param {Object} frontier - Page frontier
+ * @param {Array} coverage - Coverage data
+ * @param {Object} safetyStats - Safety statistics
+ * @returns {Array}
+ */
+export function generateWarnings(frontier, coverage, safetyStats) {
+  const warnings = [];
+
+  // Warn if frontier has unexplored pages
+  if (frontier && frontier.queue && frontier.queue.length > 0) {
+    warnings.push({
+      type: 'unexplored_pages',
+      count: frontier.queue.length,
+      message: `${frontier.queue.length} pages in queue were not explored due to budget constraints`
+    });
+  }
+
+  // Warn if safety mode blocked actions
+  if (safetyStats && safetyStats.blockedNetworkWrites > 0) {
+    warnings.push({
+      type: 'safety_mode_active',
+      blockedWrites: safetyStats.blockedNetworkWrites,
+      message: `Safety mode prevented ${safetyStats.blockedNetworkWrites} write operations`
+    });
+  }
+
+  if (safetyStats && safetyStats.blockedCrossOrigin > 0) {
+    warnings.push({
+      type: 'cross_origin_blocked',
+      count: safetyStats.blockedCrossOrigin,
+      message: `${safetyStats.blockedCrossOrigin} cross-origin requests were blocked`
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Build safety statistics object
+ * 
+ * @param {number} blockedNetworkWrites - Number of blocked write operations
+ * @param {number} blockedCrossOrigin - Number of blocked cross-origin requests
+ * @param {Array} skippedInteractions - Interactions that were skipped
+ * @returns {Object}
+ */
+export function buildSafetyStatistics(blockedNetworkWrites, blockedCrossOrigin, skippedInteractions) {
+  return {
+    safetyModeEnabled: true,
+    blockedNetworkWrites: blockedNetworkWrites || 0,
+    blockedCrossOrigin: blockedCrossOrigin || 0,
+    skippedInteractions: skippedInteractions ? skippedInteractions.length : 0,
+    skippedReasons: skippedInteractions ? countSkipReasons(skippedInteractions) : {}
+  };
+}
+
+/**
+ * Count reasons for skipped interactions
+ * 
+ * @param {Array} skippedInteractions - Skipped interactions
+ * @returns {Object}
+ */
+function countSkipReasons(skippedInteractions) {
+  const reasons = {};
+  for (const skip of skippedInteractions) {
+    const reason = skip.reason || 'unknown';
+    reasons[reason] = (reasons[reason] || 0) + 1;
+  }
+  return reasons;
+}
+
+/**
+ * Extract observedExpectations from traces
+ * 
+ * @param {Array} traces - Array of interaction traces
+ * @returns {Array}
+ */
+export function extractObservedExpectations(traces) {
+  const expectations = [];
+  
+  for (const trace of traces) {
+    if (trace.observedExpectation) {
+      expectations.push({
+        ...trace.observedExpectation,
+        traceId: trace.id,
+        executionTimestamp: trace.timestamp
+      });
+    }
+  }
+
+  return expectations;
+}
+
+/**
+ * Build skipped interactions summary
+ * 
+ * @param {Array} interactions - Skipped interactions
+ * @returns {Array}
+ */
+export function buildSkippedInteractionsSummary(interactions) {
+  if (!interactions || interactions.length === 0) {
+    return [];
+  }
+
+  return interactions.map(skip => ({
+    selector: skip.selector,
+    type: skip.type,
+    reason: skip.reason,
+    element: skip.element
+  }));
+}

package/src/verax/observe/observe-context.js

@@ -65,7 +65,7 @@
 /**
  * Forbidden imports that observers MUST NOT use
  */
-const FORBIDDEN_IMPORTS = [
+const _FORBIDDEN_IMPORTS = [
   'fs',
   'path',
   '../core/determinism/report-writer',

package/src/verax/observe/observe-helpers.js

@@ -13,7 +13,7 @@ import { writeTraces } from './traces-writer.js';
  */
 export async function setupManifestAndExpectations(manifestPath, projectDir, page, url, screenshotsDir, scanBudget, startTime, silenceTracker) {
   const { readFileSync, existsSync } = await import('fs');
-  const { loadPreviousSnapshot, saveSnapshot, buildSnapshot, compareSnapshots } = await import('../core/incremental-store.js');
+  const { loadPreviousSnapshot, saveSnapshot: _saveSnapshot, buildSnapshot, compareSnapshots } = await import('../core/incremental-store.js');
   const { executeProvenExpectations } = await import('./expectation-executor.js');
   const { isProvenExpectation } = await import('../shared/expectation-prover.js');
   
@@ -27,6 +27,7 @@ export async function setupManifestAndExpectations(manifestPath, projectDir, pag
   if (manifestPath && existsSync(manifestPath)) {
     try {
       const manifestContent = readFileSync(manifestPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
       manifest = JSON.parse(manifestContent);
       
       oldSnapshot = loadPreviousSnapshot(projectDir);

package/src/verax/observe/observe-runner.js

@@ -15,31 +15,31 @@ import { createObserveContext } from './observe-context.js';
 /**
  * Run main traversal/interaction loop
  * 
- * @param {Object} params
- * @param {import('playwright').Page} params.page
- * @param {string} params.url
- * @param {string} params.baseOrigin
- * @param {Object} params.scanBudget
- * @param {number} params.startTime
- * @param {PageFrontier} params.frontier
- * @param {Object|null} params.manifest
- * @param {Object|null} params.expectationResults
- * @param {boolean} params.incrementalMode
- * @param {Object|null} params.oldSnapshot
- * @param {Object|null} params.snapshotDiff
- * @param {string} params.currentUrl
- * @param {string} params.screenshotsDir
- * @param {number} params.timestamp
+ * @param {Object} params - Parameters object
+ * @param {import('playwright').Page} params.page - Playwright page instance
+ * @param {string} params.url - Page URL
+ * @param {string} params.baseOrigin - Base origin for relative URLs
+ * @param {Object} params.scanBudget - Scan budget configuration
+ * @param {number} params.startTime - Scan start time
+ * @param {Object} params.frontier - Page frontier (URL queue)
+ * @param {Object|null} params.manifest - Manifest file data
+ * @param {Object|null} params.expectationResults - Expectation results
+ * @param {boolean} params.incrementalMode - Incremental mode flag
+ * @param {Object|null} params.oldSnapshot - Old snapshot data
+ * @param {Object|null} params.snapshotDiff - Snapshot diff
+ * @param {string} params.currentUrl - Current page URL
+ * @param {string} params.screenshotsDir - Screenshots directory
+ * @param {number} params.timestamp - Current timestamp
  * @param {Object} params.decisionRecorder - DecisionRecorder instance
  * @param {Object} params.silenceTracker - SilenceTracker instance
- * @param {Array} params.traces
- * @param {Array} params.skippedInteractions
- * @param {Array} params.observedExpectations
- * @param {number} params.totalInteractionsDiscovered
- * @param {number} params.totalInteractionsExecuted
- * @param {Array} params.remainingInteractionsGaps
- * @param {boolean} [params.allowWrites]
- * @param {boolean} [params.allowRiskyActions]
+ * @param {Array} params.traces - Interaction traces array
+ * @param {Array} params.skippedInteractions - Skipped interactions array
+ * @param {Array} params.observedExpectations - Observed expectations array
+ * @param {number} params.totalInteractionsDiscovered - Total discovered interactions
+ * @param {number} params.totalInteractionsExecuted - Total executed interactions
+ * @param {Array} params.remainingInteractionsGaps - Remaining interaction gaps
+ * @param {boolean} [params.allowWrites=false] - Allow file writes
+ * @param {boolean} [params.allowRiskyActions=false] - Allow risky actions
  * @returns {Promise<Object>} { traces, skippedInteractions, observedExpectations, totalInteractionsDiscovered, totalInteractionsExecuted, remainingInteractionsGaps }
  */
 export async function runTraversalLoop(params) {
@@ -110,7 +110,11 @@ export async function runTraversalLoop(params) {
     const context = createObserveContext({ ...baseContext, currentUrl, routeBudget: baseContext.routeBudget });
     
     // PHASE 21.3: Check page limit using budget-observer
-    const pageLimitCheck = checkBudget(context, runState, { limitType: 'pages' });
+    const pageLimitCheck = checkBudget(context, runState, { 
+      remainingInteractions: 0,
+      currentTotalExecuted: 0,
+      limitType: 'pages' 
+    });
     if (pageLimitCheck.exceeded) break;
 
     // Check if we're already on the target page (from navigation via link click)

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

@@ -15,13 +15,13 @@ import { recordTruncation } from '../../core/determinism-model.js';
 /**
  * Check if budget limits are exceeded
  * 
- * @param {ObserveContext} context - Observe context
- * @param {RunState} runState - Current run state
+ * @param {Object} context - Observe context
+ * @param {Object} runState - Current run state
  * @param {Object} options - Additional options
  * @param {number} options.remainingInteractions - Remaining interactions count
  * @param {number} options.currentTotalExecuted - Current total executed
  * @param {string} options.limitType - Type of limit to check ('time', 'per_page', 'total', 'pages')
- * @returns {Object} { exceeded: boolean, reason?: string, observation?: Observation }
+ * @returns {Object} { exceeded: boolean, reason?: string, observation?: Object }
  */
 export function checkBudget(context, runState, options) {
   const { scanBudget, startTime, routeBudget, decisionRecorder, silenceTracker, frontier, page } = context;

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

@@ -14,11 +14,11 @@ import { ConsoleSensor } from '../console-sensor.js';
 /**
  * Observe console errors and warnings on current page
  * 
- * @param {ObserveContext} context - Observe context
- * @param {RunState} runState - Current run state
- * @returns {Promise<Array<Observation>>} Array of console observations
+ * @param {Object} context - Observe context
+ * @param {Object} _runState - Current run state
+ * @returns {Promise<Array<Object>>} Array of console observations
  */
-export async function observe(context, runState) {
+export async function observe(context, _runState) {
   const { page, currentUrl, timestamp, silenceTracker } = context;
   const observations = [];
   

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

@@ -9,12 +9,12 @@
  * - NO side effects outside its scope
  */
 
-import { recordTruncation } from '../../core/determinism-model.js';
+import { recordTruncation as _recordTruncation } from '../../core/determinism-model.js';
 
 /**
  * Create coverage gap for remaining interactions
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @param {Array} remainingInteractions - Remaining interactions
  * @param {number} startIndex - Start index of remaining interactions
  * @param {string} reason - Reason for gap
@@ -42,7 +42,7 @@ export function createCoverageGaps(context, remainingInteractions, startIndex, r
 /**
  * Build coverage summary
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @param {number} totalDiscovered - Total interactions discovered
  * @param {number} totalExecuted - Total interactions executed
  * @param {number} skippedCount - Number of skipped interactions
@@ -68,7 +68,7 @@ export function buildCoverageSummary(context, totalDiscovered, totalExecuted, sk
 /**
  * Create coverage gap for frontier capping
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @returns {Object} Coverage gap
  */
 export function createFrontierCappedGap(context) {

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

@@ -56,8 +56,8 @@ export async function discoverInteractions(context) {
  * @param {string} currentUrl
  * @param {Array} traces - Mutable array to push skipped traces
  * @param {Array} skippedInteractions - Mutable array to push skipped interactions
- * @param {SilenceTracker} silenceTracker
- * @param {PageFrontier} frontier
+ * @param {Object} silenceTracker - Silence tracker instance
+ * @param {Object} frontier - Page frontier instance
  * @param {boolean} incrementalMode
  * @param {Object|null} manifest
  * @param {Object|null} oldSnapshot
@@ -255,7 +255,7 @@ export async function checkAndSkipInteraction(
  * @param {Array} traces - Mutable array to push traces
  * @param {Array} observedExpectations - Mutable array to push observed expectations
  * @param {Array} remainingInteractionsGaps - Mutable array to push gaps
- * @param {PageFrontier} frontier
+ * @param {Object} frontier - Page frontier instance
  * @param {string} baseOrigin
  * @param {boolean} incrementalMode
  * @param {Object|null} expectationResults

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

@@ -15,7 +15,7 @@ import { isExternalUrl } from '../domain-boundary.js';
 /**
  * Navigate to a URL
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @param {string} targetUrl - URL to navigate to
  * @returns {Promise<boolean>} True if navigation succeeded, false if failed
  */
@@ -48,7 +48,7 @@ export async function navigateToPage(context, targetUrl) {
 /**
  * Discover links on current page and add to frontier
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @returns {Promise<void>}
  */
 export async function discoverPageLinks(context) {
@@ -91,7 +91,7 @@ export async function discoverPageLinks(context) {
 /**
  * Check if we're already on the target page
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @param {string} targetUrl - Target URL
  * @returns {boolean} True if already on page
  */
@@ -106,7 +106,7 @@ export function isAlreadyOnPage(context, targetUrl) {
 /**
  * Mark page as visited in frontier
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @param {string} targetUrl - Target URL
  * @param {boolean} alreadyOnPage - Whether we're already on the page
  * @returns {void}

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

@@ -16,11 +16,11 @@ import { NetworkSensor } from '../network-sensor.js';
 /**
  * Observe network state on current page
  * 
- * @param {ObserveContext} context - Observe context
- * @param {RunState} runState - Current run state
- * @returns {Promise<Array<Observation>>} Array of network observations
+ * @param {Object} context - Observe context
+ * @param {Object} _runState - Current run state
+ * @returns {Promise<Array<Object>>} Array of network observations
  */
-export async function observe(context, runState) {
+export async function observe(context, _runState) {
   const { page, currentUrl, timestamp } = context;
   const observations = [];
   

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

@@ -10,7 +10,7 @@
 /**
  * Setup network interception firewall
  * 
- * @param {ObserveContext} context - Observe context
+ * @param {Object} context - Observe context
  * @returns {Promise<void>}
  */
 export async function setupNetworkInterception(context) {

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

@@ -16,11 +16,11 @@ 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
+ * @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) {
+export async function observe(context, _runState) {
   const { page, currentUrl, timestamp } = context;
   const 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: []
+  };
+}