@veraxhq/verax 0.2.0 → 0.2.1

package/src/cli/util/observation-engine.js

@@ -1,6 +1,6 @@
 import { chromium } from 'playwright';
 import { writeFileSync, mkdirSync } from 'fs';
-import { resolve, join } from 'path';
+import { resolve } from 'path';
 import { redactHeaders, redactUrl, redactBody, redactConsole, getRedactionCounters } from './redact.js';
 
 /**
@@ -60,9 +60,16 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
       });
     });
 
-    // Navigate to base URL first
+    // Navigate to base URL first with explicit timeout
     try {
-      await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+      await page.goto(url, { 
+        waitUntil: 'domcontentloaded', // Use domcontentloaded instead of networkidle for faster timeout
+        timeout: 30000 
+      });
+      // Wait for network idle with separate timeout
+      await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {
+        // Network idle timeout is acceptable, continue
+      });
     } catch (error) {
       // Continue even if initial load fails
       if (onProgress) {
@@ -96,6 +103,7 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
         type: exp.type,
         promise: exp.promise,
         source: exp.source,
+        attempted: false,
         observed: false,
         observedAt: null,
         evidenceFiles: [],
@@ -107,6 +115,7 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
         let evidence = null;
 
         if (exp.type === 'navigation') {
+          observation.attempted = true; // Mark as attempted
           result = await observeNavigation(
             page,
             exp,
@@ -117,6 +126,7 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
           );
           evidence = result ? `nav_${expNum}_after.png` : null;
         } else if (exp.type === 'network') {
+          observation.attempted = true; // Mark as attempted
           result = await observeNetwork(page, exp, networkLogs, 5000);
           if (result) {
             const evidenceFile = `network_${expNum}.json`;
@@ -135,6 +145,7 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
             evidence = null;
           }
         } else if (exp.type === 'state') {
+          observation.attempted = true; // Mark as attempted
           result = await observeState(page, exp, evidencePath, expNum);
           evidence = result ? `state_${expNum}_after.png` : null;
         }
@@ -187,19 +198,47 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
       observedAt: new Date().toISOString(),
     };
   } finally {
-    // Clean up
+    // Robust cleanup: ensure browser/context/page are closed
+    // Remove all event listeners to prevent leaks
     if (page) {
       try {
-        await page.close();
+        // Remove all listeners
+        page.removeAllListeners();
+        // @ts-expect-error - Playwright page.close() doesn't accept timeout option, but we use it for safety
+        await page.close({ timeout: 5000 }).catch(() => {});
       } catch (e) {
-        // Ignore close errors
+        // Ignore close errors but emit warning if onProgress available
+        if (onProgress) {
+          onProgress({
+            event: 'observe:warning',
+            message: `Page cleanup warning: ${e.message}`,
+          });
+        }
       }
     }
+    
+    // Close browser context if it exists
     if (browser) {
       try {
-        await browser.close();
+        const contexts = browser.contexts();
+        for (const context of contexts) {
+          try {
+            // @ts-expect-error - Playwright context.close() doesn't accept timeout option, but we use it for safety
+            await context.close({ timeout: 5000 }).catch(() => {});
+          } catch (e) {
+            // Ignore context close errors
+          }
+        }
+        // @ts-expect-error - Playwright browser.close() doesn't accept timeout option, but we use it for safety
+        await browser.close({ timeout: 5000 }).catch(() => {});
       } catch (e) {
-        // Ignore close errors
+        // Ignore browser close errors but emit warning if onProgress available
+        if (onProgress) {
+          onProgress({
+            event: 'observe:warning',
+            message: `Browser cleanup warning: ${e.message}`,
+          });
+        }
       }
     }
   }
@@ -242,6 +281,7 @@ async function observeNavigation(page, expectation, baseUrl, visitedUrls, eviden
         await page.click(`a[href="${element.href}"]`);
       } catch (e2) {
         // Try clicking by text content
+        // eslint-disable-next-line no-undef
         const text = await page.evaluate((href) => {
           const anchors = Array.from(document.querySelectorAll('a'));
           const found = anchors.find(a => a.getAttribute('href') === href);
@@ -254,14 +294,23 @@ async function observeNavigation(page, expectation, baseUrl, visitedUrls, eviden
       }
     }
 
-    // Wait for navigation or SPA update
+    // Wait for navigation or SPA update with explicit timeout
     try {
-      await page.waitForNavigation({ waitUntil: 'networkidle', timeout: 2000 }).catch(() => {});
+      await page.waitForNavigation({ 
+        waitUntil: 'domcontentloaded', 
+        timeout: 5000 
+      }).catch(() => {
+        // Navigation timeout is acceptable for SPAs
+      });
+      // Wait for network idle with separate timeout
+      await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
+        // Network idle timeout is acceptable
+      });
     } catch (e) {
-      // Navigation might not happen
+      // Navigation might not happen, continue
     }
 
-    // Wait for potential SPA updates
+    // Wait for potential SPA updates (bounded)
     await page.waitForTimeout(300);
 
     // Screenshot after interaction
@@ -304,13 +353,21 @@ async function observeNetwork(page, expectation, networkLogs, timeoutMs) {
       if (found) {
         clearInterval(checkTimer);
         resolve(true);
+        return;
       }
 
       if (Date.now() - startTime > timeoutMs) {
         clearInterval(checkTimer);
         resolve(false);
+        return;
       }
     }, 100);
+    
+    // CRITICAL: Unref the interval so it doesn't keep the process alive
+    // This allows tests to exit cleanly even if interval is not cleared
+    if (checkTimer && checkTimer.unref) {
+      checkTimer.unref();
+    }
   });
 }
 
@@ -353,14 +410,3 @@ async function observeState(page, expectation, evidencePath, expNum) {
   }
 }
 
-/**
- * Check if page content changed (for SPA detection)
- */
-async function checkPageContentChanged(page) {
-  try {
-    const bodyText = await page.locator('body').textContent();
-    return bodyText && bodyText.length > 0;
-  } catch (error) {
-    return false;
-  }
-}

