@veraxhq/verax 0.2.0 → 0.3.0

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

@@ -1,31 +1,142 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
 import { findingIdFromExpectationId } from './idgen.js';
+import {
+  enforceContractsOnFindings,
+  FINDING_STATUS,
+  CONFIDENCE_LEVEL,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+} from '../../verax/core/contracts/index.js';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from '../../verax/core/artifacts/registry.js';
 
 /**
- * Write findings.json artifact with deterministic IDs
+ * Write findings.json artifact with deterministic IDs and contract enforcement
  */
 export function writeFindingsJson(runDir, findingsData) {
-  const findingsPath = resolve(runDir, 'findings.json');
-  
-  // Add deterministic finding IDs based on expectation IDs
-  const findingsWithIds = (findingsData.findings || []).map(finding => ({
+  const findingsPath = resolve(runDir, ARTIFACT_REGISTRY.findings.filename);
+  const normalizedFindings = normalizeFindings(findingsData?.findings || []);
+  const enforcement = enforceContractsOnFindings(normalizedFindings);
+
+  const findingsWithIds = enforcement.valid.map((finding) => ({
     ...finding,
-    findingId: findingIdFromExpectationId(finding.id),
+    findingId: findingIdFromExpectationId(finding.id || finding.expectationId || ''),
   }));
-  
+
+  const stats = findingsData?.stats || {};
   const payload = {
+    contractVersion: 1,
+    artifactVersions: getArtifactVersions(),
     findings: findingsWithIds,
+    total: findingsWithIds.length,
     stats: {
-      total: findingsData.stats?.total || 0,
-      silentFailures: findingsData.stats?.silentFailures || 0,
-      observed: findingsData.stats?.observed || 0,
-      coverageGaps: findingsData.stats?.coverageGaps || 0,
-      unproven: findingsData.stats?.unproven || 0,
-      informational: findingsData.stats?.informational || 0,
+      total: findingsWithIds.length,
+      silentFailures: stats.silentFailures || 0,
+      observed: stats.observed || 0,
+      coverageGaps: stats.coverageGaps || 0,
+      unproven: stats.unproven || 0,
+      informational: stats.informational || 0,
+    },
+    detectedAt: findingsData?.detectedAt || new Date().toISOString(),
+    enforcement: {
+      droppedCount: enforcement.dropped.length,
+      downgradedCount: enforcement.downgrades.length,
+      downgrades: enforcement.downgrades.map((entry) => ({
+        reason: entry.reason,
+        originalStatus: entry.original?.status,
+        downgradeToStatus: entry.downgraded?.status,
+      })),
+      dropped: enforcement.dropped.map((entry) => ({
+        reason: entry.reason,
+      })),
     },
-    detectedAt: findingsData.detectedAt || new Date().toISOString(),
   };
-  
+
   atomicWriteJson(findingsPath, payload);
+  return { path: findingsPath, payload };
+}
+
+function normalizeFindings(findings) {
+  return findings.map((finding) => normalizeFinding(finding));
+}
+
+function normalizeFinding(finding) {
+  const status = finding.status || mapClassificationToStatus(finding.classification);
+  const evidence = normalizeEvidence(finding.evidence);
+  const confidence = normalizeConfidence(finding.confidence);
+  const signals = normalizeSignals(finding);
+  const interaction = finding.interaction || {
+    type: finding.type || 'unknown',
+    selector: finding.promise?.selector || finding.promise?.value || finding.source?.file || 'unknown',
+  };
+
+  return {
+    ...finding,
+    status,
+    evidence,
+    confidence,
+    signals,
+    interaction,
+    what_happened: finding.what_happened || finding.reason || 'Expectation was exercised during scan.',
+    what_was_expected: finding.what_was_expected || finding.promise?.value || 'Expectation derived from source code.',
+    what_was_observed: finding.what_was_observed || finding.reason || 'Observation recorded for expectation.',
+    why_it_matters: finding.why_it_matters || 'Potential silent failure identified by expectation vs observation.',
+  };
+}
+
+function mapClassificationToStatus(classification) {
+  if (classification === 'observed') return FINDING_STATUS.CONFIRMED;
+  if (classification === 'silent-failure') return FINDING_STATUS.SUSPECTED;
+  if (classification === 'coverage-gap' || classification === 'unproven') return FINDING_STATUS.SUSPECTED;
+  return FINDING_STATUS.INFORMATIONAL;
+}
+
+function normalizeConfidence(confidence) {
+  if (confidence && typeof confidence === 'object' && confidence.level && confidence.score !== undefined) {
+    return confidence;
+  }
+
+  const numeric = typeof confidence === 'number' ? Math.max(0, Math.min(1, confidence)) : 0;
+  const score = Math.round(numeric * 100);
+  let level = CONFIDENCE_LEVEL.UNPROVEN;
+  if (score >= 80) level = CONFIDENCE_LEVEL.HIGH;
+  else if (score >= 60) level = CONFIDENCE_LEVEL.MEDIUM;
+  else if (score > 0) level = CONFIDENCE_LEVEL.LOW;
+
+  return { level, score };
+}
+
+function normalizeEvidence(evidenceArray) {
+  const items = Array.isArray(evidenceArray) ? evidenceArray : [];
+  const hasNetworkActivity = items.some((item) => item?.type === 'network-log');
+  const hasDomChange = items.some((item) => item?.type === 'screenshot');
+
+  return {
+    type: hasNetworkActivity ? 'network_activity' : undefined,
+    hasDomChange,
+    hasUrlChange: false,
+    hasNetworkActivity,
+    hasStateChange: false,
+    networkRequests: items.filter((item) => item?.type === 'network-log'),
+    before: items.find((item) => item?.type === 'screenshot')?.path,
+    after: undefined,
+  };
+}
+
+function normalizeSignals(finding) {
+  if (finding.signals && typeof finding.signals === 'object') {
+    return finding.signals;
+  }
+
+  const impact = (finding.impact && IMPACT[finding.impact]) ? finding.impact : IMPACT.MEDIUM;
+
+  return {
+    impact,
+    userRisk: USER_RISK.CONFUSES,
+    ownership: OWNERSHIP.FRONTEND,
+    grouping: {
+      expectationType: finding.type || 'unknown',
+    },
+  };
 }

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

@@ -1,18 +1,20 @@
 import { resolve } from 'path';
 import { atomicWriteJson } from './atomic-write.js';
 import { compareExpectations } from './idgen.js';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write learn.json artifact
  * Maintains deterministic ordering for stable output
  */
 export function writeLearnJson(runPaths, expectations, skipped) {
-  const learnJsonPath = resolve(runPaths.baseDir, 'learn.json');
+  const learnJsonPath = resolve(runPaths.baseDir, ARTIFACT_REGISTRY.learn.filename);
   
   // Sort expectations deterministically for stable output
   const sortedExpectations = [...expectations].sort(compareExpectations);
   
   const learnJson = {
+    contractVersion: 1,
     expectations: sortedExpectations,
     stats: {
       totalExpectations: sortedExpectations.length,

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/observe-writer.js

@@ -1,13 +1,15 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write observe.json artifact
  */
 export function writeObserveJson(runDir, observeData) {
-  const observePath = resolve(runDir, 'observe.json');
+  const observePath = resolve(runDir, ARTIFACT_REGISTRY.observe.filename);
   
   const payload = {
+    contractVersion: 1,
     observations: observeData.observations || [],
     stats: {
       attempted: observeData.stats?.attempted || 0,

package/src/cli/util/paths.js

@@ -1,23 +1,15 @@
-import { join } from 'path';
+import { join, isAbsolute } from 'path';
 import { mkdirSync } from 'fs';
+import { buildRunArtifactPaths } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Build run artifact paths
  */
 export function getRunPaths(projectRoot, outDir, runId) {
-  const baseDir = join(projectRoot, outDir, 'runs', runId);
-  
-  return {
-    baseDir,
-    runStatusJson: join(baseDir, 'run.status.json'),
-    runMetaJson: join(baseDir, 'run.meta.json'),
-    summaryJson: join(baseDir, 'summary.json'),
-    findingsJson: join(baseDir, 'findings.json'),
-    tracesJsonl: join(baseDir, 'traces.jsonl'),
-    evidenceDir: join(baseDir, 'evidence'),
-    learnJson: join(baseDir, 'learn.json'),
-    observeJson: join(baseDir, 'observe.json'),
-  };
+  const outBase = isAbsolute(outDir) ? outDir : join(projectRoot, outDir);
+  const baseDir = join(outBase, 'runs', runId);
+
+  return buildRunArtifactPaths(baseDir);
 }
 
 /**

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

@@ -1,12 +1,29 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
+import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
 
 /**
  * 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) {
+  // PHASE 21.6.1: Runtime guard - crash if called during inspection
+  assertExecutionBootstrapAllowed('discoverProject');
   const projectRoot = resolve(srcPath);
   
   // Find the nearest package.json
@@ -62,6 +79,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/project-writer.js

@@ -1,13 +1,15 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write project profile artifact
  */
 export function writeProjectJson(runPaths, projectProfile) {
-  const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
+  const projectJsonPath = resolve(runPaths.baseDir, ARTIFACT_REGISTRY.project.filename);
   
   const projectJson = {
+    contractVersion: 1,
     framework: projectProfile.framework,
     router: projectProfile.router,
     sourceRoot: projectProfile.sourceRoot,

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/run-resolver.js

@@ -0,0 +1,64 @@
+/**
+ * PHASE 21.6.1 — Run Resolver
+ * 
+ * Pure filesystem logic to resolve run IDs.
+ * No side effects, no execution dependencies.
+ */
+
+import { readdirSync, statSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Find the latest run ID from .verax/runs/
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Latest run ID or null if no runs found
+ */
+export function findLatestRunId(projectDir) {
+  const runsDir = resolve(projectDir, '.verax', 'runs');
+  
+  if (!existsSync(runsDir)) {
+    return null;
+  }
+  
+  try {
+    const runs = readdirSync(runsDir, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => {
+        const runPath = resolve(runsDir, dirent.name);
+        try {
+          const stats = statSync(runPath);
+          return {
+            name: dirent.name,
+            mtimeMs: stats.mtimeMs
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter(run => run !== null);
+    
+    if (runs.length === 0) {
+      return null;
+    }
+    
+    // Sort by modification time (descending) and return latest
+    runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return runs[0].name;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Validate that a run ID exists
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID to validate
+ * @returns {boolean} Whether run exists
+ */
+export function validateRunId(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  return existsSync(runDir);
+}
+