@veraxhq/verax 0.2.1 → 0.4.0

package/src/cli/util/trust-integration-hooks.js

@@ -0,0 +1,164 @@
+/**
+ * PHASE 6B: ACTIVATION
+ * 
+ * Activates Phase 6A by enforcing it as MANDATORY for all scan paths.
+ * 
+ * This module wraps Phase 6A and integrates it with run.js to ensure:
+ * 1. All scans use Phase 6A (no bypass possible)
+ * 2. Artifacts can only be written to staging
+ * 3. Integrity is verified before commit
+ * 4. Poison markers prevent reading corrupted runs
+ */
+
+import { initPhase6A as phase6aInit, completePhase6A as phase6aComplete, rollbackPhase6A as phase6aRollback, checkPoisonMarker } from './trust-activation-integration.js';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Initialize Phase 6A (poison marker + staging directory)
+ * MANDATORY at run start - called before any artifact writing
+ * 
+ * @param {string} runDir - Run directory (e.g., .verax/runs/<runId>)
+ * @returns {Promise<{ success: boolean, error?: Error }>}
+ */
+export async function initializePhase6A(runDir) {
+  try {
+    const result = await phase6aInit(runDir);
+    return result;
+  } catch (error) {
+    return { success: false, error };
+  }
+}
+
+/**
+ * Get paths with staging directory redirection
+ * MANDATORY - replaces all artifact paths to point to staging directory
+ * 
+ * This ensures ALL artifact writes go to staging instead of final location.
+ * 
+ * @param {Object} paths - Original paths from getRunPaths()
+ * @returns {Object} Modified paths with staging redirection
+ */
+export function getStagingRedirectedPaths(paths) {
+  const stagingDir = join(paths.baseDir, '.staging');
+  
+  const redirected = { ...paths };
+  
+  // List of artifact path keys that should be redirected to staging
+  const artifactKeys = [
+    'summary', 'findings', 'ledger', 'learn', 'observe',
+    'summaryJson', 'findingsJson', 'learnJson', 'observeJson', 'ledgerJson'
+  ];
+  
+  for (const key of artifactKeys) {
+    if (redirected[key] && typeof redirected[key] === 'string') {
+      // Extract just the filename from the path (works on Windows and Unix)
+      // Split by both / and \ to handle any path separator
+      const parts = redirected[key].replace(/\\/g, '/').split('/');
+      const filename = parts[parts.length - 1];
+      
+      if (filename) {
+        // Place in staging directory
+        redirected[key] = join(stagingDir, filename);
+      }
+    }
+  }
+  
+  return redirected;
+}
+
+/**
+ * Complete Phase 6A - verify integrity and commit artifacts
+ * MANDATORY on success - generates manifest, verifies, commits staging to final
+ * 
+ * @param {string} runDir - Run directory (base, not staging)
+ * @returns {Promise<{ success: boolean, verification?: any, error?: Error }>}
+ */
+export async function completePhase6A(runDir) {
+  try {
+    const result = await phase6aComplete(runDir);
+    return result;
+  } catch (error) {
+    return { success: false, error };
+  }
+}
+
+/**
+ * Rollback Phase 6A on error
+ * MANDATORY in catch block - cleans staging but KEEPS poison marker
+ * 
+ * @param {string} runDir - Run directory (base, not staging)
+ * @returns {Promise<{ success: boolean, error?: Error }>}
+ */
+export async function rollbackPhase6A(runDir) {
+  try {
+    // Pass generic error - the phase6a module will record it
+    const error = new Error('Scan execution failed or was interrupted');
+    const result = await phase6aRollback(runDir, error);
+    return result;
+  } catch (error) {
+    return { success: false, error };
+  }
+}
+
+/**
+ * Enforce poison marker check before reading a run
+ * MANDATORY before inspect, before loading artifacts, etc
+ * 
+ * Prevents reading from incomplete/corrupted previous runs.
+ * 
+ * @param {string} runDir - Run directory
+ * @throws {Error} If poison marker exists
+ */
+export function enforcePoisonCheckBeforeRead(runDir) {
+  const poisonCheck = checkPoisonMarker(runDir);
+  
+  if (poisonCheck.hasPoisonMarker) {
+    throw new Error(
+      `Cannot read from this run: poison marker present (incomplete/corrupted run). ` +
+      `The previous scan did not complete successfully. ` +
+      `Artifacts may be incomplete or corrupted. ` +
+      `Run 'verax doctor' to diagnose.`
+    );
+  }
+  return { safe: true };
+}
+
+/**
+ * Verify artifacts before reading (check integrity manifest)
+ * RECOMMENDED before loading summary.json, findings.json, etc
+ * 
+ * @param {string} runDir - Run directory
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function verifyArtifactsBeforeRead(runDir) {
+  try {
+    // Check that integrity manifest exists (in staging directory)
+    const stagingDir = join(runDir, '.staging');
+    const manifestPath = join(stagingDir, 'integrity.manifest.json');
+    
+    if (!existsSync(manifestPath)) {
+      return {
+        ok: false,
+        error: 'Integrity manifest missing - run may be incomplete or from older version'
+      };
+    }
+    
+    // In future: verify checksums match manifest
+    
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * Check budget compliance during execution
+ * Placeholder for Phase 6C
+ * 
+ * @returns {{ ok: boolean, violations?: string[] }}
+ */
+export function checkBudgetCompliance() {
+  // Placeholder for Phase 6C
+  return { ok: true };
+}