package/src/cli/util/paths.js

@@ -1,11 +1,12 @@
-import { join } from 'path';
+import { join, isAbsolute } from 'path';
 import { mkdirSync } from 'fs';
 
 /**
  * Build run artifact paths
  */
 export function getRunPaths(projectRoot, outDir, runId) {
-  const baseDir = join(projectRoot, outDir, 'runs', runId);
+  const outBase = isAbsolute(outDir) ? outDir : join(projectRoot, outDir);
+  const baseDir = join(outBase, 'runs', runId);
   
   return {
     baseDir,

package/src/cli/util/project-discovery.js

@@ -4,8 +4,22 @@ import { resolve, dirname } from 'path';
 /**
  * Project Discovery Module
  * Detects framework, router, source root, and dev server configuration
+ * 
+ * @typedef {Object} ProjectProfile
+ * @property {string} framework
+ * @property {string|null} router
+ * @property {string} sourceRoot
+ * @property {string} packageManager
+ * @property {{dev: string|null, build: string|null, start: string|null}} scripts
+ * @property {string} detectedAt
+ * @property {string|null} packageJsonPath
+ * @property {number} [fileCount] - Optional file count for budget calculation
  */
 
+/**
+ * @param {string} srcPath
+ * @returns {Promise<ProjectProfile>}
+ */
 export async function discoverProject(srcPath) {
   const projectRoot = resolve(srcPath);
   
@@ -62,6 +76,12 @@ function findPackageJson(startPath) {
     return immediatePackage;
   }
   
+  // For static HTML projects, don't walk up - use the startPath as project root
+  // This prevents finding parent package.json files that aren't relevant
+  if (hasStaticHtml(currentPath)) {
+    return null;
+  }
+  
   // Then walk up (limit to 5 levels for monorepos, not 10)
   for (let i = 0; i < 5; i++) {
     const parentPath = dirname(currentPath);

package/src/cli/util/redact.js

@@ -105,14 +105,14 @@ export function redactTokensInText(text, counters = { headersRedacted: 0, tokens
   });
 
   // Bearer tokens
-  output = output.replace(/Bearer\s+([A-Za-z0-9._-]+)/gi, (match, token) => {
+  output = output.replace(/Bearer\s+([A-Za-z0-9._-]+)/gi, (_match, _token) => {
     c.tokensRedacted += 1;
     return `Bearer ${REDACTED}`;
   });
 
   // JWT-like strings (three base64url-ish segments)
   // More specific: require uppercase or numbers, not just domain patterns like "api.example.com"
-  output = output.replace(/[A-Z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, (match) => {
+  output = output.replace(/[A-Z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, (_match) => {
     c.tokensRedacted += 1;
     return REDACTED;
   });

package/src/cli/util/runtime-budget.js

@@ -0,0 +1,147 @@
+/**
+ * Runtime Budget Model
+ * Computes timeouts based on project size, execution mode, and framework
+ * Ensures deterministic, bounded execution times
+ */
+
+/**
+ * @typedef {Object} RuntimeBudgetOptions
+ * @property {number} [expectationsCount=0] - Number of expectations to process
+ * @property {string} [mode='default'] - Execution mode: 'default', 'run', 'ci'
+ * @property {string} [framework='unknown'] - Detected framework (optional)
+ * @property {number|null} [fileCount=null] - Number of files scanned (optional, fallback to expectationsCount)
+ */
+
+/**
+ * Compute runtime budgets for a VERAX run
+ * @param {RuntimeBudgetOptions} [options={}] - Budget computation options
+ * @returns {Object} Budget object with phase timeouts
+ */
+export function computeRuntimeBudget(options = {}) {
+  const {
+    expectationsCount = 0,
+    mode = 'default',
+    framework = 'unknown',
+    fileCount = null,
+  } = options;
+
+  // TEST MODE OVERRIDE: Fixed deterministic budgets for integration tests
+  if (process.env.VERAX_TEST_MODE === '1') {
+    return {
+      totalMaxMs: 30000,          // Hard cap per run
+      learnMaxMs: 5000,           // Keep learn bounded
+      observeMaxMs: 20000,        // Deterministic observe budget
+      detectMaxMs: 5000,          // Bounded detect
+      perExpectationMaxMs: 5000,  // Deterministic per-expectation guard
+      mode: 'test',
+      framework,
+      expectationsCount,
+      projectSize: fileCount !== null ? fileCount : expectationsCount,
+      frameworkMultiplier: 1.0,
+    };
+  }
+
+  // Use file count if available, otherwise use expectations count as proxy
+  const projectSize = fileCount !== null ? fileCount : expectationsCount;
+
+  // Base timeouts (milliseconds)
+  // Small project: < 10 expectations/files
+  // Medium project: 10-50 expectations/files
+  // Large project: > 50 expectations/files
+
+  // Learn phase: file scanning and AST parsing
+  const learnBaseMs = mode === 'ci' ? 30000 : 60000; // CI: 30s, default: 60s
+  const learnPerFileMs = 50; // 50ms per file
+  const learnMaxMs = mode === 'ci' ? 120000 : 300000; // CI: 2min, default: 5min
+
+  // Observe phase: browser automation
+  const observeBaseMs = mode === 'ci' ? 60000 : 120000; // CI: 1min, default: 2min
+  const observePerExpectationMs = mode === 'ci' ? 2000 : 5000; // CI: 2s, default: 5s per expectation
+  const observeMaxMs = mode === 'ci' ? 600000 : 1800000; // CI: 10min, default: 30min
+
+  // Detect phase: analysis and comparison
+  const detectBaseMs = mode === 'ci' ? 15000 : 30000; // CI: 15s, default: 30s
+  const detectPerExpectationMs = 100; // 100ms per expectation
+  const detectMaxMs = mode === 'ci' ? 120000 : 300000; // CI: 2min, default: 5min
+
+  // Per-expectation timeout during observe phase
+  const perExpectationBaseMs = mode === 'ci' ? 10000 : 30000; // CI: 10s, default: 30s
+  const perExpectationMaxMs = 120000; // 2min max per expectation
+
+  // Framework weighting (some frameworks may need more time)
+  let frameworkMultiplier = 1.0;
+  if (framework === 'nextjs' || framework === 'remix') {
+    frameworkMultiplier = 1.2; // SSR frameworks may need slightly more time
+  } else if (framework === 'react' || framework === 'vue') {
+    frameworkMultiplier = 1.1; // SPA frameworks
+  }
+
+  // Compute phase budgets
+  const computedLearnMaxMs = Math.min(
+    learnBaseMs + (projectSize * learnPerFileMs * frameworkMultiplier),
+    learnMaxMs
+  );
+
+  const computedObserveMaxMs = Math.min(
+    observeBaseMs + (expectationsCount * observePerExpectationMs * frameworkMultiplier),
+    observeMaxMs
+  );
+
+  const computedDetectMaxMs = Math.min(
+    detectBaseMs + (expectationsCount * detectPerExpectationMs * frameworkMultiplier),
+    detectMaxMs
+  );
+
+  const computedPerExpectationMaxMs = Math.min(
+    perExpectationBaseMs * frameworkMultiplier,
+    perExpectationMaxMs
+  );
+
+  // Global watchdog timeout (must be >= sum of all phases + buffer)
+  // Add 30s buffer for finalization
+  const totalMaxMs = Math.max(
+    computedLearnMaxMs + computedObserveMaxMs + computedDetectMaxMs + 30000,
+    mode === 'ci' ? 900000 : 2400000 // CI: 15min minimum, default: 40min minimum
+  );
+
+  // Cap global timeout
+  const totalMaxMsCap = mode === 'ci' ? 1800000 : 3600000; // CI: 30min, default: 60min
+  const finalTotalMaxMs = Math.min(totalMaxMs, totalMaxMsCap);
+
+  // Ensure minimums are met
+  const finalLearnMaxMs = Math.max(computedLearnMaxMs, 10000); // At least 10s
+  const finalObserveMaxMs = Math.max(computedObserveMaxMs, 30000); // At least 30s
+  const finalDetectMaxMs = Math.max(computedDetectMaxMs, 5000); // At least 5s
+  const finalPerExpectationMaxMs = Math.max(computedPerExpectationMaxMs, 5000); // At least 5s
+
+  return {
+    totalMaxMs: finalTotalMaxMs,
+    learnMaxMs: finalLearnMaxMs,
+    observeMaxMs: finalObserveMaxMs,
+    detectMaxMs: finalDetectMaxMs,
+    perExpectationMaxMs: finalPerExpectationMaxMs,
+    mode,
+    framework,
+    expectationsCount,
+    projectSize,
+  };
+}
+
+/**
+ * Create a timeout wrapper that rejects after specified milliseconds
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @param {Promise} promise - Promise to wrap
+ * @param {string} phase - Phase name for error messages
+ * @returns {Promise} Promise that rejects on timeout
+ */
+export function withTimeout(timeoutMs, promise, phase = 'unknown') {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Phase timeout: ${phase} exceeded ${timeoutMs}ms`));
+      }, timeoutMs);
+    }),
+  ]);
+}
+

package/src/cli/util/summary-writer.js

@@ -1,5 +1,4 @@
 import { atomicWriteJson } from './atomic-write.js';
-import { resolve } from 'path';
 
 /**
  * Write summary.json with deterministic digest
@@ -15,6 +14,18 @@ export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
     command: summaryData.command,
     url: summaryData.url,
     notes: summaryData.notes,
+    metrics: summaryData.metrics || {
+      learnMs: stats.learnMs || 0,
+      observeMs: stats.observeMs || 0,
+      detectMs: stats.detectMs || 0,
+      totalMs: stats.totalMs || 0,
+    },
+    findingsCounts: summaryData.findingsCounts || {
+      HIGH: stats.HIGH || 0,
+      MEDIUM: stats.MEDIUM || 0,
+      LOW: stats.LOW || 0,
+      UNKNOWN: stats.UNKNOWN || 0,
+    },
     
     // Stable digest that should be identical across repeated runs on same input
     digest: {

package/src/types/global.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Global type declarations for VERAX
+ * These extend built-in types to support runtime-injected properties
+ */
+
+// Extend Window interface for browser-injected properties
+declare global {
+  interface Window {
+    __veraxNavTracking?: any;
+    next?: any;
+    __REDUX_STORE__?: any;
+    store?: any;
+    __REDUX_DEVTOOLS_EXTENSION__?: any;
+    __REACT_DEVTOOLS_GLOBAL_HOOK__?: any;
+    __VERAX_STATE_SENSOR__?: any;
+    __unhandledRejections?: any[];
+    __ZUSTAND_STORE__?: any;
+  }
+}
+
+// Playwright Page type (imported from playwright)
+import type { Page as PlaywrightPage } from 'playwright';
+
+// Re-export for use in JS files
+export type Page = PlaywrightPage;
+
+export {};
+

package/src/types/ts-ast.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TypeScript AST Node type extensions
+ * These extend the base Node type to include properties used by VERAX
+ */
+
+import type * as ts from 'typescript';
+
+declare module 'typescript' {
+  interface Node {
+    attributes?: ts.NodeArray<ts.JSDocAttribute>;
+    tagName?: ts.Identifier;
+    body?: ts.Node;
+    arguments?: ts.NodeArray<ts.Expression>;
+    initializer?: ts.Expression;
+    expression?: ts.Expression;
+    children?: ts.NodeArray<ts.Node>;
+  }
+  
+  namespace ts {
+    // Add isFalseKeyword if it doesn't exist (it might be in a different version)
+    function isFalseKeyword(node: ts.Node): node is ts.FalseKeyword;
+  }
+}
+

package/src/verax/cli/doctor.js

@@ -4,7 +4,7 @@
  * Checks environment, dependencies, and project setup.
  */
 
-import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { resolve } from 'path';
 import { chromium } from 'playwright';
 import { get } from 'http';
@@ -182,7 +182,7 @@ async function checkUrlReachability(url) {
  * @returns {Promise<Object>} Doctor results
  */
 export async function runDoctor(options = {}) {
-  const { projectRoot = process.cwd(), url = null, json = false } = options;
+  const { projectRoot = process.cwd(), url = null, json: _json = false } = options;
   
   const checks = [];
   let overallStatus = 'ok';

package/src/verax/cli/init.js

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, writeFileSync, mkdirSync } from 'fs';
-import { resolve, dirname } from 'path';
+import { resolve } from 'path';
 import { getDefaultConfig } from '../shared/config-loader.js';
 
 /**

package/src/verax/cli/url-safety.js

@@ -68,11 +68,21 @@ export function checkUrlSafety(url) {
   }
 }
 
+/**
+ * @typedef {Object} ReadlineInterface
+ * @property {function(string): Promise<string>} question - Prompt user with question
+ * @property {function(): void} close - Close the readline interface
+ */
+
+/**
+ * @typedef {Object} ConfirmExternalUrlOptions
+ * @property {ReadlineInterface} [readlineInterface] - Readline interface (injectable)
+ */
+
 /**
  * Prompt for external URL confirmation
  * @param {string} hostname - Hostname to confirm
- * @param {Object} options - Options
- * @param {Function} options.readlineInterface - Readline interface (injectable)
+ * @param {ConfirmExternalUrlOptions} [options={}] - Options
  * @returns {Promise<boolean>} True if confirmed
  */
 export async function confirmExternalUrl(hostname, options = {}) {

package/src/verax/cli/wizard.js

@@ -4,8 +4,15 @@
  * Guides users through VERAX configuration with friendly prompts.
  */
 
+/**
+ * @typedef {Object} ReadlineInterface
+ * @property {function(string): Promise<string>} question - Prompt user with question
+ * @property {function(): void} close - Close the readline interface
+ */
+
 /**
  * Create a readline interface (can be injected for testing)
+ * @returns {Promise<ReadlineInterface>}
  */
 async function createReadlineInterface(input = process.stdin, output = process.stdout) {
   const readline = await import('readline/promises');
@@ -16,10 +23,14 @@ async function createReadlineInterface(input = process.stdin, output = process.s
   });
 }
 
+/**
+ * @typedef {Object} WizardOptions
+ * @property {ReadlineInterface} [readlineInterface] - Readline interface (injectable for testing)
+ */
+
 /**
  * Run interactive wizard
- * @param {Object} options - Options for wizard
- * @param {Function} options.readlineInterface - Readline interface (injectable for testing)
+ * @param {WizardOptions} [options={}] - Options for wizard
  * @returns {Promise<Object>} Wizard results
  */
 export async function runWizard(options = {}) {

package/src/verax/core/budget-engine.js

@@ -131,7 +131,7 @@ export function computeRouteBudget(manifest, currentUrl, baseBudget) {
   const routes = manifest.routes || [];
   const expectations = manifest.staticExpectations || [];
   const totalRoutes = routes.length;
-  const totalExpectations = expectations.length;
+  // const totalExpectations = expectations.length; // Reserved for future use
   
   // Count expectations per route
   const routeExpectationCount = new Map();

package/src/verax/core/decision-snapshot.js

@@ -175,10 +175,10 @@ function extractUnverified(detectTruth, observeTruth) {
  * @param {Array} findings - Array of findings
  * @param {Object} detectTruth - Detect phase truth
  * @param {Object} observeTruth - Observe phase truth
- * @param {Object} silences - Silence data
+ * @param {Object} _silences - Silence data (unused parameter, kept for API compatibility)
  * @returns {Object} - Decision snapshot answering 6 mandatory questions
  */
-export function computeDecisionSnapshot(findings, detectTruth, observeTruth, silences) {
+export function computeDecisionSnapshot(findings, detectTruth, observeTruth, _silences) {
   // Question 1: Do we have confirmed SILENT FAILURES?
   const confirmedFailures = findings.filter(f => 
     f.outcome === 'broken' || f.type === 'silent_failure'