@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/execution-mode-detector.js

@@ -0,0 +1,192 @@
+/**
+ * EXECUTION MODE DETECTOR
+ * 
+ * Automatically detects whether VERAX is running in:
+ * 1. PROJECT_SCAN: Local source code is available for analysis
+ * 2. WEB_SCAN_LIMITED: Only URL provided, no source code available
+ * 
+ * This determines:
+ * - What analysis techniques can be used
+ * - Maximum confidence ceiling (0.45 for WEB_SCAN_LIMITED)
+ * - What explanations to provide to users
+ * 
+ * PRINCIPLES:
+ * - Detection is automatic and implicit (no user configuration needed)
+ * - Behavior changes based on what's available, not explicit flags
+ * - Users understand limitations from generated explanations
+ */
+
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join as _join } from 'path';
+
+/**
+ * Execution mode constants
+ */
+export const EXECUTION_MODES = {
+  PROJECT_SCAN: 'PROJECT_SCAN',           // Full analysis with source code
+  WEB_SCAN_LIMITED: 'WEB_SCAN_LIMITED'    // URL-only analysis without source
+};
+
+/**
+ * Confidence ceiling by mode
+ */
+export const CONFIDENCE_CEILINGS = {
+  [EXECUTION_MODES.PROJECT_SCAN]: 1.0,      // No ceiling, full range [0, 1]
+  [EXECUTION_MODES.WEB_SCAN_LIMITED]: 0.45  // Limited to 45% max confidence
+};
+
+/**
+ * Detect execution mode based on available inputs
+ * @param {string} srcPath - Path to source code directory
+ * @param {string} _url - Target URL
+ * @ts-expect-error - JSDoc param documented but unused
+ * @returns {Object} - { mode, ceiling, explanation }
+ */
+export function detectExecutionMode(srcPath, _url) {
+  // Check if source code is available and viable
+  const hasSourceCode = isSourceCodeAvailable(srcPath);
+  
+  if (hasSourceCode) {
+    return {
+      mode: EXECUTION_MODES.PROJECT_SCAN,
+      ceiling: CONFIDENCE_CEILINGS[EXECUTION_MODES.PROJECT_SCAN],
+      explanation: 'Full project analysis: source code is available for static analysis, expectations extraction, and dynamic behavior correlation.',
+      reason: 'Source code detected at ' + srcPath
+    };
+  } else {
+    return {
+      mode: EXECUTION_MODES.WEB_SCAN_LIMITED,
+      ceiling: CONFIDENCE_CEILINGS[EXECUTION_MODES.WEB_SCAN_LIMITED],
+      explanation: 'Limited web scan: no local source code available. Analysis is based solely on runtime behavior observation. Confidence is capped at 45% due to inability to correlate with code-level expectations.',
+      reason: 'No source code available; analyzing runtime behavior only'
+    };
+  }
+}
+
+/**
+ * Check if source code is available and viable for analysis
+ * @param {string} srcPath - Path to source code directory
+ * @returns {boolean} - True if source code appears to be available
+ */
+function isSourceCodeAvailable(srcPath) {
+  // Check if path exists
+  if (!existsSync(srcPath)) {
+    return false;
+  }
+  
+  // Check if it's a directory
+  try {
+    const stats = statSync(srcPath);
+    if (!stats.isDirectory()) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+  
+  // Check for minimum viable source indicators
+  return hasSourceIndicators(srcPath);
+}
+
+/**
+ * Check for presence of source code indicators
+ * @param {string} srcPath - Path to potential source directory
+ * @returns {boolean} - True if source indicators are present
+ */
+function hasSourceIndicators(srcPath) {
+  try {
+    const entries = readdirSync(srcPath, { withFileTypes: true });
+    
+    // Look for common source code patterns
+    const indicators = {
+      hasJs: false,      // .js, .jsx, .ts, .tsx files
+      hasSrc: false,     // src/ directory
+      hasPackageJson: false,
+      hasPythonFiles: false,
+      hasGoFiles: false
+    };
+    
+    for (const entry of entries) {
+      const name = entry.name;
+      const lowerName = name.toLowerCase();
+      
+      // Check for source directories
+      if (entry.isDirectory() && 
+          (lowerName === 'src' || lowerName === 'lib' || lowerName === 'app' || 
+           lowerName === 'pages' || lowerName === 'components' || lowerName === 'python')) {
+        indicators.hasSrc = true;
+      }
+      
+      // Check for package.json (Node.js projects)
+      if (name === 'package.json') {
+        indicators.hasPackageJson = true;
+      }
+      
+      // Check for JS/TS files
+      if (lowerName.endsWith('.js') || lowerName.endsWith('.jsx') || 
+          lowerName.endsWith('.ts') || lowerName.endsWith('.tsx') ||
+          lowerName.endsWith('.mjs') || lowerName.endsWith('.cjs')) {
+        indicators.hasJs = true;
+      }
+      
+      // Check for Python files
+      if (lowerName.endsWith('.py')) {
+        indicators.hasPythonFiles = true;
+      }
+      
+      // Check for Go files
+      if (lowerName.endsWith('.go')) {
+        indicators.hasGoFiles = true;
+      }
+    }
+    
+    // Multiple indicators needed to confirm source code is present
+    const indicatorCount = Object.values(indicators).filter(Boolean).length;
+    return indicatorCount >= 2; // Need at least 2 indicators
+    
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Apply confidence ceiling to a score
+ * @param {number} score - Confidence score (0..1 float)
+ * @param {string} mode - Execution mode
+ * @returns {number} - Capped confidence score (0..1 float)
+ */
+export function applyConfidenceCeiling(score, mode) {
+  const ceiling = CONFIDENCE_CEILINGS[mode] || 1.0;
+  return Math.min(score, ceiling);
+}
+
+/**
+ * Generate execution mode explanation for output
+ * @param {string} mode - Execution mode
+ * @param {string} ceiling - Confidence ceiling
+ * @returns {string} - Human-readable explanation
+ */
+export function generateModeExplanation(mode, ceiling) {
+  switch (mode) {
+    case EXECUTION_MODES.PROJECT_SCAN:
+      return `Running in PROJECT_SCAN mode. Full analysis enabled with source code available.`;
+    
+    case EXECUTION_MODES.WEB_SCAN_LIMITED:
+      // @ts-expect-error - Arithmetic on constant
+      return `Running in WEB_SCAN_LIMITED mode. No source code available; analysis limited to runtime observation. Confidence capped at ${Math.round(ceiling * 100)}%.`;
+    
+    default:
+      return 'Execution mode unknown.';
+  }
+}
+
+/**
+ * Format execution mode info for CLI output
+ * @param {Object} modeInfo - Result from detectExecutionMode()
+ * @returns {string} - Formatted text for console output
+ */
+export function formatModeForOutput(modeInfo) {
+  return `Execution Mode: ${modeInfo.mode}
+Confidence Ceiling: ${Math.round(modeInfo.ceiling * 100)}%
+Reason: ${modeInfo.reason}`;
+}

package/src/verax/core/failures/exit-codes.js

@@ -0,0 +1,88 @@
+/**
+ * Exit Codes Contract v1
+ * 
+ * Exit codes with explicit precedence (highest wins):
+ * - 64: USAGE ERROR (invalid CLI usage)
+ * - 2:  TOOL FAILURE (crash, invariant, runtime error)
+ * - 20: FAILURE (any CONFIRMED finding)
+ * - 10: WARNING (only SUSPECTED/INFORMATIONAL findings)
+ * - 0:  OK (no CONFIRMED findings)
+ */
+
+import { FAILURE_SEVERITY as _FAILURE_SEVERITY } from './failure.types.js';
+
+/**
+ * Exit Code Constants (Contract v1)
+ */
+export const EXIT_CODE = {
+  OK: 0,                       // No CONFIRMED findings
+  WARNING: 10,                 // Only SUSPECTED/INFORMATIONAL
+  FAILURE: 20,                 // Any CONFIRMED finding
+  TOOL_FAILURE: 2,             // Crash, invariant, runtime error
+  USAGE_ERROR: 64              // Invalid CLI usage
+};
+
+/**
+ * Determine exit code with precedence (highest wins)
+ * Precedence: 64 > 2 > 20 > 10 > 0
+ * 
+ * @param {Object} ledgerSummary - Failure ledger summary
+ * @param {string} _determinismVerdict - Determinism verdict
+ * @ts-expect-error - JSDoc param documented but unused
+ * @param {boolean} evidenceLawViolated - Whether Evidence Law was violated
+ * @param {boolean} policyInvalid - Whether policy was invalid
+ * @returns {number} Exit code
+ */
+export function determineExitCode(ledgerSummary, _determinismVerdict = null, evidenceLawViolated = false, policyInvalid = false) {
+  // Precedence 1: USAGE ERROR (64)
+  if (policyInvalid) {
+    return EXIT_CODE.USAGE_ERROR;
+  }
+  
+  // Precedence 2: TOOL FAILURE (2) - Internal corruption or contract violations
+  const hasInternalCorruption = ledgerSummary.byCategory?.INTERNAL > 0 ||
+                                 ledgerSummary.byCategory?.CONTRACT > 0;
+  if (hasInternalCorruption) {
+    return EXIT_CODE.TOOL_FAILURE;
+  }
+  
+  // Precedence 2: TOOL FAILURE (2) - BLOCKING failures
+  if (ledgerSummary.bySeverity?.BLOCKING > 0) {
+    return EXIT_CODE.TOOL_FAILURE;
+  }
+  
+  // Precedence 2: TOOL FAILURE (2) - DEGRADED failures
+  if (ledgerSummary.bySeverity?.DEGRADED > 0) {
+    return EXIT_CODE.TOOL_FAILURE;
+  }
+  
+  // Precedence 2: TOOL FAILURE (2) - Evidence Law violation
+  if (evidenceLawViolated) {
+    return EXIT_CODE.TOOL_FAILURE;
+  }
+  
+  // Note: Precedence 3-5 (FAILURE/WARNING/OK) handled by run-result.js
+  // This function handles system failures only
+  
+  // No system failures → delegate to findings-based logic
+  return EXIT_CODE.OK;
+}
+
+/**
+ * Get exit code meaning
+ * 
+ * @param {number} exitCode - Exit code
+ * @returns {string} Human-readable meaning
+ */
+export function getExitCodeMeaning(exitCode) {
+  const meanings = {
+    [EXIT_CODE.OK]: 'OK (no CONFIRMED findings)',
+    [EXIT_CODE.WARNING]: 'WARNING (only SUSPECTED/INFORMATIONAL findings)',
+    [EXIT_CODE.FAILURE]: 'FAILURE (CONFIRMED finding detected)',
+    [EXIT_CODE.TOOL_FAILURE]: 'TOOL FAILURE (crash, invariant, or runtime error)',
+    [EXIT_CODE.USAGE_ERROR]: 'USAGE ERROR (invalid CLI usage)'
+  };
+  
+  return meanings[exitCode] || `Unknown exit code: ${exitCode}`;
+}
+

package/src/verax/core/failures/failure-summary.js

@@ -0,0 +1,76 @@
+/**
+ * PHASE 21.5 — Failure Summary Formatter
+ * 
+ * Formats failure summaries for CLI output.
+ */
+
+import { determineExitCode, getExitCodeMeaning as _getExitCodeMeaning } from './exit-codes.js';
+
+/**
+ * Format failure summary for CLI
+ * 
+ * @param {Object} ledgerSummary - Failure ledger summary
+ * @param {string} determinismVerdict - Determinism verdict
+ * @param {boolean} evidenceLawViolated - Whether Evidence Law was violated
+ * @param {string} ledgerPath - Path to failure ledger file
+ * @returns {string} Formatted summary
+ */
+export function formatFailureSummary(ledgerSummary, determinismVerdict = null, evidenceLawViolated = false, ledgerPath = null) {
+  const lines = [];
+  
+  lines.push('\n═══════════════════════════════════════');
+  lines.push('EXECUTION VERDICT');
+  lines.push('═══════════════════════════════════════');
+  
+  // Determine verdict
+  const highestSeverity = ledgerSummary.highestSeverity;
+  let verdict = 'CLEAN';
+  if (highestSeverity === 'BLOCKING') {
+    verdict = 'BLOCKING';
+  } else if (highestSeverity === 'DEGRADED') {
+    verdict = 'DEGRADED';
+  } else if (highestSeverity === 'WARNING') {
+    verdict = 'WARNINGS';
+  }
+  
+  lines.push(`Verdict: ${verdict}`);
+  
+  // Determinism verdict
+  if (determinismVerdict) {
+    lines.push(`Deterministic: ${determinismVerdict === 'DETERMINISTIC' ? 'YES' : 'NO'}`);
+  } else {
+    lines.push('Deterministic: UNKNOWN');
+  }
+  
+  // Evidence Law status
+  lines.push(`Evidence Law: ${evidenceLawViolated ? 'VIOLATED' : 'ENFORCED'}`);
+  
+  // Failure summary
+  lines.push('');
+  lines.push('Failures:');
+  lines.push(`  BLOCKING: ${ledgerSummary.bySeverity?.BLOCKING || 0}`);
+  lines.push(`  DEGRADED: ${ledgerSummary.bySeverity?.DEGRADED || 0}`);
+  lines.push(`  WARNING: ${ledgerSummary.bySeverity?.WARNING || 0}`);
+  
+  // Ledger path
+  if (ledgerPath) {
+    lines.push('');
+    lines.push(`See: ${ledgerPath}`);
+  }
+  
+  return lines.join('\n');
+}
+
+/**
+ * Get exit code from failure ledger and system state
+ * 
+ * @param {Object} ledgerSummary - Failure ledger summary
+ * @param {string} determinismVerdict - Determinism verdict
+ * @param {boolean} evidenceLawViolated - Whether Evidence Law was violated
+ * @param {boolean} policyInvalid - Whether policy was invalid
+ * @returns {number} Exit code
+ */
+export function getExitCodeFromLedger(ledgerSummary, determinismVerdict = null, evidenceLawViolated = false, policyInvalid = false) {
+  return determineExitCode(ledgerSummary, determinismVerdict, evidenceLawViolated, policyInvalid);
+}
+

package/src/verax/core/failures/failure.factory.js

@@ -0,0 +1,225 @@
+/**
+ * PHASE 21.5 — Failure Factory
+ * 
+ * Creates properly classified failure objects.
+ * No ad-hoc error creation allowed.
+ */
+
+import { FAILURE_CODE as _FAILURE_CODE, FAILURE_CATEGORY, FAILURE_SEVERITY, EXECUTION_PHASE, validateFailure } from './failure.types.js';
+
+/**
+ * Create a failure object
+ * 
+ * @param {Object} params
+ * @param {string} params.code - Failure code
+ * @param {string} params.category - Failure category
+ * @param {string} params.severity - Failure severity
+ * @param {string} params.phase - Execution phase
+ * @param {boolean} params.isRecoverable - Whether recoverable
+ * @param {string} params.message - Human-readable message
+ * @param {string} params.component - Component name
+ * @param {Object} [params.context] - Additional context
+ * @param {string} [params.stack] - Stack trace
+ * @param {string} [params.recoveryAction] - Recovery action
+ * @param {string} [params.impact] - Impact description
+ * @returns {Object} Validated failure object
+ */
+export function createFailure(params) {
+  const {
+    code,
+    category,
+    severity,
+    phase,
+    isRecoverable,
+    message,
+    component,
+    context = {},
+    stack = null,
+    recoveryAction = null,
+    impact = null
+  } = params;
+  
+  const failure = {
+    code,
+    category,
+    severity,
+    phase,
+    isRecoverable,
+    message,
+    component,
+    timestamp: Date.now(),
+    context,
+    ...(stack && { stack }),
+    ...(recoveryAction && { recoveryAction }),
+    ...(impact && { impact })
+  };
+  
+  validateFailure(failure);
+  return failure;
+}
+
+/**
+ * Create evidence law failure
+ */
+export function createEvidenceFailure(code, message, component, context = {}) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.EVIDENCE,
+    severity: FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.DETECT,
+    isRecoverable: false,
+    message,
+    component,
+    context,
+    impact: 'Cannot produce CONFIRMED findings without complete evidence'
+  });
+}
+
+/**
+ * Create determinism failure
+ */
+export function createDeterminismFailure(code, message, component, context = {}) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.DETERMINISM,
+    severity: FAILURE_SEVERITY.DEGRADED,
+    phase: EXECUTION_PHASE.OBSERVE,
+    isRecoverable: false,
+    message,
+    component,
+    context,
+    impact: 'Determinism verdict downgraded to NON_DETERMINISTIC'
+  });
+}
+
+/**
+ * Create observation failure
+ */
+export function createObserveFailure(code, message, component, context = {}, isRecoverable = false) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.OBSERVE,
+    severity: isRecoverable ? FAILURE_SEVERITY.DEGRADED : FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.OBSERVE,
+    isRecoverable,
+    message,
+    component,
+    context
+  });
+}
+
+/**
+ * Create detection failure
+ */
+export function createDetectFailure(code, message, component, context = {}, isRecoverable = false) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.DETECT,
+    severity: isRecoverable ? FAILURE_SEVERITY.DEGRADED : FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.DETECT,
+    isRecoverable,
+    message,
+    component,
+    context
+  });
+}
+
+/**
+ * Create I/O failure
+ */
+export function createIOFailure(code, message, component, context = {}, isRecoverable = false) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.IO,
+    severity: isRecoverable ? FAILURE_SEVERITY.WARNING : FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.REPORT,
+    isRecoverable,
+    message,
+    component,
+    context
+  });
+}
+
+/**
+ * Create policy failure
+ */
+export function createPolicyFailure(code, message, component, context = {}) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.POLICY,
+    severity: FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.DETECT,
+    isRecoverable: false,
+    message,
+    component,
+    context,
+    impact: 'Invalid policy prevents execution'
+  });
+}
+
+/**
+ * Create contract failure
+ */
+export function createContractFailure(code, message, component, context = {}, stack = null) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.CONTRACT,
+    severity: FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.DETECT,
+    isRecoverable: false,
+    message,
+    component,
+    context,
+    stack,
+    impact: 'Invariant violation - system integrity compromised'
+  });
+}
+
+/**
+ * Create internal failure
+ */
+export function createInternalFailure(code, message, component, context = {}, stack = null) {
+  return createFailure({
+    code,
+    category: FAILURE_CATEGORY.INTERNAL,
+    severity: FAILURE_SEVERITY.BLOCKING,
+    phase: EXECUTION_PHASE.DETECT,
+    isRecoverable: false,
+    message,
+    component,
+    context,
+    stack,
+    impact: 'Internal error - system state may be corrupted'
+  });
+}
+
+/**
+ * Convert error to failure
+ * 
+ * @param {Error} error - JavaScript error
+ * @param {string} code - Failure code
+ * @param {string} category - Failure category
+ * @param {string} phase - Execution phase
+ * @param {string} component - Component name
+ * @param {Object} context - Additional context
+ * @returns {Object} Failure object
+ */
+export function errorToFailure(error, code, category, phase, component, context = {}) {
+  return createFailure({
+    code,
+    category,
+    severity: FAILURE_SEVERITY.BLOCKING,
+    phase,
+    isRecoverable: false,
+    message: error.message || 'Unexpected error',
+    component,
+    context: {
+      ...context,
+      errorName: error.name,
+      errorType: error.constructor?.name
+    },
+    stack: error.stack || null,
+    impact: 'Unexpected error - execution may be incomplete'
+  });
+}
+

