@veraxhq/verax 0.1.0

package/src/verax/learn/source-instrumenter.js

@@ -0,0 +1,214 @@
+/**
+ * Wave 5 — Source Instrumentation
+ * 
+ * Babel transform to inject data-verax-source attributes into JSX elements
+ * with onClick/onSubmit handlers for runtime attribution.
+ * 
+ * This allows matching runtime interactions to source code locations.
+ */
+
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+import generate from '@babel/generator';
+import * as t from '@babel/types';
+import { relative, sep, resolve as pathResolve, dirname as pathDirname, join as pathJoin } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Instrument JSX code with data-verax-source attributes.
+ * 
+ * @param {string} code - Source code to instrument
+ * @param {string} filePath - Absolute path to source file
+ * @param {string} workspaceRoot - Workspace root for relative paths
+ * @returns {string} - Instrumented code
+ */
+export function instrumentJSX(code, filePath, workspaceRoot) {
+  try {
+    const ast = parse(code, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+    const importMap = buildImportMap(ast, filePath, workspaceRoot);
+
+    traverse.default(ast, {
+      JSXOpeningElement(path) {
+        const attributes = path.node.attributes;
+         const elementName = path.node.name;
+        
+        // Check if this element has onClick or onSubmit
+        const hasHandler = attributes.some((attr) => {
+          return (
+            attr.type === 'JSXAttribute' &&
+            attr.name &&
+            attr.name.name &&
+            (attr.name.name === 'onClick' || attr.name.name === 'onSubmit')
+          );
+        });
+
+         // Also check if it's a Link element with navigation props
+         const isLinkWithNav = 
+           elementName.type === 'JSXIdentifier' &&
+           elementName.name === 'Link' &&
+           attributes.some((attr) => {
+             return (
+               attr.type === 'JSXAttribute' &&
+               attr.name &&
+               attr.name.name &&
+               (attr.name.name === 'href' || attr.name.name === 'to')
+             );
+           });
+
+         if (!hasHandler && !isLinkWithNav) return;
+
+        // Check if already instrumented
+        const alreadyInstrumented = attributes.some((attr) => {
+          return (
+            attr.type === 'JSXAttribute' &&
+            attr.name &&
+            attr.name.name === 'data-verax-source'
+          );
+        });
+
+        // Add sourceRef if missing
+        if (!alreadyInstrumented) {
+          const loc = path.node.loc;
+          const sourceRef = formatSourceRef(filePath, workspaceRoot, loc);
+          const sourceAttr = t.jsxAttribute(
+            t.jsxIdentifier('data-verax-source'),
+            t.stringLiteral(sourceRef)
+          );
+          path.node.attributes.push(sourceAttr);
+        }
+
+        // Add handlerRef for identifier handlers
+        const handlerAttr = attributes.find((attr) => (
+          attr.type === 'JSXAttribute' &&
+          attr.name?.name &&
+          (attr.name.name === 'onClick' || attr.name.name === 'onSubmit')
+        ));
+        if (handlerAttr && handlerAttr.value && handlerAttr.value.type === 'JSXExpressionContainer') {
+          const expr = handlerAttr.value.expression;
+          if (expr && expr.type === 'Identifier') {
+            const handlerRef = deriveHandlerRef(expr.name, importMap, filePath, workspaceRoot);
+            if (handlerRef) {
+              const hasHandlerRef = attributes.some((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'data-verax-handler');
+              if (!hasHandlerRef) {
+                const handlerAttrNode = t.jsxAttribute(
+                  t.jsxIdentifier('data-verax-handler'),
+                  t.stringLiteral(handlerRef)
+                );
+                path.node.attributes.push(handlerAttrNode);
+              }
+            }
+          }
+        }
+      },
+    });
+
+    const output = generate.default(ast, {
+      retainLines: true,
+      compact: false,
+    });
+
+    return output.code;
+  } catch (err) {
+    console.warn(`Failed to instrument ${filePath}: ${err.message}`);
+    return code; // Return original code on error
+  }
+}
+
+/**
+ * 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}`;
+}
+
+/**
+ * Instrument a file and write to output path.
+ * 
+ * @param {string} inputPath - Input file path
+ * @param {string} outputPath - Output file path
+ * @param {string} workspaceRoot - Workspace root
+ */
+export async function instrumentFile(inputPath, outputPath, workspaceRoot) {
+  const { readFileSync, writeFileSync } = await import('fs');
+  const { dirname } = await import('path');
+  const { mkdirSync } = await import('fs');
+  
+  const code = readFileSync(inputPath, 'utf-8');
+  const instrumented = instrumentJSX(code, inputPath, workspaceRoot);
+  
+  // Ensure output directory exists
+  mkdirSync(dirname(outputPath), { recursive: true });
+  
+  writeFileSync(outputPath, instrumented, 'utf-8');
+}
+
+// === Handler Reference Helpers ===
+
+const EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+function buildImportMap(ast, filePath, workspaceRoot) {
+  const map = new Map(); // localName -> { modulePath, exportName }
+  const fileDir = pathDirname(filePath);
+
+  traverse.default(ast, {
+    ImportDeclaration(path) {
+      const source = path.node.source.value;
+      const resolved = resolveModulePath(source, fileDir, workspaceRoot);
+      if (!resolved) return;
+
+      const specifiers = path.node.specifiers || [];
+      for (const spec of specifiers) {
+        if (spec.type === 'ImportDefaultSpecifier') {
+          map.set(spec.local.name, { modulePath: resolved, exportName: 'default' });
+        } else if (spec.type === 'ImportSpecifier') {
+          const imported = spec.imported.name;
+          map.set(spec.local.name, { modulePath: resolved, exportName: imported });
+        }
+      }
+    }
+  });
+
+  return map;
+}
+
+function resolveModulePath(specifier, fromDir, workspaceRoot) {
+  if (specifier.startsWith('.') || specifier.startsWith('/')) {
+    const base = specifier.startsWith('.') ? pathResolve(fromDir, specifier) : pathResolve(workspaceRoot, specifier);
+    const candidates = [base, ...EXTENSIONS.map(ext => base + ext), ...EXTENSIONS.map(ext => pathJoin(base, 'index' + ext))];
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) {
+        return relative(workspaceRoot, candidate).split(sep).join('/');
+      }
+    }
+    return null;
+  }
+  // External module - not resolved
+  return null;
+}
+
+function deriveHandlerRef(name, importMap, filePath, workspaceRoot) {
+  const entry = importMap.get(name);
+  if (entry) {
+    return `${entry.modulePath}#${entry.exportName}`;
+  }
+  const localPath = relative(workspaceRoot, filePath).split(sep).join('/');
+  return `${localPath}#${name}`;
+}

