@veraxhq/verax 0.1.0 → 0.2.0

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

@@ -3,12 +3,12 @@
  * 
  * 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.
+ * with static URL literals and template literals.
  * 
  * NO HEURISTICS. Only static, deterministic analysis.
  */
 
-import { parse } from '@babel/parser';
+import { normalizeTemplateLiteral } from '../shared/dynamic-route-utils.js';import { parse } from '@babel/parser';
 import traverse from '@babel/traverse';
 import { readFileSync } from 'fs';
 import { resolve, relative, sep } from 'path';
@@ -21,113 +21,234 @@ import { resolve, relative, sep } from 'path';
  * @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,
-               });
-             }
-           }
-         }
-       },
-    });
+    return extractActionContractsFromCode(filePath, workspaceRoot, code, 0);
   } catch (err) {
-    // Parse errors are not fatal; just return empty contracts
     console.warn(`Failed to parse ${filePath}: ${err.message}`);
+    return [];
   }
+}
+
+function extractActionContractsFromCode(filePath, workspaceRoot, code, lineOffset = 0) {
+  const contracts = [];
+
+  // Track function declarations and arrow function assignments with location
+  const functionBodies = new Map(); // name -> { body, loc }
+
+  const ast = parse(code, {
+    sourceType: 'unambiguous',
+    plugins: ['jsx', 'typescript'],
+  });
+
+  traverse.default(ast, {
+    FunctionDeclaration(path) {
+      if (path.node.id && path.node.id.name) {
+        functionBodies.set(path.node.id.name, { body: path.node.body, loc: path.node.loc });
+      }
+    },
+
+    VariableDeclarator(path) {
+      if (
+        path.node.id.type === 'Identifier' &&
+        path.node.init &&
+        path.node.init.type === 'ArrowFunctionExpression'
+      ) {
+        functionBodies.set(path.node.id.name, { body: path.node.init.body, loc: path.node.loc });
+      }
+    },
+
+    // JSX handlers (React)
+    JSXAttribute(path) {
+      const attrName = path.node.name.name;
+      if (attrName !== 'onClick' && attrName !== 'onSubmit') {
+        return;
+      }
+      
+      const isSubmitHandler = attrName === 'onSubmit';
+
+      const value = path.node.value;
+      if (!value) return;
+
+      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, lineOffset);
+
+          if (call.kind === 'VALIDATION_BLOCK' && isSubmitHandler) {
+            contracts.push({
+              kind: 'VALIDATION_BLOCK',
+              method: call.method,
+              urlPath: null,
+              source: sourceRef,
+              elementType: path.parent.name.name,
+              handlerRef: sourceRef,
+              selectorHint: null
+            });
+          } else if (call.kind !== 'VALIDATION_BLOCK') {
+            contracts.push({
+              kind: call.kind || 'NETWORK_ACTION',
+              method: call.method,
+              urlPath: call.url,
+              source: sourceRef,
+              elementType: path.parent.name.name,
+              handlerRef: sourceRef
+            });
+          }
+        }
+      } else if (
+        value.type === 'JSXExpressionContainer' &&
+        value.expression.type === 'Identifier'
+      ) {
+        const refName = value.expression.name;
+        const handlerRecord = functionBodies.get(refName);
+
+        if (handlerRecord) {
+          const networkCalls = findNetworkCallsInNode(handlerRecord.body);
+
+          for (const call of networkCalls) {
+            const loc = path.node.loc;
+            const sourceRef = formatSourceRef(filePath, workspaceRoot, loc, lineOffset);
+
+            if (call.kind === 'VALIDATION_BLOCK' && isSubmitHandler) {
+              contracts.push({
+                kind: 'VALIDATION_BLOCK',
+                method: call.method,
+                urlPath: null,
+                source: sourceRef,
+                elementType: path.parent.name.name,
+                handlerRef: sourceRef,
+                selectorHint: null
+              });
+            } else if (call.kind !== 'VALIDATION_BLOCK') {
+              contracts.push({
+                kind: call.kind || 'NETWORK_ACTION',
+                method: call.method,
+                urlPath: call.url,
+                source: sourceRef,
+                elementType: path.parent.name.name,
+                handlerRef: sourceRef
+              });
+            }
+          }
+        }
+      }
+    },
+
+    // DOM addEventListener handlers (static HTML/JS)
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'addEventListener'
+      ) {
+        const args = path.node.arguments || [];
+        if (args.length < 2) return;
+
+        const eventArg = args[0];
+        const handlerArg = args[1];
+        const eventType = eventArg && eventArg.type === 'StringLiteral' ? eventArg.value : 'event';
+
+        let handlerBody = null;
+        let handlerLoc = handlerArg?.loc || path.node.loc;
+
+        if (handlerArg && (handlerArg.type === 'ArrowFunctionExpression' || handlerArg.type === 'FunctionExpression')) {
+          handlerBody = handlerArg.body;
+          handlerLoc = handlerArg.loc || path.node.loc;
+        } else if (handlerArg && handlerArg.type === 'Identifier') {
+          const record = functionBodies.get(handlerArg.name);
+          if (record) {
+            handlerBody = record.body;
+            handlerLoc = record.loc || path.node.loc;
+          }
+        }
+
+        if (!handlerBody) return;
+
+        const networkCalls = findNetworkCallsInNode(handlerBody);
+        const isSubmitEvent = eventType === 'submit';
+        
+        for (const call of networkCalls) {
+          const handlerRef = formatSourceRef(filePath, workspaceRoot, handlerLoc, lineOffset);
+          
+          if (call.kind === 'VALIDATION_BLOCK' && isSubmitEvent) {
+            contracts.push({
+              kind: 'VALIDATION_BLOCK',
+              method: call.method,
+              urlPath: null,
+              source: handlerRef,
+              handlerRef: `${handlerRef}#${eventType}`,
+              elementType: 'dom',
+              selectorHint: null
+            });
+          } else if (call.kind !== 'VALIDATION_BLOCK') {
+            contracts.push({
+              kind: call.kind || 'NETWORK_ACTION',
+              method: call.method,
+              urlPath: call.url,
+              source: handlerRef,
+              handlerRef: `${handlerRef}#${eventType}`,
+              elementType: 'dom'
+            });
+          }
+        }
+      }
+    }
+  });
 
   return contracts;
 }
 
 /**
- * Find network calls (fetch, axios) in an AST node by recursively scanning.
- * Only returns calls with static URL literals.
+ * Extract template literal pattern from node.
+ * Returns null if template has complex expressions.
+ */
+function extractTemplateLiteralPath(node) {
+  if (!node || node.type !== 'TemplateLiteral') {
+    return null;
+  }
+  
+  // Build template string
+  let templateStr = node.quasis[0]?.value?.cooked || '';
+  
+  for (let i = 0; i < node.expressions.length; i++) {
+    const expr = node.expressions[i];
+    
+    // Only support simple identifiers
+    if (expr.type === 'Identifier') {
+      templateStr += '${' + expr.name + '}';
+    } else {
+      return null;
+    }
+    
+    if (node.quasis[i + 1]) {
+      templateStr += node.quasis[i + 1].value.cooked || '';
+    }
+  }
+  
+  return templateStr;
+}
+
+/**
+ * Find action calls (fetch, axios, router.push, navigate) in an AST node by recursively scanning.
+ * Only returns calls with static URL/path literals or template patterns.
  * 
  * @param {Object} node - AST node to scan
- * @returns {Array<Object>} - Array of {method, url}
+ * @returns {Array<Object>} - Array of {kind, method, url} where kind is 'NETWORK_ACTION' or 'NAVIGATION_ACTION'
  */
 function findNetworkCallsInNode(node) {
   const calls = [];
+  
+  // Track if we found preventDefault or return false for validation block detection
+  let hasPreventDefault = false;
+  let hasReturnFalse = false;
 
   // Recursive function to scan all nodes
   function scan(n) {
@@ -156,7 +277,7 @@ function findNetworkCallsInNode(node) {
             }
           }
 
-          calls.push({ method, url: urlArg.value });
+          calls.push({ kind: 'NETWORK_ACTION', method, url: urlArg.value });
         }
       }
 
