@veraxhq/verax 0.2.0 → 0.3.0

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

@@ -0,0 +1,215 @@
+/**
+ * PHASE 20 — Vue State Promise Detection
+ * 
+ * Detects ref/reactive mutations that are UI-bound:
+ * - ref declarations: const count = ref(0);
+ * - reactive: const state = reactive({ x: 1 });
+ * - Only emit if identifiers are used in template bindings
+ */
+
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+
+const traverse = _traverse.default || _traverse;
+
+/**
+ * PHASE 20: Detect Vue state 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
+ * @returns {Array} State promises
+ */
+export function detectVueStatePromises(scriptContent, filePath, relPath, scriptBlock, templateBindings) {
+  const promises = [];
+  const templateVars = new Set(templateBindings.bindings || []);
+  
+  if (templateVars.size === 0) {
+    return promises; // No template bindings, skip
+  }
+  
+  try {
+    const ast = parse(scriptContent, {
+      sourceType: 'module',
+      plugins: [
+        'typescript',
+        'classProperties',
+        'optionalChaining',
+        'nullishCoalescingOperator',
+        'dynamicImport',
+        'topLevelAwait',
+        'objectRestSpread',
+      ],
+      errorRecovery: true,
+    });
+    
+    const lines = scriptContent.split('\n');
+    const refDeclarations = new Map(); // varName -> { loc, astSource }
+    const reactiveDeclarations = new Map();
+    
+    traverse(ast, {
+      // Detect ref() declarations
+      VariableDeclarator(path) {
+        const node = path.node;
+        const init = node.init;
+        
+        if (init && init.type === 'CallExpression') {
+          const callee = init.callee;
+          
+          // ref(0) or ref({})
+          if (callee.type === 'Identifier' && callee.name === 'ref') {
+            const varName = node.id.name;
+            if (templateVars.has(varName)) {
+              const loc = node.loc;
+              const line = loc ? loc.start.line : 1;
+              const astSource = lines.slice(line - 1, loc ? loc.end.line : line)
+                .join('\n')
+                .substring(0, 200);
+              
+              refDeclarations.set(varName, {
+                loc,
+                astSource,
+                line,
+              });
+            }
+          }
+          
+          // reactive({})
+          if (callee.type === 'Identifier' && callee.name === 'reactive') {
+            const varName = node.id.name;
+            if (templateVars.has(varName)) {
+              const loc = node.loc;
+              const line = loc ? loc.start.line : 1;
+              const astSource = lines.slice(line - 1, loc ? loc.end.line : line)
+                .join('\n')
+                .substring(0, 200);
+              
+              reactiveDeclarations.set(varName, {
+                loc,
+                astSource,
+                line,
+              });
+            }
+          }
+        }
+      },
+      
+      // Detect mutations: count.value = ... or state.x = ...
+      AssignmentExpression(path) {
+        const node = path.node;
+        const left = node.left;
+        
+        // count.value = ...
+        if (left.type === 'MemberExpression' && 
+            left.property.name === 'value' &&
+            left.object.type === 'Identifier') {
+          const varName = left.object.name;
+          
+          if (refDeclarations.has(varName) && templateVars.has(varName)) {
+            const decl = refDeclarations.get(varName);
+            const loc = node.loc;
+            const line = loc ? loc.start.line : 1;
+            const column = loc ? loc.start.column : 0;
+            
+            const astSource = lines.slice(line - 1, loc ? loc.end.line : line)
+              .join('\n')
+              .substring(0, 200);
+            
+            const context = buildContext(path);
+            
+            promises.push({
+              type: 'state',
+              promise: {
+                kind: 'state-change',
+                value: `${varName}.value`,
+                stateVar: varName,
+              },
+              source: {
+                file: relPath,
+                line,
+                column,
+                context,
+                astSource,
+              },
+              confidence: 0.9,
+            });
+          }
+        }
+        
+        // state.x = ...
+        if (left.type === 'MemberExpression' &&
+            left.object.type === 'Identifier') {
+          const varName = left.object.name;
+          
+          if (reactiveDeclarations.has(varName) && templateVars.has(varName)) {
+            const loc = node.loc;
+            const line = loc ? loc.start.line : 1;
+            const column = loc ? loc.start.column : 0;
+            
+            const astSource = lines.slice(line - 1, loc ? loc.end.line : line)
+              .join('\n')
+              .substring(0, 200);
+            
+            const context = buildContext(path);
+            const propName = left.property.name || '<property>';
+            
+            promises.push({
+              type: 'state',
+              promise: {
+                kind: 'state-change',
+                value: `${varName}.${propName}`,
+                stateVar: varName,
+              },
+              source: {
+                file: relPath,
+                line,
+                column,
+                context,
+                astSource,
+              },
+              confidence: 0.9,
+            });
+          }
+        }
+      },
+    });
+  } 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>',
+      });
+    }
+    
+    current = current.parentPath;
+  }
+  
+  return context.reverse().map(c => `${c.type}:${c.name}`).join(' > ');
+}
+

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/finding-explainer.js