package/src/cli/util/types.js

@@ -0,0 +1,153 @@
+/**
+ * PHASE 2: Canonical Type System for VERAX
+ * 
+ * Single source of truth for all valid types in the analysis pipeline:
+ * - EXPECTATION_TYPE: Types of expectations extracted from source code
+ * - FINDING_TYPE: Types of findings detected during analysis
+ * - SKIP_REASON: Structured reasons why expectations were skipped
+ * 
+ * Validation happens at CREATION TIME, not at enforcement time.
+ * No object may be created with an invalid type.
+ */
+
+/**
+ * Valid expectation types extracted from source code.
+ * These represent what the code is expected to do.
+ */
+export const EXPECTATION_TYPE = Object.freeze({
+  // Navigation: Expects a URL change or page navigation
+  NAVIGATION: 'navigation',
+  
+  // Network: Expects a network call to be made
+  NETWORK: 'network',
+  
+  // State: Expects a state change or promise fulfillment
+  STATE: 'state',
+});
+
+/**
+ * Valid finding types detected during analysis.
+ * These represent what the code is NOT doing that it should be.
+ */
+export const FINDING_TYPE = Object.freeze({
+  // Silent Failures: Expectation not met with no observable effect
+  SILENT_FAILURE: 'silent_failure',
+  NETWORK_SILENT_FAILURE: 'network_silent_failure',
+  VALIDATION_SILENT_FAILURE: 'validation_silent_failure',
+  FLOW_SILENT_FAILURE: 'flow_silent_failure',
+  DYNAMIC_ROUTE_SILENT_FAILURE: 'dynamic_route_silent_failure',
+  
+  // Observable Breaks: Expectation not met with visible effects
+  OBSERVED_BREAK: 'observed_break',
+  
+  // UI Feedback: Missing user feedback after action
+  MISSING_FEEDBACK_FAILURE: 'missing_feedback_failure',
+  CSS_LOADING_FEEDBACK_FAILURE: 'css_loading_feedback_failure',
+  
+  // Route Issues: Problems with dynamic route detection
+  DYNAMIC_ROUTE_MISMATCH: 'dynamic_route_mismatch',
+  
+  // Interactive: Issues with interactive elements
+  NAVIGATION_SILENT_FAILURE: 'navigation_silent_failure',
+  JOURNEY_STALL_SILENT_FAILURE: 'journey_stall_silent_failure',
+  
+  // Network: Issues with network calls
+  MISSING_NETWORK_ACTION: 'missing_network_action',
+  NETWORK_SUCCESS_NO_FEEDBACK: 'network_success_no_feedback',
+});
+
+/**
+ * Structured reasons why expectations were skipped (not analyzed).
+ * Distinguish between systemic failures and intentional filtering.
+ */
+export const SKIP_REASON = Object.freeze({
+  // Systemic Failures: Pipeline cannot continue (force INCOMPLETE state)
+  NO_EXPECTATIONS_EXTRACTED: 'NO_EXPECTATIONS_EXTRACTED',
+  TIMEOUT_OBSERVE: 'TIMEOUT_OBSERVE',
+  TIMEOUT_DETECT: 'TIMEOUT_DETECT',
+  TIMEOUT_TOTAL: 'TIMEOUT_TOTAL',
+  BUDGET_EXCEEDED: 'BUDGET_EXCEEDED',
+  MISSING_SOURCE_DIR: 'MISSING_SOURCE_DIR',
+  UNREACHABLE_URL: 'UNREACHABLE_URL',
+  
+  // Intentional Filtering: Skips that don't indicate truncation (COMPLETE is allowed)
+  DYNAMIC_ROUTE_UNSUPPORTED: 'DYNAMIC_ROUTE_UNSUPPORTED',
+  EXTERNAL_URL_SKIPPED: 'EXTERNAL_URL_SKIPPED',
+  PARSE_ERROR: 'PARSE_ERROR',
+  UNSUPPORTED_FILE: 'UNSUPPORTED_FILE',
+  OBSERVATION_FAILED: 'OBSERVATION_FAILED',
+  CONTRACT_VIOLATION: 'CONTRACT_VIOLATION',
+});
+
+/**
+ * Validate that a type string is a valid expectation type.
+ * @param {string} type - The type to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If invalid
+ */
+export function validateExpectationType(type) {
+  // @ts-expect-error - Runtime string comparison against enum values
+  if (!Object.values(EXPECTATION_TYPE).includes(type)) {
+    throw new Error(
+      `Invalid expectation type: "${type}". Must be one of: ${Object.values(EXPECTATION_TYPE).join(', ')}`
+    );
+  }
+  return true;
+}
+
+/**
+ * Validate that a type string is a valid finding type.
+ * @param {string} type - The type to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If invalid
+ */
+export function validateFindingType(type) {
+  // @ts-expect-error - Runtime string comparison against enum values
+  if (!Object.values(FINDING_TYPE).includes(type)) {
+    throw new Error(
+      `Invalid finding type: "${type}". Must be one of: ${Object.values(FINDING_TYPE).join(', ')}`
+    );
+  }
+  return true;
+}
+
+/**
+ * Validate that a reason is a valid skip reason.
+ * @param {string} reason - The reason to validate
+ * @returns {string} Normalized valid skip reason
+ * @throws {Error} If invalid and cannot be normalized
+ */
+export function validateSkipReason(reason) {
+  // CRASH GUARD: Normalize undefined/invalid reasons instead of throwing
+  if (reason === undefined || reason === null || reason === 'undefined') {
+    console.warn(`[VERAX] Invalid skip reason "${reason}" normalized to OBSERVATION_FAILED`);
+    return SKIP_REASON.OBSERVATION_FAILED;
+  }
+  
+  // @ts-expect-error - Runtime string comparison against enum values
+  if (!Object.values(SKIP_REASON).includes(reason)) {
+    console.warn(`[VERAX] Unknown skip reason "${reason}" normalized to OBSERVATION_FAILED`);
+    return SKIP_REASON.OBSERVATION_FAILED;
+  }
+  return reason;
+}
+
+/**
+ * Check if a skip reason is a systemic failure.
+ * Systemic failures force analysis state to INCOMPLETE.
+ * @param {string} reason - The skip reason
+ * @returns {boolean} True if this is a systemic failure
+ */
+export function isSystemicFailure(reason) {
+  const systemicFailures = [
+    SKIP_REASON.NO_EXPECTATIONS_EXTRACTED,
+    SKIP_REASON.TIMEOUT_OBSERVE,
+    SKIP_REASON.TIMEOUT_DETECT,
+    SKIP_REASON.TIMEOUT_TOTAL,
+    SKIP_REASON.BUDGET_EXCEEDED,
+    SKIP_REASON.MISSING_SOURCE_DIR,
+    SKIP_REASON.UNREACHABLE_URL,
+  ];
+  // @ts-expect-error - Runtime string comparison against enum values
+  return systemicFailures.includes(reason);
+}