@@ -171,7 +292,7 @@ function findNetworkCallsInNode(node) {
        const urlArg = n.arguments[0];
 
         if (urlArg && urlArg.type === 'StringLiteral') {
-          calls.push({ method: methodName, url: urlArg.value });
+          calls.push({ kind: 'NETWORK_ACTION', method: methodName, url: urlArg.value });
         }
       }
 
@@ -190,11 +311,85 @@ function findNetworkCallsInNode(node) {
           urlArg && urlArg.type === 'StringLiteral'
         ) {
           calls.push({
+            kind: 'NETWORK_ACTION',
             method: methodArg.value.toUpperCase(),
             url: urlArg.value,
           });
         }
       }
+      
+      // Case 4: router.push(path), router.replace(path), history.push(path)
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.object.type === 'Identifier' &&
+        (callee.object.name === 'router' || callee.object.name === 'history') &&
+        callee.property.type === 'Identifier' &&
+        ['push', 'replace', 'navigate'].includes(callee.property.name)
+      ) {
+        const pathArg = n.arguments[0];
+        if (pathArg && pathArg.type === 'StringLiteral') {
+          calls.push({
+            kind: 'NAVIGATION_ACTION',
+            method: `${callee.object.name}.${callee.property.name}`,
+            url: pathArg.value
+          });
+        } else if (pathArg && pathArg.type === 'TemplateLiteral') {
+          // Template literal: router.push(`/users/${id}`)
+          const templatePath = extractTemplateLiteralPath(pathArg);
+          if (templatePath && templatePath.startsWith('/')) {
+            // Normalize to example path
+            const normalized = normalizeTemplateLiteral(templatePath);
+            calls.push({
+              kind: 'NAVIGATION_ACTION',
+              method: `${callee.object.name}.${callee.property.name}`,
+              url: normalized ? normalized.examplePath : templatePath
+            });
+          }
+        }
+      }
+      
+      // Case 5: navigate(path) - standalone function
+      if (callee.type === 'Identifier' && callee.name === 'navigate') {
+        const pathArg = n.arguments[0];
+        if (pathArg && pathArg.type === 'StringLiteral') {
+          calls.push({
+            kind: 'NAVIGATION_ACTION',
+            method: 'navigate',
+            url: pathArg.value
+          });
+        } else if (pathArg && pathArg.type === 'TemplateLiteral') {
+          // Template literal: navigate(`/users/${id}`)
+          const templatePath = extractTemplateLiteralPath(pathArg);
+          if (templatePath && templatePath.startsWith('/')) {
+            // Normalize to example path
+            const normalized = normalizeTemplateLiteral(templatePath);
+            calls.push({
+              kind: 'NAVIGATION_ACTION',
+              method: 'navigate',
+              url: normalized ? normalized.examplePath : templatePath
+            });
+          }
+        }
+      }
+      
+      // Case 6: event.preventDefault() - validation block
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'preventDefault'
+      ) {
+        hasPreventDefault = true;
+      }
+   }
+   
+   // Check for return false statement
+   if (n.type === 'ReturnStatement' && n.argument) {
+     if (
+       (n.argument.type === 'BooleanLiteral' && n.argument.value === false) ||
+       (n.argument.type === 'Identifier' && n.argument.name === 'false')
+     ) {
+       hasReturnFalse = true;
+     }
    }
    
    // Recursively scan all properties
