@veraxhq/verax 0.2.0 → 0.2.1

package/src/verax/detect/explanation-helpers.js

@@ -8,7 +8,7 @@
  * Generate a human summary - one short sentence describing what the USER experienced.
  * NO technical jargon.
  */
-export function generateHumanSummary(finding, trace) {
+export function generateHumanSummary(finding, _trace) {
   const findingType = finding.type || '';
   const interaction = finding.interaction || {};
   const label = interaction.label || interaction.text || 'the button';

package/src/verax/detect/finding-detector.js

@@ -16,7 +16,7 @@ import { hasMeaningfulUrlChange, hasVisibleChange, hasDomChange } from './compar
 import { computeConfidence } from './confidence-engine.js';
 import { generateHumanSummary, generateActionHint, deriveConfidenceExplanation } from './explanation-helpers.js';
 import { mapFindingTypeToOutcome } from '../core/canonical-outcomes.js';
-import { inferPromiseFromInteraction, PROMISE_TYPES } from '../core/promise-model.js';
+import { inferPromiseFromInteraction } from '../core/promise-model.js';
 
 /**
  * Map finding type to confidence engine type.
@@ -110,7 +110,7 @@ export function bindPromiseToFinding(finding, trace) {
  * Create finding from expectation-driven execution outcome.
  * Called when expectation execution resulted in SILENT_FAILURE.
  */
-export function createFindingFromExpectationOutcome(expectation, trace, beforeUrl, afterUrl, beforeScreenshot, afterScreenshot, projectDir, manifest) {
+export function createFindingFromExpectationOutcome(expectation, trace, beforeUrl, afterUrl, beforeScreenshot, afterScreenshot, projectDir, _manifest) {
   const interaction = trace.interaction;
   const sensors = trace.sensors || {};
   

package/src/verax/detect/findings-writer.js

@@ -1,11 +1,10 @@
-import { resolve, dirname } from 'path';
+import { resolve } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
-import { getArtifactPath } from '../core/run-id.js';
 import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
 
 /**
- * Write findings to canonical artifact root. If a runDir can be inferred,
- * write to .verax/runs/<runId>/findings.json; otherwise fall back to legacy path.
+ * Write findings to canonical artifact root.
+ * Writes to .verax/runs/<runId>/findings.json.
  * 
  * PHASE 2: Includes outcome classification summary.
  * PHASE 3: Includes promise type summary.
@@ -14,20 +13,14 @@ import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
  * @param {string} url
  * @param {Array} findings
  * @param {Array} coverageGaps
- * @param {string|null} runDirOpt - Optional absolute run directory path
+ * @param {string} runDirOpt - Required absolute run directory path
  */
-export function writeFindings(projectDir, url, findings, coverageGaps = [], runDirOpt = null) {
-  let findingsPath;
-  if (runDirOpt) {
-    // Canonical location
-    mkdirSync(runDirOpt, { recursive: true });
-    findingsPath = resolve(runDirOpt, 'findings.json');
-  } else {
-    // Legacy location for backward compatibility (tests without runId)
-    const detectDir = resolve(projectDir, '.veraxverax', 'detect');
-    mkdirSync(detectDir, { recursive: true });
-    findingsPath = resolve(detectDir, 'findings.json');
+export function writeFindings(projectDir, url, findings, coverageGaps = [], runDirOpt) {
+  if (!runDirOpt) {
+    throw new Error('runDirOpt is required');
   }
+  mkdirSync(runDirOpt, { recursive: true });
+  const findingsPath = resolve(runDirOpt, 'findings.json');
 
   // PHASE 2: Compute outcome summary
   const outcomeSummary = {};

package/src/verax/detect/flow-detector.js

@@ -133,9 +133,9 @@ export function detectFlowSilentFailures(traces, manifest, findings, coverageGap
     }
 
     // Look for silent failures followed by lack of recovery
-    let hasSilentFailure = false;
+    const _hasSilentFailure = false;
     let failedStepIndex = -1;
-    let failedExpectation = null;
+    const _failedExpectation = null;
 
     for (let i = 0; i < flowTraces.length; i++) {
       const trace = flowTraces[i];
@@ -248,9 +248,9 @@ export function detectFlowSilentFailures(traces, manifest, findings, coverageGap
 
       if (isSilentFailure && matchedExpectation) {
         // Silent failure detected at this step
-        hasSilentFailure = true;
+        const _hasSilentFailure = true;
         failedStepIndex = i;
-        failedExpectation = matchedExpectation;
+        const _failedExpectation = matchedExpectation;
 
         // Check if subsequent steps show UI recovery
         let hasSubsequentRecovery = false;

package/src/verax/detect/index.js

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync } from 'fs';
-import { dirname } from 'path';
+import { dirname, basename } from 'path';
 import { expectsNavigation } from './expectation-model.js';
 import { hasMeaningfulUrlChange, hasVisibleChange, hasDomChange } from './comparison.js';
 import { writeFindings } from './findings-writer.js';
@@ -7,7 +7,13 @@ import { getUrlPath } from './evidence-validator.js';
 import { classifySkipReason, collectSkipReasons } from './skip-classifier.js';
 import { detectInteractiveFindings } from './interactive-findings.js';
 
-export async function detect(manifestPath, tracesPath, validation = null) {
+/**
+ * @param {string} manifestPath
+ * @param {string} tracesPath
+ * @param {Object} [validation]
+ * @returns {Promise<any>}
+ */
+export async function detect(manifestPath, tracesPath, validation = null, _expectationCoverageGaps = null, _silenceTracker = null) {
   if (!existsSync(manifestPath)) {
     throw new Error(`Manifest not found: ${manifestPath}`);
   }
@@ -25,8 +31,21 @@ export async function detect(manifestPath, tracesPath, validation = null) {
   const projectDir = manifest.projectDir;
   const findings = [];
   
+  // Extract runId from tracesPath: .verax/runs/<runId>/observation-traces.json
+  let runId = null;
+  try {
+    const runDir = dirname(tracesPath);
+    const runDirBasename = basename(runDir);
+    // Check if runDir is in .verax/runs/<runId> structure
+    const parentDir = dirname(runDir);
+    if (basename(parentDir) === 'runs' && basename(dirname(parentDir)) === '.verax') {
+      runId = runDirBasename;
+    }
+  } catch {
+    // Ignore path parsing errors
+  }
+  
   let interactionsAnalyzed = 0;
-  let interactionsSkippedNoExpectation = 0;
   const skips = [];
   
   for (const trace of observation.traces) {
@@ -39,7 +58,6 @@ export async function detect(manifestPath, tracesPath, validation = null) {
     const expectsNav = expectsNavigation(manifest, interaction, beforeUrl);
     
     if (!expectsNav) {
-      interactionsSkippedNoExpectation++;
       const skipReason = classifySkipReason(manifest, interaction, beforeUrl, validation);
       if (skipReason) {
         skips.push({
@@ -73,8 +91,8 @@ export async function detect(manifestPath, tracesPath, validation = null) {
             const interactionSelector = interaction.selector || '';
             
             if (selectorHint && interactionSelector) {
-              const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
-              const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
+              const normalizedSelectorHint = selectorHint.replace(/[[\]()]/g, '');
+              const normalizedInteractionSelector = interactionSelector.replace(/[[\]()]/g, '');
               
               if (selectorHint === interactionSelector || 
                   selectorHint.includes(interactionSelector) || 
@@ -117,7 +135,6 @@ export async function detect(manifestPath, tracesPath, validation = null) {
               label: interaction.label
             }
           });
-          interactionsSkippedNoExpectation++;
           continue;
         }
       }
@@ -161,7 +178,6 @@ export async function detect(manifestPath, tracesPath, validation = null) {
               label: interaction.label
             }
           });
-          interactionsSkippedNoExpectation++;
           continue;
         } else if (matchingRoutes.length === 1) {
           expectedTargetPath = matchingRoutes[0];
@@ -180,14 +196,22 @@ export async function detect(manifestPath, tracesPath, validation = null) {
           label: interaction.label
         }
       });
-      interactionsSkippedNoExpectation++;
       continue;
     }
     
     interactionsAnalyzed++;
     
     const hasUrlChange = hasMeaningfulUrlChange(beforeUrl, afterUrl);
-    const hasVisibleChangeResult = hasVisibleChange(beforeScreenshot, afterScreenshot, projectDir);
+    // hasVisibleChange requires runId, skip comparison if runId unavailable
+    let hasVisibleChangeResult = false;
+    if (runId) {
+      try {
+        hasVisibleChangeResult = hasVisibleChange(beforeScreenshot, afterScreenshot, projectDir, runId);
+      } catch (e) {
+        // If screenshot comparison fails, treat as no visible change
+        hasVisibleChangeResult = false;
+      }
+    }
     const hasDomChangeResult = hasDomChange(trace);
     
     if (expectedTargetPath) {
@@ -263,7 +287,9 @@ export async function detect(manifestPath, tracesPath, validation = null) {
   let runDir = null;
   try {
     runDir = dirname(tracesPath);
-  } catch {}
+  } catch {
+    // Ignore path parsing errors
+  }
 
   const findingsResult = writeFindings(projectDir, observation.url, findings, [], runDir);
   

package/src/verax/detect/interactive-findings.js

@@ -2,7 +2,7 @@
 // Handles keyboard, hover, file_upload, login, logout, auth_guard interactions
 // Plus accessibility detections: focus, ARIA, keyboard trap, feedback gap, freeze
 
-import { hasMeaningfulUrlChange, hasVisibleChange, hasDomChange } from './comparison.js';
+import { hasMeaningfulUrlChange, hasDomChange } from './comparison.js';
 import { computeConfidence } from './confidence-engine.js';
 import { enrichFindingWithExplanations } from './finding-detector.js';
 
@@ -14,10 +14,9 @@ import { enrichFindingWithExplanations } from './finding-detector.js';
  * @param {Array} traces - Interaction traces to analyze
  * @param {Object} manifest - Project manifest (not used currently)
  * @param {Array} findings - Findings array to append to
- * @param {Object} helpers - Helper functions (not used currently)
  * @returns {Array} Array of detected interactive findings
  */
-export function detectInteractiveFindings(traces, manifest, findings, helpers = {}) {
+export function detectInteractiveFindings(traces, manifest, findings, _helpers = {}) {
   const interactiveFindings = [];
 
   for (const trace of traces) {
@@ -165,7 +164,7 @@ export function detectInteractiveFindings(traces, manifest, findings, helpers =
       const domChanged = hasDomChange(trace);
       const urlChanged = hasMeaningfulUrlChange(beforeUrl, afterUrl);
       const network = sensors.network || {};
-      const hasNetwork = (network.totalRequests || 0) > 0;
+      const _hasNetwork = (network.totalRequests || 0) > 0;
       const loading = sensors.loading || {};
       const stateData = sensors.state || {};
 

package/src/verax/detect/signal-mapper.js

@@ -136,8 +136,8 @@ export function mapOwnership(finding, trace = {}) {
   const findingType = finding.type || 'unknown';
   const sensors = trace.sensors || {};
   const hasNetwork = (sensors.network?.totalRequests || 0) > 0;
-  const hasAria = sensors.aria !== undefined;
-  const hasFocus = sensors.focus !== undefined;
+  const _hasAria = sensors.aria !== undefined;
+  const _hasFocus = sensors.focus !== undefined;
   const hasTiming = sensors.timing !== undefined;
   
   // ACCESSIBILITY: Focus, ARIA, keyboard trap failures

package/src/verax/detect/skip-classifier.js

@@ -54,8 +54,8 @@ export function classifySkipReason(manifest, interaction, beforeUrl, validation
           const interactionSelector = interaction.selector || '';
           
           if (selectorHint && interactionSelector) {
-            const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
-            const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
+            const normalizedSelectorHint = selectorHint.replace(/[[\]()]/g, '');
+            const normalizedInteractionSelector = interactionSelector.replace(/[[\]()]/g, '');
             
             if (selectorHint === interactionSelector || 
                 selectorHint.includes(interactionSelector) || 
@@ -76,8 +76,8 @@ export function classifySkipReason(manifest, interaction, beforeUrl, validation
           const interactionSelector = interaction.selector || '';
           
           if (selectorHint && interactionSelector) {
-            const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
-            const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
+            const normalizedSelectorHint = selectorHint.replace(/[[\]()]/g, '');
+            const normalizedInteractionSelector = interactionSelector.replace(/[[\]()]/g, '');
             
             if (selectorHint === interactionSelector || 
                 selectorHint.includes(interactionSelector) || 

package/src/verax/detect/verdict-engine.js

@@ -14,9 +14,7 @@
  * PHASE 4: All observations include Silence lifecycle - type, trigger, evaluation status, confidence impact.
  */
 
-import fs from 'fs';
-import path from 'path';
-import { buildEvidenceIndex, writeEvidenceIndex } from './evidence-index.js';
+import { buildEvidenceIndex } from './evidence-index.js';
 import { CANONICAL_OUTCOMES } from '../core/canonical-outcomes.js';
 import { SILENCE_TYPES, EVALUATION_STATUS } from '../core/silence-model.js';
 import { inferPromiseFromInteraction } from '../core/promise-model.js';
@@ -74,7 +72,7 @@ export function computeObservationSummary(findings, observeTruth, learnTruth, co
     const outcome = finding.outcome || CANONICAL_OUTCOMES.SILENT_FAILURE;  // Default for legacy findings
     const promiseType = finding.promise?.type || 'UNKNOWN_PROMISE';  // PHASE 3
     
-    if (findingsByConfidence.hasOwnProperty(confidence)) {
+    if (Object.prototype.hasOwnProperty.call(findingsByConfidence, confidence)) {
       findingsByConfidence[confidence]++;
     }
     findingsByType[type] = (findingsByType[type] || 0) + 1;
@@ -402,7 +400,7 @@ export function formatObservationSummary(observationSummary) {
     for (const finding of obs.findings.slice(0, 3)) {
       const outcome = finding.outcome ? ` [${finding.outcome}]` : '';
       const promiseInfo = finding.promise ? ` (${finding.promise.type.replace(/_PROMISE$/, '')})` : '';
-      const confStr = finding.confidence?.level ? ` (${finding.confidence.level} confidence)` : '';
+      const _confStr = finding.confidence?.level ? ` (${finding.confidence.level} confidence)` : '';
       const userStmt = finding.what_happened ? `User: ${finding.what_happened}` : '';
       lines.push(`  • ${finding.type}${outcome}${promiseInfo}`);
       if (userStmt) lines.push(`    ${userStmt}`);
@@ -454,7 +452,7 @@ export function formatObservationSummary(observationSummary) {
 export function inferPromiseForSilence(silence) {
   if (!silence) return null;
   
-  const { silence_type, scope, reason, context } = silence;
+  const { silence_type, scope: _scope, reason, context } = silence;
   
   // Navigation-related silences
   if (silence_type === SILENCE_TYPES.NAVIGATION_TIMEOUT || 

package/src/verax/flow/flow-engine.js

@@ -63,7 +63,7 @@ export async function executeFlow(page, spec, sensors = {}) {
   };
 }
 
-async function executeStep(page, step, idx, spec, sensors, secretValues) {
+async function executeStep(page, step, idx, spec, _sensors, _secretValues) {
   const baseResult = {
     stepIndex: idx,
     type: step.type,
@@ -131,7 +131,8 @@ async function stepGoto(page, step, result, spec) {
     return result;
   }
 
-  await page.goto(url, { waitUntil: 'networkidle' });
+  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+  await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
   await waitForSettle(page, { timeoutMs: 3000, settleMs: 500 });
 
   result.success = true;

package/src/verax/flow/flow-spec.js

@@ -111,10 +111,9 @@ export function validateFlowSpec(spec) {
  * Returns actual value or throws if not found.
  *
  * @param {string} value - String containing $ENV:VARNAME references
- * @param {Object} secrets - Map of secret keys to env var names
  * @returns {string} - Resolved value
  */
-export function resolveSecrets(value, secrets = {}) {
+export function resolveSecrets(value, _secrets = {}) {
   if (typeof value !== 'string') return value;
 
   // Replace $ENV:VARNAME with actual env var value

package/src/verax/index.js

@@ -53,8 +53,18 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     manifestPath: manifest.manifestPath
   };
   
-  const validation = await validateRoutes(manifestForValidation, url);
-  
+  let validation = await validateRoutes(manifestForValidation, url);
+  
+  if (!validation) {
+    // validateRoutes might return null if routes cannot be validated
+    validation = { 
+      routesValidated: 0, 
+      routesReachable: 0, 
+      routesUnreachable: 0, 
+      details: [], 
+      warnings: []
+    };
+  }
   if (validation.warnings && validation.warnings.length > 0) {
     if (!manifest.learnTruth.warnings) {
       manifest.learnTruth.warnings = [];
@@ -94,7 +104,9 @@ export async function scan(projectDir, url, manifestPath = null, scanBudgetOverr
     const { writeFileSync } = await import('fs');
     const manifestCopyPath = getArtifactPath(projectDir, runId, 'manifest.json');
     writeFileSync(manifestCopyPath, JSON.stringify(manifest, null, 2));
-  } catch {}
+  } catch {
+    // Ignore write errors
+  }
   
   // Create silence tracker from observation silences
   const silenceTracker = new SilenceTracker();

package/src/verax/intel/effect-detector.js

@@ -65,7 +65,7 @@ function analyzeNode(node, sourceFile, projectRoot, eventType = null) {
   // VALIDATION INTELLIGENCE v1: Check for return false in submit context
   if (ts.isReturnStatement(node) && eventType === 'onSubmit') {
     const expression = node.expression;
-    if (expression && ts.isFalseKeyword(expression)) {
+    if (expression && expression.kind === ts.SyntaxKind.FalseKeyword) {
       const location = getNodeLocation(sourceFile, node, projectRoot);
       return {
         type: 'validation_block',

package/src/verax/intel/index.js

@@ -122,7 +122,7 @@ export async function runCodeIntelligence(projectRoot) {
         matchAttribute: el.attrs.to ? 'to' : (el.attrs.href ? 'href' : null),
         proof: 'PROVEN_EXPECTATION',
         sourceRef: el.sourceRef,
-        selectorHint: extractSelectorHint({ attributes: { properties: [] } }) || `${el.tag}`,
+        selectorHint: extractSelectorHint(/** @type {any} */ ({ attributes: { properties: [] } })) || `${el.tag}`,
         metadata: {
           elementFile: el.file,
           elementLine: el.line,
@@ -267,7 +267,7 @@ function generateExpectation(mapping, effect) {
  * @param {Object} effect - Effect object
  * @returns {string} - Expectation type
  */
-function determineExpectationType(effect) {
+function _determineExpectationType(effect) {
   switch (effect.type) {
     case 'navigation':
       return 'navigation';

package/src/verax/intel/route-extractor.js

@@ -12,9 +12,9 @@
  */
 
 import ts from 'typescript';
-import { resolve, relative, sep, basename, dirname, extname } from 'path';
+import { resolve, relative, basename, extname } from 'path';
 import { existsSync, readdirSync, statSync } from 'fs';
-import { parseFile, findNodes, getStringLiteral, getNodeLocation } from './ts-program.js';
+import { parseFile, findNodes, getNodeLocation } from './ts-program.js';
 import { extractVueRoutes } from './vue-router-extractor.js';
 import { normalizeDynamicRoute } from '../shared/dynamic-route-utils.js';
 
@@ -27,7 +27,7 @@ const INTERNAL_PATH_PATTERNS = [
   /\/private/
 ];
 
-function isInternalRoute(path) {
+function _isInternalRoute(path) {
   return INTERNAL_PATH_PATTERNS.some(pattern => pattern.test(path));
 }