package/src/cli/util/url-validation.js

@@ -0,0 +1,40 @@
+/**
+ * URL Validation Utilities
+ * Ensures strict URL format validation to prevent false greens
+ */
+
+export function validateUrl(urlString) {
+  if (!urlString || typeof urlString !== 'string') {
+    throw new Error('URL must be a non-empty string');
+  }
+  
+  try {
+    const url = new URL(urlString);
+    
+    // Require http or https
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw new Error(`Invalid protocol: ${url.protocol} (must be http or https)`);
+    }
+    
+    // Require hostname
+    if (!url.hostname) {
+      throw new Error('URL must include a hostname');
+    }
+    
+    // Check for localhost without port (common misconfiguration)
+    if (url.hostname === 'localhost' && !url.port) {
+      // This is OK - localhost defaults to port 80/443
+    }
+    
+    return { valid: true, url };
+  } catch (error) {
+    throw new Error(`Invalid URL: ${error.message}`);
+  }
+}
+
+export function validateFlags(flags, allowed) {
+  const invalidFlags = flags.filter(flag => !allowed.includes(flag));
+  if (invalidFlags.length > 0) {
+    throw new Error(`Unknown flag(s): ${invalidFlags.join(', ')}`);
+  }
+}

package/src/cli/util/vue-navigation-detector.js