@@ -211,6 +406,16 @@ function findNetworkCallsInNode(node) {
   }
 
   scan(node);
+  
+  // If validation block detected, add VALIDATION_BLOCK contract
+  if (hasPreventDefault || hasReturnFalse) {
+    calls.push({
+      kind: 'VALIDATION_BLOCK',
+      method: hasPreventDefault ? 'preventDefault' : 'return-false',
+      url: null
+    });
+  }
+  
   return calls;
 }
 
@@ -223,14 +428,14 @@ function findNetworkCallsInNode(node) {
  * @param {Object} loc - Location object from AST
  * @returns {string} - Formatted source reference
  */
-function formatSourceRef(filePath, workspaceRoot, loc) {
+function formatSourceRef(filePath, workspaceRoot, loc, lineOffset = 0) {
   let relPath = relative(workspaceRoot, filePath);
   
   // Normalize to forward slashes
   relPath = relPath.split(sep).join('/');
   
-  const line = loc.start.line;
-  const col = loc.start.column;
+  const line = (loc?.start?.line || 1) + lineOffset;
+  const col = loc?.start?.column || 0;
   
   return `${relPath}:${line}:${col}`;
 }
@@ -260,14 +465,43 @@ export async function scanForContracts(rootPath, workspaceRoot) {
         
         if (stat.isDirectory()) {
           // Skip node_modules, .git, etc.
-          if (!entry.startsWith('.') && entry !== 'node_modules') {
+          const ignoredDirs = new Set([
+            'node_modules',
+            '.git',
+            '.verax',
+            'dist',
+            'build',
+            'out',
+            'artifacts',
+            'logs',
+            'temp-installs',
+            'tmp',
+            'temp'
+          ]);
+          if (!entry.startsWith('.') && !ignoredDirs.has(entry)) {
             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);
+          } else if (/\.html?$/.test(entry)) {
+            try {
+              const html = readFileSync(fullPath, 'utf-8');
+              const scriptRegex = /<script[^>]*>([\s\S]*?)<\/script>/gi;
+              let match;
+              while ((match = scriptRegex.exec(html)) !== null) {
+                const tagOpen = html.slice(match.index, html.indexOf('>', match.index) + 1);
+                if (/\ssrc=/i.test(tagOpen)) continue; // skip external scripts
+                const before = html.slice(0, match.index);
+                const lineOffset = (before.match(/\n/g) || []).length;
+                const code = match[1];
+                const blockContracts = extractActionContractsFromCode(fullPath, workspaceRoot, code, lineOffset + 1);
+                contracts.push(...blockContracts);
+              }
+            } catch (err) {
+              console.warn(`Failed to parse HTML scripts in ${fullPath}: ${err.message}`);
+            }
           }
         }
       }

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

@@ -4,6 +4,7 @@ import { readFileSync } from 'fs';
 import { glob } from 'glob';
 import { resolve } from 'path';
 import { ExpectationProof } from '../shared/expectation-proof.js';
+import { normalizeTemplateLiteral } from '../shared/dynamic-route-utils.js';
 
 const MAX_FILES_TO_SCAN = 200;
 
@@ -45,18 +46,73 @@ function extractStaticStringValue(node) {
   return null;
 }
 
+/**
+ * Extracts template literal pattern from Babel TemplateLiteral node.
+ * Returns null if template has complex expressions that cannot be normalized.
+ * 
+ * Examples:
+ * - `${id}` → { pattern: '${id}', examplePath: '/1' }
+ * - `/users/${id}` → { pattern: '/users/${id}', examplePath: '/users/1' }
+ * - `/posts/${slug}` → { pattern: '/posts/${slug}', examplePath: '/posts/example' }
+ */
+function extractTemplatePattern(templateNode) {
+  if (!templateNode || templateNode.type !== 'TemplateLiteral') {
+    return null;
+  }
+  
+  // Build the template string with ${} placeholders
+  let templateStr = templateNode.quasis[0]?.value?.cooked || '';
+  
+  for (let i = 0; i < templateNode.expressions.length; i++) {
+    const expr = templateNode.expressions[i];
+    
+    // Only support simple identifiers: ${id}, ${slug}
+    if (expr.type === 'Identifier') {
+      templateStr += '${' + expr.name + '}';
+    } else {
+      // Complex expressions like function calls - cannot normalize
+      return null;
+    }
+    
+    // Add the next quasi
+    if (templateNode.quasis[i + 1]) {
+      templateStr += templateNode.quasis[i + 1].value.cooked || '';
+    }
+  }
+  
+  // Must be a valid route pattern (start with /)
+  if (!templateStr.startsWith('/')) {
+    return null;
+  }
+  
+  // Normalize to example path
+  const normalized = normalizeTemplateLiteral(templateStr);
+  if (normalized) {
+    return {
+      pattern: templateStr,
+      examplePath: normalized.examplePath,
+      isDynamic: true,
+      originalPattern: normalized.originalPattern
+    };
+  }
+  
+  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">
+ * Supported patterns (all require static string literals or template patterns):
+ * - Next.js: <Link href="/about"> or <Link href={`/about`}>
+ * - React Router: <Link to="/about"> or <RouterLink :to="`/users/${id}`">
  * - Plain JSX: <a href="/about">
- * - Imperative: navigate("/about"), router.push("/about")
+ * - Imperative: navigate("/about"), router.push("/about"), router.push(`/users/${id}`)
  * 
  * Returns array of contracts with:
  * - kind: 'NAVIGATION'
- * - targetPath: string
+ * - targetPath: string (example path for dynamic routes)
+ * - originalPattern: string (original pattern for dynamic routes)
+ * - isDynamic: boolean (true if dynamic route)
  * - sourceFile: string
  * - element: 'Link' | 'NavLink' | 'a' | 'navigate' | 'router'
  * - attribute: 'href' | 'to' (for runtime matching)
@@ -138,6 +194,23 @@ function extractContractsFromFile(filePath, fileContent) {
                 imperativeOnly: true // Cannot match to DOM element
               });
             }
+          } else if (firstArg && firstArg.type === 'TemplateLiteral') {
+            // Template literal: navigate(`/users/${id}`)
+            const templatePattern = extractTemplatePattern(firstArg);
+            if (templatePattern) {
+              contracts.push({
+                kind: 'NAVIGATION',
+                targetPath: templatePattern.examplePath,
+                originalPattern: templatePattern.pattern,
+                isDynamic: true,
+                sourceFile: filePath,
+                element: 'navigate',
+                attribute: null,
+                proof: ExpectationProof.PROVEN_EXPECTATION,
+                line: path.node.loc?.start.line || null,
+                imperativeOnly: true // Cannot match to DOM element
+              });
+            }
           }
         }
         
@@ -162,6 +235,23 @@ function extractContractsFromFile(filePath, fileContent) {
                 imperativeOnly: true // Cannot match to DOM element
               });
             }
+          } else if (firstArg && firstArg.type === 'TemplateLiteral') {
+            // Template literal: router.push(`/users/${id}`)
+            const templatePattern = extractTemplatePattern(firstArg);
+            if (templatePattern) {
+              contracts.push({
+                kind: 'NAVIGATION',
+                targetPath: templatePattern.examplePath,
+                originalPattern: templatePattern.pattern,
+                isDynamic: true,
+                sourceFile: filePath,
+                element: 'router',
+                attribute: null,
+                proof: ExpectationProof.PROVEN_EXPECTATION,
+                line: path.node.loc?.start.line || null,
+                imperativeOnly: true // Cannot match to DOM element
+              });
+            }
           }
         }
       }