package/src/verax/core/failures/failure.ledger.js

@@ -0,0 +1,133 @@
+/**
+ * PHASE 21.5 — Failure Ledger
+ * 
+ * Enterprise artifact that records all failures (even recovered ones).
+ * Deterministic, append-only, never missing.
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname as _dirname } from 'path';
+import { validateFailure } from './failure.types.js';
+
+/**
+ * Failure Ledger
+ * 
+ * Maintains an ordered list of all failures during execution.
+ */
+export class FailureLedger {
+  constructor(runId, projectDir) {
+    this.runId = runId;
+    this.projectDir = projectDir;
+    this.failures = [];
+    this.startTime = Date.now();
+  }
+  
+  /**
+   * Record a failure
+   * 
+   * @param {Object} failure - Failure object
+   * @ts-expect-error - Failure type not imported
+   */
+  record(failure) {
+    validateFailure(failure);
+    
+    // Add sequence number for deterministic ordering
+    const sequencedFailure = {
+      ...failure,
+      sequence: this.failures.length,
+      relativeTime: Date.now() - this.startTime
+    };
+    
+    this.failures.push(sequencedFailure);
+  }
+  
+  /**
+   * Get failure summary
+   * 
+   * @returns {Object} Summary with counts by severity
+   */
+  getSummary() {
+    const summary = {
+      total: this.failures.length,
+      bySeverity: {
+        BLOCKING: 0,
+        DEGRADED: 0,
+        WARNING: 0
+      },
+      byCategory: {},
+      byPhase: {},
+      highestSeverity: null
+    };
+    
+    for (const failure of this.failures) {
+      summary.bySeverity[failure.severity] = (summary.bySeverity[failure.severity] || 0) + 1;
+      summary.byCategory[failure.category] = (summary.byCategory[failure.category] || 0) + 1;
+      summary.byPhase[failure.phase] = (summary.byPhase[failure.phase] || 0) + 1;
+    }
+    
+    // Determine highest severity
+    if (summary.bySeverity.BLOCKING > 0) {
+      summary.highestSeverity = 'BLOCKING';
+    } else if (summary.bySeverity.DEGRADED > 0) {
+      summary.highestSeverity = 'DEGRADED';
+    } else if (summary.bySeverity.WARNING > 0) {
+      summary.highestSeverity = 'WARNING';
+    }
+    
+    return summary;
+  }
+  
+  /**
+   * Get highest severity for exit code determination
+   * 
+   * @returns {string|null} Highest severity or null if no failures
+   */
+  getHighestSeverity() {
+    const summary = this.getSummary();
+    return summary.highestSeverity;
+  }
+  
+  /**
+   * Write ledger to file
+   * 
+   * @returns {string} Path to ledger file
+   */
+  write() {
+    if (!this.runId || !this.projectDir) {
+      throw new Error('Cannot write failure ledger: runId and projectDir required');
+    }
+    
+    const runsDir = resolve(this.projectDir, '.verax', 'runs', this.runId);
+    mkdirSync(runsDir, { recursive: true });
+    
+    const ledgerPath = resolve(runsDir, 'failure.ledger.json');
+    
+    const ledgerData = {
+      runId: this.runId,
+      startTime: this.startTime,
+      endTime: Date.now(),
+      duration: Date.now() - this.startTime,
+      summary: this.getSummary(),
+      failures: this.failures
+    };
+    
+    writeFileSync(ledgerPath, JSON.stringify(ledgerData, null, 2), 'utf-8');
+    
+    return ledgerPath;
+  }
+  
+  /**
+   * Export ledger data (for testing)
+   * 
+   * @returns {Object} Ledger data
+   */
+  export() {
+    return {
+      runId: this.runId,
+      startTime: this.startTime,
+      summary: this.getSummary(),
+      failures: this.failures
+    };
+  }
+}
+