@@ -0,0 +1,178 @@
+/**
+ * PHASE 20 — Vue Navigation Promise Detection
+ * 
+ * Detects Vue Router navigation promises:
+ * - router.push('/path'), router.replace('/path')
+ * - router.push({ name: 'X', params: { id: 1 }}) -> mark as dynamic/ambiguous
+ */
+
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+
+const traverse = _traverse.default || _traverse;
+
+/**
+ * PHASE 20: Detect Vue navigation promises
+ * 
+ * @param {string} scriptContent - Script block content
+ * @param {string} filePath - File path
+ * @param {string} relPath - Relative path
+ * @param {Object} _scriptBlock - Script block metadata
+ * @param {Object} _templateBindings - Template bindings (optional)
+ * @ts-expect-error - JSDoc params documented but unused
+ * @returns {Array} Navigation promises
+ */
+export function detectVueNavigationPromises(scriptContent, filePath, relPath, _scriptBlock, _templateBindings) {
+  const promises = [];
+  
+  try {
+    const ast = parse(scriptContent, {
+      sourceType: 'module',
+      plugins: [
+        'typescript',
+        'classProperties',
+        'optionalChaining',
+        'nullishCoalescingOperator',
+        'dynamicImport',
+        'topLevelAwait',
+        'objectRestSpread',
+      ],
+      errorRecovery: true,
+    });
+    
+    const lines = scriptContent.split('\n');
+    
+    traverse(ast, {
+      CallExpression(path) {
+        const node = path.node;
+        const callee = node.callee;
+        
+        // Detect router.push() and router.replace()
+        if (callee.type === 'MemberExpression') {
+          const object = callee.object;
+          const property = callee.property;
+          
+          if (property.name === 'push' || property.name === 'replace') {
+            // Check if object is 'router' or 'this.$router' or 'useRouter()'
+            const isRouter = 
+              (object.type === 'Identifier' && object.name === 'router') ||
+              (object.type === 'MemberExpression' && 
+               object.object.type === 'ThisExpression' && 
+               object.property.name === '$router') ||
+              (object.type === 'CallExpression' &&
+               callee.type === 'Identifier' &&
+               callee.name === 'useRouter');
+            
+            if (isRouter && node.arguments.length > 0) {
+              const arg = node.arguments[0];
+              let targetPath = null;
+              let isDynamic = false;
+              
+              // String literal: router.push('/path')
+              if (arg.type === 'StringLiteral') {
+                targetPath = arg.value;
+              }
+              // Object literal: router.push({ name: 'X', params: {} })
+              else if (arg.type === 'ObjectExpression') {
+                const nameProp = arg.properties.find(p => 
+                  p.key && p.key.name === 'name'
+                );
+                const pathProp = arg.properties.find(p => 
+                  p.key && p.key.name === 'path'
+                );
+                
+                if (pathProp && pathProp.value && pathProp.value.type === 'StringLiteral') {
+                  targetPath = pathProp.value.value;
+                } else if (nameProp) {
+                  // Named route - mark as dynamic/ambiguous
+                  isDynamic = true;
+                  targetPath = '<named-route>';
+                } else {
+                  isDynamic = true;
+                  targetPath = '<dynamic>';
+                }
+              }
+              // Template literal or other dynamic
+              else {
+                isDynamic = true;
+                targetPath = '<dynamic>';
+              }
+              
+              if (targetPath) {
+                const loc = node.loc;
+                const line = loc ? loc.start.line : 1;
+                const column = loc ? loc.start.column : 0;
+                
+                // Extract AST source
+                const astSource = lines.slice(line - 1, loc ? loc.end.line : line)
+                  .join('\n')
+                  .substring(0, 200);
+                
+                // Build context chain
+                const context = buildContext(path);
+                
+                promises.push({
+                  type: 'navigation',
+                  promise: {
+                    kind: 'navigate',
+                    value: targetPath,
+                    isDynamic,
+                  },
+                  source: {
+                    file: relPath,
+                    line,
+                    column,
+                    context,
+                    astSource,
+                  },
+                  confidence: isDynamic ? 0.7 : 1.0,
+                });
+              }
+            }
+          }
+        }
+      },
+    });
+  } catch (error) {
+    // Parse error - skip
+  }
+  
+  return promises;
+}
+
+/**
+ * Build context chain from AST path
+ */
+function buildContext(path) {
+  const context = [];
+  let current = path;
+  
+  while (current) {
+    if (current.isFunctionDeclaration()) {
+      context.push({
+        type: 'function',
+        name: current.node.id?.name || '<anonymous>',
+      });
+    } else if (current.isArrowFunctionExpression()) {
+      context.push({
+        type: 'arrow-function',
+        name: '<arrow>',
+      });
+    } else if (current.isMethodDefinition()) {
+      context.push({
+        type: 'method',
+        name: current.node.key?.name || '<method>',
+      });
+    } else if (current.isObjectProperty()) {
+      context.push({
+        type: 'property',
+        name: current.node.key?.name || '<property>',
+      });
+    }
+    
+    current = current.parentPath;
+  }
+  
+  return context.reverse().map(c => `${c.type}:${c.name}`).join(' > ');
+}
+