package/src/verax/learn/static-extractor.js

@@ -0,0 +1,222 @@
+import { glob } from 'glob';
+import { resolve, dirname, join, relative } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { parse } from 'node-html-parser';
+import { ExpectationProof } from '../shared/expectation-proof.js';
+
+const MAX_HTML_FILES = 200;
+
+function htmlFileToRoute(file) {
+  let path = file.replace(/[\\\/]/g, '/');
+  path = path.replace(/\/index\.html$/, '');
+  path = path.replace(/\.html$/, '');
+  path = path.replace(/^index$/, '');
+  
+  if (path === '' || path === '/') {
+    return '/';
+  }
+  if (!path.startsWith('/')) {
+    path = '/' + path;
+  }
+  
+  return path;
+}
+
+function resolveLinkPath(href, fromFile, projectDir) {
+  if (!href || href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:')) {
+    return null;
+  }
+  
+  if (href.startsWith('http://') || href.startsWith('https://')) {
+    return null;
+  }
+  
+  try {
+    if (href.startsWith('/')) {
+      return htmlFileToRoute(href);
+    }
+    
+    const fromDir = dirname(resolve(projectDir, fromFile));
+    const resolved = resolve(fromDir, href);
+    const relativePath = relative(projectDir, resolved);
+    
+    if (relativePath.startsWith('..')) {
+      return null;
+    }
+    
+    return htmlFileToRoute(relativePath);
+  } catch (error) {
+    return null;
+  }
+}
+
+export async function extractStaticRoutes(projectDir) {
+  const routes = [];
+  const routeSet = new Set();
+  
+  const htmlFiles = await glob('**/*.html', {
+    cwd: projectDir,
+    absolute: false,
+    ignore: ['node_modules/**']
+  });
+  
+  for (const file of htmlFiles.slice(0, MAX_HTML_FILES)) {
+    const routePath = htmlFileToRoute(file);
+    const routeKey = routePath;
+    
+    if (!routeSet.has(routeKey)) {
+      routeSet.add(routeKey);
+      routes.push({
+        path: routePath,
+        source: file,
+        public: true
+      });
+    }
+  }
+  
+  routes.sort((a, b) => a.path.localeCompare(b.path));
+  
+  return routes;
+}
+
+function extractButtonNavigationExpectations(root, fromPath, file, routeMap, projectDir) {
+  const expectations = [];
+  
+  const buttons = root.querySelectorAll('button');
+  for (const button of buttons) {
+    let targetPath = null;
+    let selectorHint = null;
+    
+    const buttonId = button.getAttribute('id');
+    const dataHref = button.getAttribute('data-href');
+    const onclick = button.getAttribute('onclick') || '';
+    
+    if (dataHref) {
+      targetPath = resolveLinkPath(dataHref, file, projectDir);
+      if (targetPath && routeMap.has(targetPath)) {
+        selectorHint = buttonId ? `#${buttonId}` : `button[data-href="${dataHref}"]`;
+      }
+    } else if (onclick) {
+      const locationMatch = onclick.match(/window\.location\s*=\s*['"]([^'"]+)['"]|document\.location\s*=\s*['"]([^'"]+)['"]/);
+      if (locationMatch) {
+        const href = locationMatch[1] || locationMatch[2];
+        targetPath = resolveLinkPath(href, file, projectDir);
+        if (targetPath && routeMap.has(targetPath)) {
+          selectorHint = buttonId ? `#${buttonId}` : `button[onclick*="${href}"]`;
+        }
+      }
+    } else {
+      const parentLink = button.closest('a[href]');
+      if (parentLink) {
+        const href = parentLink.getAttribute('href');
+        targetPath = resolveLinkPath(href, file, projectDir);
+        if (targetPath && routeMap.has(targetPath)) {
+          selectorHint = buttonId ? `#${buttonId}` : `button`;
+        }
+      }
+    }
+    
+    if (targetPath && selectorHint) {
+      expectations.push({
+        fromPath: fromPath,
+        type: 'navigation',
+        targetPath: targetPath,
+        proof: ExpectationProof.PROVEN_EXPECTATION,
+        evidence: {
+          source: file,
+          selectorHint: selectorHint
+        }
+      });
+    }
+  }
+  
+  return expectations;
+}
+
+function extractFormSubmissionExpectations(root, fromPath, file, routeMap, projectDir) {
+  const expectations = [];
+  
+  const forms = root.querySelectorAll('form[action]');
+  for (const form of forms) {
+    const action = form.getAttribute('action');
+    if (!action) continue;
+    
+    const targetPath = resolveLinkPath(action, file, projectDir);
+    if (!targetPath || !routeMap.has(targetPath)) continue;
+    
+    const formId = form.getAttribute('id');
+    const selectorHint = formId ? `#${formId}` : `form[action="${action}"]`;
+    
+    expectations.push({
+      fromPath: fromPath,
+      type: 'form_submission',
+      targetPath: targetPath,
+      proof: ExpectationProof.PROVEN_EXPECTATION,
+      evidence: {
+        source: file,
+        selectorHint: selectorHint
+      }
+    });
+  }
+  
+  return expectations;
+}
+
+export async function extractStaticExpectations(projectDir, routes) {
+  const expectations = [];
+  const routeMap = new Map(routes.map(r => [r.path, r]));
+  
+  const htmlFiles = await glob('**/*.html', {
+    cwd: projectDir,
+    absolute: false,
+    ignore: ['node_modules/**']
+  });
+  
+  for (const file of htmlFiles.slice(0, MAX_HTML_FILES)) {
+    const fromPath = htmlFileToRoute(file);
+    const filePath = resolve(projectDir, file);
+    
+    if (!existsSync(filePath)) continue;
+    
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const root = parse(content);
+      
+      const links = root.querySelectorAll('a[href]');
+      for (const link of links) {
+        const href = link.getAttribute('href');
+        if (!href) continue;
+        
+        const targetPath = resolveLinkPath(href, file, projectDir);
+        if (!targetPath) continue;
+        
+        if (!routeMap.has(targetPath)) continue;
+        
+        const linkText = link.textContent?.trim() || '';
+        const selectorHint = link.id ? `#${link.id}` : `a[href="${href}"]`;
+        
+        expectations.push({
+          fromPath: fromPath,
+          type: 'navigation',
+          targetPath: targetPath,
+          proof: ExpectationProof.PROVEN_EXPECTATION,
+          evidence: {
+            source: file,
+            selectorHint: selectorHint
+          }
+        });
+      }
+      
+      const buttonExpectations = extractButtonNavigationExpectations(root, fromPath, file, routeMap, projectDir);
+      expectations.push(...buttonExpectations);
+      
+      const formExpectations = extractFormSubmissionExpectations(root, fromPath, file, routeMap, projectDir);
+      expectations.push(...formExpectations);
+    } catch (error) {
+      continue;
+    }
+  }
+  
+  return expectations;
+}
+

