@veraxhq/verax 0.1.0

package/src/verax/index.js

@@ -0,0 +1,97 @@
+import { learn } from './learn/index.js';
+import { observe } from './observe/index.js';
+import { detect } from './detect/index.js';
+import { writeScanSummary } from './scan-summary-writer.js';
+import { validateRoutes } from './learn/route-validator.js';
+import { initArtifactPaths, generateRunId } from './shared/artifact-manager.js';
+
+export async function scan(projectDir, url, manifestPath = null, runId = null) {
+  // Generate runId for this scan if not provided
+  const scanRunId = runId || generateRunId();
+  const artifactPaths = initArtifactPaths(projectDir, scanRunId);
+  // If manifestPath is provided, read it first before learn() overwrites it
+  let loadedManifest = null;
+  if (manifestPath) {
+    const { readFileSync } = await import('fs');
+    try {
+      const manifestContent = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      loadedManifest = manifestContent;
+    } catch (e) {
+      // Fall through to learn if we can't read the manifest
+    }
+  }
+  
+  const learnedManifest = await learn(projectDir);
+  
+  // Merge: prefer loaded manifest for routes, but use learned for project type and truth
+  let manifest;
+  if (loadedManifest) {
+    manifest = {
+      ...learnedManifest,
+      projectType: loadedManifest.projectType || learnedManifest.projectType,
+      publicRoutes: loadedManifest.publicRoutes || learnedManifest.publicRoutes,
+      routes: loadedManifest.routes || learnedManifest.routes,
+      internalRoutes: loadedManifest.internalRoutes || learnedManifest.internalRoutes,
+      manifestPath: manifestPath
+    };
+  } else {
+    manifest = learnedManifest;
+  }
+  
+  if (!url) {
+    return { manifest, observation: null, findings: null, scanSummary: null, validation: null };
+  }
+  
+  // manifestForValidation uses the provided/merged manifest (which may have been modified)
+  const manifestForValidation = {
+    projectType: manifest.projectType,
+    publicRoutes: manifest.publicRoutes,
+    routes: manifest.routes,
+    manifestPath: manifest.manifestPath
+  };
+  
+  const validation = await validateRoutes(manifestForValidation, url);
+  
+  if (validation.warnings && validation.warnings.length > 0) {
+    if (!manifest.learnTruth.warnings) {
+      manifest.learnTruth.warnings = [];
+    }
+    manifest.learnTruth.warnings.push(...validation.warnings);
+  }
+  
+  const usedManifestPath = manifestPath || manifest.manifestPath;
+  const observation = await observe(url, usedManifestPath, artifactPaths);
+  
+  // For detect, we need tracesPath - use observation.tracesPath if available, otherwise use artifact paths
+  let tracesPathForDetect = observation.tracesPath;
+  if (artifactPaths && !tracesPathForDetect) {
+    tracesPathForDetect = artifactPaths.traces;
+  }
+  
+  const findings = await detect(usedManifestPath, tracesPathForDetect, validation, artifactPaths);
+  
+  const learnTruthWithValidation = {
+    ...manifest.learnTruth,
+    validation: validation
+  };
+  
+  const scanSummary = writeScanSummary(
+    projectDir,
+    url,
+    manifest.projectType,
+    learnTruthWithValidation,
+    observation.observeTruth,
+    findings.detectTruth,
+    manifest.manifestPath,
+    observation.tracesPath,
+    findings.findingsPath,
+    artifactPaths
+  );
+  
+  return { manifest, observation, findings, scanSummary, validation };
+}
+
+export { learn } from './learn/index.js';
+export { observe } from './observe/index.js';
+export { detect } from './detect/index.js';
+

package/src/verax/learn/action-contract-extractor.js