package/src/cli/util/vue-sfc-extractor.js

@@ -0,0 +1,161 @@
+/**
+ * PHASE 20 — Vue SFC (Single File Component) Extractor
+ * 
+ * Extracts <script>, <script setup>, and <template> content from .vue files.
+ * Deterministic and robust (no external runtime execution).
+ */
+
+/**
+ * PHASE 20: Extract Vue SFC blocks
+ * 
+ * @param {string} content - Full .vue file content
+ * @returns {Object} { scriptBlocks: [{content, lang, startLine}], template: {content, startLine} }
+ */
+export function extractVueSFC(content) {
+  const scriptBlocks = [];
+  let template = null;
+  
+  // Extract <script> blocks (including <script setup>)
+  const scriptRegex = /<script(?:\s+setup)?(?:\s+lang=["']([^"']+)["'])?[^>]*>([\s\S]*?)<\/script>/gi;
+  let scriptMatch;
+  let _lineOffset = 1;
+  
+  while ((scriptMatch = scriptRegex.exec(content)) !== null) {
+    const isSetup = scriptMatch[0].includes('setup');
+    const lang = scriptMatch[1] || 'js';
+    const scriptContent = scriptMatch[2];
+    
+    // Calculate start line
+    const beforeMatch = content.substring(0, scriptMatch.index);
+    const startLine = (beforeMatch.match(/\n/g) || []).length + 1;
+    
+    scriptBlocks.push({
+      content: scriptContent.trim(),
+      lang: lang.toLowerCase(),
+      startLine,
+      isSetup,
+    });
+  }
+  
+  // Extract <template> block
+  const templateRegex = /<template[^>]*>([\s\S]*?)<\/template>/i;
+  const templateMatch = content.match(templateRegex);
+  
+  if (templateMatch) {
+    const beforeTemplate = content.substring(0, templateMatch.index);
+    const templateStartLine = (beforeTemplate.match(/\n/g) || []).length + 1;
+    
+    template = {
+      content: templateMatch[1].trim(),
+      startLine: templateStartLine,
+    };
+  }
+  
+  return {
+    scriptBlocks,
+    template,
+  };
+}
+
+/**
+ * PHASE 20: Extract template bindings and references
+ * 
+ * @param {string} templateContent - Template content
+ * @returns {Object} { bindings: string[], routerLinks: Array, eventHandlers: Array }
+ */
+export function extractTemplateBindings(templateContent) {
+  const bindings = [];
+  const routerLinks = [];
+  const eventHandlers = [];
+  
+  // Extract variable bindings: {{ var }}, :prop="var", v-if="var", etc.
+  const bindingPatterns = [
+    /\{\{\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\}\}/g,  // {{ var }}
+    /:([a-zA-Z-]+)=["']([^"']+)["']/g,  // :prop="value"
+    /v-if=["']([^"']+)["']/g,  // v-if="condition"
+    /v-show=["']([^"']+)["']/g,  // v-show="condition"
+    /v-model=["']([^"']+)["']/g,  // v-model="value"
+  ];
+  
+  for (const pattern of bindingPatterns) {
+    let match;
+    while ((match = pattern.exec(templateContent)) !== null) {
+      const binding = match[1] || match[2];
+      if (binding && !bindings.includes(binding)) {
+        bindings.push(binding);
+      }
+    }
+  }
+  
+  // Extract <router-link> usage
+  const routerLinkRegex = /<router-link[^>]*\s+to=["']([^"']+)["'][^>]*>/gi;
+  let routerLinkMatch;
+  while ((routerLinkMatch = routerLinkRegex.exec(templateContent)) !== null) {
+    routerLinks.push({
+      to: routerLinkMatch[1],
+      fullMatch: routerLinkMatch[0],
+    });
+  }
+  
+  // Extract event handlers: @click="handler", @submit.prevent="handler"
+  const eventHandlerRegex = /@([a-z]+)(?:\.([a-z]+)*)?=["']([^"']+)["']/gi;
+  let eventMatch;
+  while ((eventMatch = eventHandlerRegex.exec(templateContent)) !== null) {
+    eventHandlers.push({
+      event: eventMatch[1],
+      modifiers: eventMatch[2] ? eventMatch[2].split('.') : [],
+      handler: eventMatch[3],
+    });
+  }
+  
+  return {
+    bindings,
+    routerLinks,
+    eventHandlers,
+  };
+}
+
+/**
+ * PHASE 20: Map template handlers to script functions
+ * 
+ * @param {Object} templateBindings - Result from extractTemplateBindings
+ * @param {Array} scriptBlocks - Script blocks from extractVueSFC
+ * @returns {Map} handlerName -> { scriptBlock, functionInfo }
+ */
+export function mapTemplateHandlersToScript(templateBindings, scriptBlocks) {
+  const handlerMap = new Map();
+  
+  for (const handler of templateBindings.eventHandlers) {
+    const handlerName = handler.handler;
+    
+    // Find handler in script blocks
+    for (const scriptBlock of scriptBlocks) {
+      const scriptContent = scriptBlock.content;
+      
+      // Look for function declarations: function handlerName() {}
+      const functionRegex = new RegExp(`(?:function|const|let|var)\\s+${handlerName}\\s*[=(]`, 'g');
+      if (functionRegex.test(scriptContent)) {
+        handlerMap.set(handlerName, {
+          scriptBlock,
+          handler,
+          type: 'function',
+        });
+        break;
+      }
+      
+      // Look for method definitions: methods: { handlerName() {} }
+      const methodRegex = new RegExp(`(?:methods|setup)\\s*:\\s*\\{[^}]*${handlerName}\\s*[:(]`, 's');
+      if (methodRegex.test(scriptContent)) {
+        handlerMap.set(handlerName, {
+          scriptBlock,
+          handler,
+          type: 'method',
+        });
+        break;
+      }
+    }
+  }
+  
+  return handlerMap;
+}
+