@@ -14,11 +14,22 @@
 export function formatFinding(finding, expectation = null) {
   const lines = [];
   
-  // Finding type and confidence
-  const confidenceLevel = finding.confidence?.level || 'UNKNOWN';
-  const confidenceScore = finding.confidence?.score || 0;
+  // PHASE 15: Finding type and unified confidence
+  const confidenceLevel = finding.confidenceLevel || finding.confidence?.level || 'UNPROVEN';
+  const confidenceScore = finding.confidence !== undefined 
+    ? (finding.confidence <= 1 ? Math.round(finding.confidence * 100) : finding.confidence)
+    : (finding.confidence?.score || 0);
+  const confidenceReasons = finding.confidenceReasons || [];
+  
   lines.push(`  [${confidenceLevel} (${confidenceScore}%)] ${finding.type || 'unknown'}`);
   
+  // PHASE 15: Show top confidence reasons
+  if (confidenceReasons.length > 0) {
+    const topReasons = confidenceReasons.slice(0, 3);
+    const reasonText = topReasons.join(', ');
+    lines.push(`  └─ Confidence: ${reasonText}`);
+  }
+  
   // Expectation (what was promised)
   if (expectation) {
     let expectationDesc = '';
@@ -84,6 +95,48 @@ export function formatFinding(finding, expectation = null) {
     lines.push(`  └─ Source: ${expectation.source.file}${sourceLine}`);
   }
   
+  // PHASE 16: Show evidence completeness
+  if (finding.evidencePackage) {
+    if (finding.evidencePackage.isComplete) {
+      lines.push(`  └─ Evidence: Complete`);
+    } else {
+      lines.push(`  └─ Evidence: Incomplete (missing: ${finding.evidencePackage.missingEvidence.join(', ')})`);
+    }
+  }
+  
+  // PHASE 16: Show downgrade reason if evidence was incomplete
+  if (finding.evidenceCompleteness?.downgraded) {
+    lines.push(`  └─ Downgraded: ${finding.evidenceCompleteness.downgradeReason}`);
+  }
+  
+  // PHASE 17/23: Show guardrails applied and reconciliation
+  if (finding.guardrails) {
+    const guardrails = finding.guardrails;
+    if (guardrails.appliedRules && guardrails.appliedRules.length > 0) {
+      const ruleCodes = guardrails.appliedRules.map(r => r.code || r.ruleId).filter(Boolean);
+      if (ruleCodes.length > 0) {
+        lines.push(`  └─ Final status due to guardrails: ${ruleCodes.join(', ')}`);
+      }
+    }
+    if (guardrails.contradictions && guardrails.contradictions.length > 0) {
+      lines.push(`  └─ Contradiction: ${guardrails.contradictions[0].message}`);
+    }
+    
+    // PHASE 23: Show confidence reconciliation if present
+    if (guardrails.reconciliation) {
+      const recon = guardrails.reconciliation;
+      if (recon.confidenceBefore !== recon.confidenceAfter) {
+        const beforePercent = Math.round(recon.confidenceBefore * 100);
+        const afterPercent = Math.round(recon.confidenceAfter * 100);
+        lines.push(`  └─ Confidence: ${beforePercent}% → ${afterPercent}% (${recon.confidenceLevelBefore} → ${recon.confidenceLevelAfter})`);
+      }
+      if (recon.reconciliationReasons && recon.reconciliationReasons.length > 0) {
+        const topReasons = recon.reconciliationReasons.slice(0, 2);
+        lines.push(`  └─ Reconciliation: ${topReasons.join(', ')}`);
+      }
+    }
+  }
+  
   return lines.join('\n');
 }
 

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/artifacts/registry.js

@@ -0,0 +1,154 @@
+import { join } from 'path';
+
+export const ARTIFACT_REGISTRY = {
+  runStatus: {
+    key: 'runStatus',
+    filename: 'run.status.json',
+    stage: 'init',
+    contractVersion: 1,
+    type: 'file'
+  },
+  runMeta: {
+    key: 'runMeta',
+    filename: 'run.meta.json',
+    stage: 'init',
+    contractVersion: 1,
+    type: 'file'
+  },
+  summary: {
+    key: 'summary',
+    filename: 'summary.json',
+    stage: 'finalize',
+    contractVersion: 1,
+    type: 'file'
+  },
+  findings: {
+    key: 'findings',
+    filename: 'findings.json',
+    stage: 'detect',
+    contractVersion: 1,
+    type: 'file'
+  },
+  learn: {
+    key: 'learn',
+    filename: 'learn.json',
+    stage: 'learn',
+    contractVersion: 1,
+    type: 'file'
+  },
+  observe: {
+    key: 'observe',
+    filename: 'observe.json',
+    stage: 'observe',
+    contractVersion: 1,
+    type: 'file'
+  },
+  project: {
+    key: 'project',
+    filename: 'project.json',
+    stage: 'init',
+    contractVersion: 1,
+    type: 'file'
+  },
+  traces: {
+    key: 'traces',
+    filename: 'traces.jsonl',
+    stage: 'finalize',
+    contractVersion: 1,
+    type: 'file'
+  },
+  evidence: {
+    key: 'evidence',
+    filename: 'evidence',
+    stage: 'observe',
+    contractVersion: 1,
+    type: 'directory'
+  },
+  scanSummary: {
+    key: 'scanSummary',
+    filename: 'scan-summary.json',
+    stage: 'finalize',
+    contractVersion: 1,
+    type: 'file'
+  },
+  determinismReport: {
+    key: 'determinismReport',
+    filename: 'determinism.report.json',
+    stage: 'finalize',
+    contractVersion: 1,
+    type: 'file'
+  },
+  evidenceIntent: {
+    key: 'evidenceIntent',
+    filename: 'evidence.intent.json',
+    stage: 'detect',
+    contractVersion: 1,
+    type: 'file'
+  },
+  guardrailsReport: {
+    key: 'guardrailsReport',
+    filename: 'guardrails.report.json',
+    stage: 'detect',
+    contractVersion: 1,
+    type: 'file'
+  },
+  confidenceReport: {
+    key: 'confidenceReport',
+    filename: 'confidence.report.json',
+    stage: 'detect',
+    contractVersion: 1,
+    type: 'file'
+  },
+  determinismContract: {
+    key: 'determinismContract',
+    filename: 'determinism.contract.json',
+    stage: 'observe',
+    contractVersion: 1,
+    type: 'file'
+  },
+  determinismReport: {
+    key: 'determinismReport',
+    filename: 'determinism.report.json',
+    stage: 'verify',
+    contractVersion: 1,
+    type: 'file'
+  },
+  runMeta: {
+    key: 'runMeta',
+    filename: 'run.meta.json',
+    stage: 'learn',
+    contractVersion: 1,
+    type: 'file'
+  }
+};
+
+export function getArtifactVersions() {
+  const versions = {};
+  for (const [key, def] of Object.entries(ARTIFACT_REGISTRY)) {
+    versions[key] = def.contractVersion;
+  }
+  return versions;
+}
+
+export function buildRunArtifactPaths(baseDir) {
+  return {
+    baseDir,
+    runStatusJson: join(baseDir, ARTIFACT_REGISTRY.runStatus.filename),
+    runMetaJson: join(baseDir, ARTIFACT_REGISTRY.runMeta.filename),
+    summaryJson: join(baseDir, ARTIFACT_REGISTRY.summary.filename),
+    findingsJson: join(baseDir, ARTIFACT_REGISTRY.findings.filename),
+    tracesJsonl: join(baseDir, ARTIFACT_REGISTRY.traces.filename),
+    evidenceDir: join(baseDir, ARTIFACT_REGISTRY.evidence.filename),
+    learnJson: join(baseDir, ARTIFACT_REGISTRY.learn.filename),
+    observeJson: join(baseDir, ARTIFACT_REGISTRY.observe.filename),
+    projectJson: join(baseDir, ARTIFACT_REGISTRY.project.filename),
+    scanSummaryJson: join(baseDir, ARTIFACT_REGISTRY.scanSummary.filename),
+    evidenceIntentJson: join(baseDir, ARTIFACT_REGISTRY.evidenceIntent.filename),
+    guardrailsReportJson: join(baseDir, ARTIFACT_REGISTRY.guardrailsReport.filename),
+    confidenceReportJson: join(baseDir, ARTIFACT_REGISTRY.confidenceReport.filename),
+    determinismContractJson: join(baseDir, ARTIFACT_REGISTRY.determinismContract.filename),
+    determinismReportJson: join(baseDir, ARTIFACT_REGISTRY.determinismReport.filename),
+    runMetaJson: join(baseDir, ARTIFACT_REGISTRY.runMeta.filename),
+    artifactVersions: getArtifactVersions()
+  };
+}