@@ -0,0 +1,281 @@
+/**
+ * Wave 5 — Action Contract Extractor
+ * 
+ * Extracts PROVEN network action contracts from JSX/React source files.
+ * Uses AST analysis to find onClick/onSubmit handlers that call fetch/axios
+ * with static URL literals.
+ * 
+ * NO HEURISTICS. Only static, deterministic analysis.
+ */
+
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+import { readFileSync } from 'fs';
+import { resolve, relative, sep } from 'path';
+
+/**
+ * Extract action contracts from a source file.
+ * 
+ * @param {string} filePath - Absolute path to source file
+ * @param {string} workspaceRoot - Workspace root for relative paths
+ * @returns {Array<Object>} - Array of contract objects
+ */
+export function extractActionContracts(filePath, workspaceRoot) {
+  const contracts = [];
+  
+  try {
+    const code = readFileSync(filePath, 'utf-8');
+    const ast = parse(code, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+     // Track function declarations and arrow function assignments
+     const functionBodies = new Map(); // name -> AST node
+   
+    traverse.default(ast, {
+       // Track function declarations
+       FunctionDeclaration(path) {
+         if (path.node.id && path.node.id.name) {
+           functionBodies.set(path.node.id.name, path.node.body);
+         }
+       },
+     
+       // Track arrow function variable assignments
+       VariableDeclarator(path) {
+         if (
+           path.node.id.type === 'Identifier' &&
+           path.node.init &&
+           path.node.init.type === 'ArrowFunctionExpression'
+         ) {
+           functionBodies.set(path.node.id.name, path.node.init.body);
+         }
+       },
+     
+      // Find JSX elements with onClick or onSubmit
+      JSXAttribute(path) {
+        const attrName = path.node.name.name;
+        if (attrName !== 'onClick' && attrName !== 'onSubmit') {
+          return;
+        }
+
+        const value = path.node.value;
+        if (!value) return;
+
+         // Only analyze inline arrow functions for now
+         // Case 1: Inline arrow function: onClick={() => fetch(...)}
+         if (
+           value.type === 'JSXExpressionContainer' &&
+           value.expression.type === 'ArrowFunctionExpression'
+         ) {
+           const handlerBody = value.expression.body;
+           const networkCalls = findNetworkCallsInNode(handlerBody);
+         
+           for (const call of networkCalls) {
+             const loc = path.node.loc;
+             const sourceRef = formatSourceRef(filePath, workspaceRoot, loc);
+           
+             contracts.push({
+               kind: 'NETWORK_ACTION',
+               method: call.method,
+               urlPath: call.url,
+               source: sourceRef,
+               elementType: path.parent.name.name, // button, form, etc.
+             });
+           }
+         }
+         // Case 2: Function reference - analyze the function declaration
+         else if (
+           value.type === 'JSXExpressionContainer' &&
+           value.expression.type === 'Identifier'
+         ) {
+           const refName = value.expression.name;
+           const handlerBody = functionBodies.get(refName);
+         
+           if (handlerBody) {
+             const networkCalls = findNetworkCallsInNode(handlerBody);
+           
+             for (const call of networkCalls) {
+               const loc = path.node.loc;
+               const sourceRef = formatSourceRef(filePath, workspaceRoot, loc);
+             
+               contracts.push({
+                 kind: 'NETWORK_ACTION',
+                 method: call.method,
+                 urlPath: call.url,
+                 source: sourceRef,
+                 elementType: path.parent.name.name,
+               });
+             }
+           }
+         }
+       },
+    });
+  } catch (err) {
+    // Parse errors are not fatal; just return empty contracts
+    console.warn(`Failed to parse ${filePath}: ${err.message}`);
+  }
+
+  return contracts;
+}
+
+/**
+ * Find network calls (fetch, axios) in an AST node by recursively scanning.
+ * Only returns calls with static URL literals.
+ * 
+ * @param {Object} node - AST node to scan
+ * @returns {Array<Object>} - Array of {method, url}
+ */
+function findNetworkCallsInNode(node) {
+  const calls = [];
+
+  // Recursive function to scan all nodes
+  function scan(n) {
+    if (!n || typeof n !== 'object') return;
+    
+    // Check if this is a CallExpression
+    if (n.type === 'CallExpression') {
+      const callee = n.callee;
+
+      // Case 1: fetch(url, options)
+      if (callee.type === 'Identifier' && callee.name === 'fetch') {
+       const urlArg = n.arguments[0];
+       const optionsArg = n.arguments[1];
+
+        // Only accept static string literals
+        if (urlArg && urlArg.type === 'StringLiteral') {
+          let method = 'GET'; // default
+          
+          // Try to extract method from options
+          if (optionsArg && optionsArg.type === 'ObjectExpression') {
+            const methodProp = optionsArg.properties.find(
+              (p) => p.key && p.key.name === 'method'
+            );
+            if (methodProp && methodProp.value.type === 'StringLiteral') {
+              method = methodProp.value.value.toUpperCase();
+            }
+          }
+
+          calls.push({ method, url: urlArg.value });
+        }
+      }
+
+      // Case 2: axios.get(url), axios.post(url, data), etc.
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.object.type === 'Identifier' &&
+        callee.object.name === 'axios' &&
+        callee.property.type === 'Identifier'
+      ) {
+        const methodName = callee.property.name.toUpperCase();
+       const urlArg = n.arguments[0];
+
+        if (urlArg && urlArg.type === 'StringLiteral') {
+          calls.push({ method: methodName, url: urlArg.value });
+        }
+      }
+
+      // Case 3: XMLHttpRequest (optional, basic support)
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'open'
+      ) {
+        // xhr.open(method, url)
+       const methodArg = n.arguments[0];
+       const urlArg = n.arguments[1];
+
+        if (
+          methodArg && methodArg.type === 'StringLiteral' &&
+          urlArg && urlArg.type === 'StringLiteral'
+        ) {
+          calls.push({
+            method: methodArg.value.toUpperCase(),
+            url: urlArg.value,
+          });
+        }
+      }
+   }
+   
+   // Recursively scan all properties
+   for (const key in n) {
+     if (n.hasOwnProperty(key)) {
+       const value = n[key];
+       if (Array.isArray(value)) {
+         value.forEach(item => scan(item));
+       } else if (value && typeof value === 'object') {
+         scan(value);
+       }
+     }
+   }
+  }
+
+  scan(node);
+  return calls;
+}
+
+/**
+ * Format source reference as "file:line:col"
+ * Normalizes Windows paths to use forward slashes.
+ * 
+ * @param {string} filePath - Absolute file path
+ * @param {string} workspaceRoot - Workspace root
+ * @param {Object} loc - Location object from AST
+ * @returns {string} - Formatted source reference
+ */
+function formatSourceRef(filePath, workspaceRoot, loc) {
+  let relPath = relative(workspaceRoot, filePath);
+  
+  // Normalize to forward slashes
+  relPath = relPath.split(sep).join('/');
+  
+  const line = loc.start.line;
+  const col = loc.start.column;
+  
+  return `${relPath}:${line}:${col}`;
+}
+
+/**
+ * Scan a directory tree for source files and extract all contracts.
+ * 
+ * @param {string} rootPath - Root directory to scan
+ * @param {string} workspaceRoot - Workspace root
+ * @returns {Array<Object>} - All contracts found
+ */
+export async function scanForContracts(rootPath, workspaceRoot) {
+  const contracts = [];
+  
+  // For now, just scan known patterns
+  // In real implementation, would recurse through directories
+  const { readdirSync, statSync } = await import('fs');
+  const { join } = await import('path');
+  
+  function walk(dir) {
+    try {
+      const entries = readdirSync(dir);
+      
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        
+        if (stat.isDirectory()) {
+          // Skip node_modules, .git, etc.
+          if (!entry.startsWith('.') && entry !== 'node_modules') {
+            walk(fullPath);
+          }
+        } else if (stat.isFile()) {
+          // Only process .js, .jsx, .ts, .tsx files
+          if (/\.(jsx?|tsx?)$/.test(entry)) {
+            const fileContracts = extractActionContracts(fullPath, workspaceRoot);
+            contracts.push(...fileContracts);
+          }
+        }
+      }
+    } catch (err) {
+      // Ignore errors (permission issues, etc.)
+    }
+  }
+  
+  walk(rootPath);
+  return contracts;
+}