package/src/verax/learn/truth-assessor.js

@@ -0,0 +1,96 @@
+import { glob } from 'glob';
+import { hasReactRouterDom } from './project-detector.js';
+
+const MAX_HTML_FILES = 200;
+
+export async function assessLearnTruth(projectDir, projectType, routes, staticExpectations, spaExpectations = null) {
+  const truth = {
+    routesDiscovered: routes.length,
+    routesSource: 'none',
+    routesConfidence: 'LOW',
+    expectationsDiscovered: 0,
+    expectationsStrong: 0,
+    expectationsWeak: 0,
+    warnings: [],
+    limitations: []
+  };
+  
+  if (projectType === 'nextjs_app_router' || projectType === 'nextjs_pages_router') {
+    truth.routesSource = 'nextjs_fs';
+    truth.routesConfidence = 'HIGH';
+    
+    // Wave 1 - CODE TRUTH ENGINE: Count AST-derived expectations
+    if (spaExpectations && spaExpectations.length > 0) {
+      truth.expectationsDiscovered = spaExpectations.length;
+      truth.expectationsStrong = spaExpectations.length;
+      truth.expectationsWeak = 0;
+      truth.expectationsSource = 'ast_contracts';
+    }
+  } else if (projectType === 'static') {
+    truth.routesSource = 'static_html';
+    
+    const htmlFiles = await glob('**/*.html', {
+      cwd: projectDir,
+      absolute: false,
+      ignore: ['node_modules/**']
+    });
+    
+    if (htmlFiles.length <= MAX_HTML_FILES) {
+      truth.routesConfidence = 'HIGH';
+    } else {
+      truth.routesConfidence = 'MEDIUM';
+      truth.warnings.push({
+        code: 'HTML_SCAN_CAPPED',
+        message: `HTML file count (${htmlFiles.length}) exceeds cap (${MAX_HTML_FILES}). Some routes may be missed.`
+      });
+    }
+    
+    if (staticExpectations) {
+      truth.expectationsDiscovered = staticExpectations.length;
+      truth.expectationsStrong = staticExpectations.filter(e => 
+        e.type === 'navigation' || e.type === 'form_submission'
+      ).length;
+      truth.expectationsWeak = 0;
+    }
+  } else if (projectType === 'react_spa') {
+    truth.routesSource = 'react_router_regex';
+    truth.routesConfidence = 'MEDIUM';
+    
+    const hasRouter = await hasReactRouterDom(projectDir);
+    if (!hasRouter || routes.length === 0) {
+      truth.routesConfidence = 'LOW';
+      truth.limitations.push({
+        code: 'REACT_ROUTES_NOT_FOUND',
+        message: hasRouter 
+          ? 'React Router detected but no routes extracted. Route extraction may have failed.'
+          : 'react-router-dom not detected in package.json. Routes cannot be extracted.'
+      });
+    }
+    
+    // Wave 1 - CODE TRUTH ENGINE: Report AST-based expectations instead of routes
+    if (spaExpectations && spaExpectations.length > 0) {
+      truth.expectationsDiscovered = spaExpectations.length;
+      truth.expectationsStrong = spaExpectations.length;
+      truth.expectationsWeak = 0;
+      truth.expectationsSource = 'ast_contracts';
+    } else {
+      truth.expectationsDiscovered = 0;
+      truth.expectationsStrong = 0;
+      truth.expectationsWeak = 0;
+      truth.warnings.push({
+        code: 'NO_AST_CONTRACTS_FOUND',
+        message: 'No JSX Link/NavLink elements with static href/to found. No PROVEN expectations available.'
+      });
+    }
+  } else if (projectType === 'unknown') {
+    truth.routesSource = 'none';
+    truth.routesConfidence = 'LOW';
+    truth.limitations.push({
+      code: 'PROJECT_TYPE_UNKNOWN',
+      message: 'Project type could not be determined. No routes or expectations can be extracted.'
+    });
+  }
+  
+  return truth;
+}
+