package/src/verax/learn/ast-contract-extractor.js

@@ -0,0 +1,255 @@
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+import { readFileSync } from 'fs';
+import { glob } from 'glob';
+import { resolve } from 'path';
+import { ExpectationProof } from '../shared/expectation-proof.js';
+
+const MAX_FILES_TO_SCAN = 200;
+
+/**
+ * Extracts static string value from JSX attribute or expression.
+ * Returns null if value is dynamic (variable, template with interpolation, etc.)
+ * 
+ * Wave 1 - CODE TRUTH ENGINE: Only static literals are PROVEN.
+ */
+function extractStaticStringValue(node) {
+  if (!node) return null;
+  
+  // Direct string literal: href="/about"
+  if (node.type === 'StringLiteral') {
+    return node.value;
+  }
+  
+  // JSX expression: href={'/about'} or href={`/about`}
+  if (node.type === 'JSXExpressionContainer') {
+    const expr = node.expression;
+    
+    // String literal in expression: {'/about'}
+    if (expr.type === 'StringLiteral') {
+      return expr.value;
+    }
+    
+    // Template literal WITHOUT interpolation: {`/about`}
+    if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+      // Only if there are no ${...} expressions
+      if (expr.quasis.length === 1) {
+        return expr.quasis[0].value.cooked;
+      }
+    }
+    
+    // Anything else (variables, interpolated templates, etc.) is UNKNOWN
+    return null;
+  }
+  
+  return null;
+}
+
+/**
+ * Extracts PROVEN navigation contracts from JSX elements and imperative calls.
+ * 
+ * Supported patterns (all require static string literals):
+ * - Next.js: <Link href="/about">
+ * - React Router: <Link to="/about"> or <NavLink to="/about">
+ * - Plain JSX: <a href="/about">
+ * - Imperative: navigate("/about"), router.push("/about")
+ * 
+ * Returns array of contracts with:
+ * - kind: 'NAVIGATION'
+ * - targetPath: string
+ * - sourceFile: string
+ * - element: 'Link' | 'NavLink' | 'a' | 'navigate' | 'router'
+ * - attribute: 'href' | 'to' (for runtime matching)
+ * - proof: PROVEN_EXPECTATION
+ * - line: number (optional)
+ */
+function extractContractsFromFile(filePath, fileContent) {
+  const contracts = [];
+  
+  try {
+    // Parse with Babel - support JSX and TypeScript
+    const ast = parse(fileContent, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript']
+    });
+    
+    traverse.default(ast, {
+      // JSX elements: <Link href>, <a href>, <NavLink to>
+      JSXElement(path) {
+        const openingElement = path.node.openingElement;
+        const elementName = openingElement.name.name;
+        
+        // Check for Link, NavLink, or a elements
+        if (elementName === 'Link' || elementName === 'NavLink' || elementName === 'a') {
+          let targetPath = null;
+          let attributeName = null;
+          
+          // Find href or to attribute
+          for (const attr of openingElement.attributes) {
+            if (attr.type === 'JSXAttribute') {
+              const attrName = attr.name.name;
+              
+              if (attrName === 'href' || attrName === 'to') {
+                targetPath = extractStaticStringValue(attr.value);
+                attributeName = attrName;
+                break;
+              }
+            }
+          }
+          
+          // Only create contract if we have a static target path
+          if (targetPath && !targetPath.startsWith('http://') && !targetPath.startsWith('https://') && !targetPath.startsWith('mailto:') && !targetPath.startsWith('tel:')) {
+            // Normalize path
+            const normalized = targetPath.startsWith('/') ? targetPath : '/' + targetPath;
+            
+            contracts.push({
+              kind: 'NAVIGATION',
+              targetPath: normalized,
+              sourceFile: filePath,
+              element: elementName,
+              attribute: attributeName,
+              proof: ExpectationProof.PROVEN_EXPECTATION,
+              line: openingElement.loc?.start.line || null
+            });
+          }
+        }
+      },
+      
+      // Imperative navigation calls: navigate("/about"), router.push("/about")
+      // Note: These are recorded but not used for element-based expectations
+      // since we cannot reliably tie them to clicked elements
+      CallExpression(path) {
+        const callee = path.node.callee;
+        
+        // navigate("/about") - useNavigate hook
+        if (callee.type === 'Identifier' && callee.name === 'navigate') {
+          const firstArg = path.node.arguments[0];
+          if (firstArg && firstArg.type === 'StringLiteral') {
+            const targetPath = firstArg.value;
+            if (targetPath.startsWith('/')) {
+              contracts.push({
+                kind: 'NAVIGATION',
+                targetPath: targetPath,
+                sourceFile: filePath,
+                element: 'navigate',
+                attribute: null,
+                proof: ExpectationProof.PROVEN_EXPECTATION,
+                line: path.node.loc?.start.line || null,
+                imperativeOnly: true // Cannot match to DOM element
+              });
+            }
+          }
+        }
+        
+        // router.push("/about") or router.replace("/about")
+        if (callee.type === 'MemberExpression' && 
+            callee.object.type === 'Identifier' && 
+            callee.object.name === 'router' &&
+            callee.property.type === 'Identifier' &&
+            (callee.property.name === 'push' || callee.property.name === 'replace')) {
+          const firstArg = path.node.arguments[0];
+          if (firstArg && firstArg.type === 'StringLiteral') {
+            const targetPath = firstArg.value;
+            if (targetPath.startsWith('/')) {
+              contracts.push({
+                kind: 'NAVIGATION',
+                targetPath: targetPath,
+                sourceFile: filePath,
+                element: 'router',
+                attribute: null,
+                proof: ExpectationProof.PROVEN_EXPECTATION,
+                line: path.node.loc?.start.line || null,
+                imperativeOnly: true // Cannot match to DOM element
+              });
+            }
+          }
+        }
+      }
+    });
+  } catch (error) {
+    // Parse error - skip this file
+    // This is expected for files with syntax errors or unsupported syntax
+    return [];
+  }
+  
+  return contracts;
+}
+
+/**
+ * Scans a project directory for navigation contracts using AST analysis.
+ * Returns array of PROVEN navigation contracts.
+ * 
+ * Wave 1 - CODE TRUTH ENGINE: AST-derived PROVEN expectations only.
+ */
+export async function extractASTContracts(projectDir) {
+  const contracts = [];
+  
+  try {
+    // Find all JS/JSX/TS/TSX files (excluding node_modules, dist, build)
+    const files = await glob('**/*.{js,jsx,ts,tsx}', {
+      cwd: projectDir,
+      absolute: false,
+      ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**', 'out/**']
+    });
+    
+    // Limit files to scan
+    const filesToScan = files.slice(0, MAX_FILES_TO_SCAN);
+    
+    for (const file of filesToScan) {
+      try {
+        const filePath = resolve(projectDir, file);
+        const content = readFileSync(filePath, 'utf-8');
+        const fileContracts = extractContractsFromFile(file, content);
+        contracts.push(...fileContracts);
+      } catch (error) {
+        // Skip files that can't be read
+        continue;
+      }
+    }
+  } catch (error) {
+    // If glob fails, return empty
+    return [];
+  }
+  
+  return contracts;
+}
+
+/**
+ * Converts AST contracts to manifest expectations format.
+ * Only includes contracts that can be matched at runtime (excludes imperativeOnly).
+ */
+export function contractsToExpectations(contracts, projectType) {
+  const expectations = [];
+  const seenPaths = new Set();
+  
+  for (const contract of contracts) {
+    // Skip imperative-only contracts (navigate, router.push)
+    // These cannot be reliably matched to DOM elements
+    if (contract.imperativeOnly) {
+      continue;
+    }
+    
+    // Skip duplicates
+    const key = `${contract.targetPath}:${contract.attribute}`;
+    if (seenPaths.has(key)) {
+      continue;
+    }
+    seenPaths.add(key);
+    
+    // Create expectation for runtime matching
+    // We don't specify fromPath since we'll match by href/to attribute value
+    expectations.push({
+      type: 'spa_navigation',
+      targetPath: contract.targetPath,
+      proof: ExpectationProof.PROVEN_EXPECTATION,
+      matchAttribute: contract.attribute, // 'href' or 'to'
+      evidence: {
+        source: contract.sourceFile,
+        element: contract.element,
+        line: contract.line
+      }
+    });
+  }
+  
+  return expectations;
+}

package/src/verax/learn/index.js

@@ -0,0 +1,18 @@
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { detectProjectType } from './project-detector.js';
+import { extractRoutes } from './route-extractor.js';
+import { writeManifest } from './manifest-writer.js';
+
+export async function learn(projectDir) {
+  const absoluteProjectDir = resolve(projectDir);
+  
+  if (!existsSync(absoluteProjectDir)) {
+    throw new Error(`Project directory does not exist: ${absoluteProjectDir}`);
+  }
+  
+  const projectType = await detectProjectType(absoluteProjectDir);
+  const routes = await extractRoutes(absoluteProjectDir, projectType);
+  
+  return await writeManifest(absoluteProjectDir, projectType, routes);
+}