@veraxhq/verax 0.1.0

package/src/verax/learn/manifest-writer.js

@@ -0,0 +1,97 @@
+import { resolve } from 'path';
+import { writeFileSync, mkdirSync } from 'fs';
+import { extractStaticExpectations } from './static-extractor.js';
+import { assessLearnTruth } from './truth-assessor.js';
+import { ExpectationProof } from '../shared/expectation-proof.js';
+import { extractASTContracts, contractsToExpectations } from './ast-contract-extractor.js';
+import { scanForContracts } from './action-contract-extractor.js';
+import { resolveActionContracts } from './ts-contract-resolver.js';
+
+export async function writeManifest(projectDir, projectType, routes) {
+  const publicRoutes = routes.filter(r => r.public).map(r => r.path);
+  const internalRoutes = routes.filter(r => !r.public).map(r => r.path);
+  
+  const manifest = {
+    version: 1,
+    learnedAt: new Date().toISOString(),
+    projectDir: projectDir,
+    projectType: projectType,
+    routes: routes.map(r => ({
+      path: r.path,
+      source: r.source,
+      public: r.public
+    })),
+    publicRoutes: publicRoutes,
+    internalRoutes: internalRoutes,
+    notes: []
+  };
+  
+  let staticExpectations = null;
+  let spaExpectations = null;
+  let actionContracts = null;
+  
+  if (projectType === 'static' && routes.length > 0) {
+    staticExpectations = await extractStaticExpectations(projectDir, routes);
+    manifest.staticExpectations = staticExpectations;
+    manifest.expectationProof = ExpectationProof.PROVEN_EXPECTATION;
+  } else if (projectType === 'react_spa' || projectType.startsWith('nextjs_')) {
+    // Wave 1 - CODE TRUTH ENGINE: Extract PROVEN contracts from AST
+    const contracts = await extractASTContracts(projectDir);
+    spaExpectations = contractsToExpectations(contracts, projectType);
+    
+    if (spaExpectations.length > 0) {
+      manifest.spaExpectations = spaExpectations;
+      manifest.expectationProof = ExpectationProof.PROVEN_EXPECTATION;
+    } else {
+      manifest.expectationProof = ExpectationProof.UNKNOWN_EXPECTATION;
+    }
+  } else {
+    manifest.expectationProof = ExpectationProof.UNKNOWN_EXPECTATION;
+  }
+  
+  // Wave 5/6 - ACTION CONTRACTS: Extract network action contracts (Babel inline + TS cross-file)
+  const shouldExtractActions = projectType === 'react_spa' || projectType.startsWith('nextjs_');
+  if (shouldExtractActions) {
+    const [babelContracts, tsContracts] = await Promise.all([
+      scanForContracts(projectDir, projectDir),
+      resolveActionContracts(projectDir, projectDir).catch(() => [])
+    ]);
+    const merged = dedupeActionContracts([...(babelContracts || []), ...(tsContracts || [])]);
+    if (merged.length > 0) {
+      actionContracts = merged;
+      manifest.actionContracts = actionContracts;
+    }
+  }
+
+  const learnTruth = await assessLearnTruth(projectDir, projectType, routes, staticExpectations, spaExpectations);
+  manifest.notes.push({
+    type: 'truth',
+    learn: learnTruth
+  });
+  
+  const manifestDir = resolve(projectDir, '.verax', 'learn');
+  mkdirSync(manifestDir, { recursive: true });
+  
+  const manifestPath = resolve(manifestDir, 'site-manifest.json');
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  
+  return {
+    ...manifest,
+    manifestPath: manifestPath,
+    learnTruth: learnTruth,
+    actionContracts
+  };
+}
+
+function dedupeActionContracts(contracts) {
+  const seen = new Set();
+  const out = [];
+  for (const c of contracts) {
+    const key = `${c.kind}|${c.method}|${c.urlPath}|${c.source || ''}|${c.handlerRef || ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  return out;
+}
+

package/src/verax/learn/project-detector.js

@@ -0,0 +1,87 @@
+import { glob } from 'glob';
+import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+async function hasReactDependency(projectDir) {
+  try {
+    const packageJsonPath = resolve(projectDir, 'package.json');
+    if (!existsSync(packageJsonPath)) return false;
+    
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    
+    return !!deps.react;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function hasNextJs(projectDir) {
+  try {
+    const packageJsonPath = resolve(projectDir, 'package.json');
+    if (!existsSync(packageJsonPath)) return false;
+    
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    
+    return !!deps.next;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function hasReactRouter(projectDir) {
+  try {
+    const packageJsonPath = resolve(projectDir, 'package.json');
+    if (!existsSync(packageJsonPath)) return false;
+    
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    
+    return !!deps['react-router-dom'] || !!deps['react-router'];
+  } catch (error) {
+    return false;
+  }
+}
+
+export async function detectProjectType(projectDir) {
+  const appDir = resolve(projectDir, 'app');
+  const pagesDir = resolve(projectDir, 'pages');
+  
+  try {
+    if (existsSync(appDir)) {
+      const appFiles = await glob('**/page.{js,jsx,ts,tsx}', { cwd: appDir, absolute: false });
+      if (appFiles.length > 0) {
+        return 'nextjs_app_router';
+      }
+    }
+    
+    if (existsSync(pagesDir)) {
+      const pagesFiles = await glob('**/*.{js,jsx,ts,tsx}', { cwd: pagesDir, absolute: false });
+      if (pagesFiles.length > 0) {
+        return 'nextjs_pages_router';
+      }
+    }
+    
+    const hasReact = await hasReactDependency(projectDir);
+    const hasNext = await hasNextJs(projectDir);
+    
+    if (hasReact && !hasNext) {
+      return 'react_spa';
+    }
+    
+    const htmlFiles = await glob('**/*.html', { cwd: projectDir, absolute: false, ignore: ['node_modules/**'] });
+    if (htmlFiles.length > 0) {
+      return 'static';
+    }
+  } catch (error) {
+    // Fall through to unknown
+  }
+  
+  return 'unknown';
+}
+
+export async function hasReactRouterDom(projectDir) {
+  return await hasReactRouter(projectDir);
+}
+

package/src/verax/learn/react-router-extractor.js

@@ -0,0 +1,73 @@
+import { glob } from 'glob';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+export async function extractReactRouterRoutes(projectDir) {
+  const routes = [];
+  const routeSet = new Set();
+  
+  const jsFiles = await glob('**/*.{js,jsx,ts,tsx}', {
+    cwd: projectDir,
+    absolute: false,
+    ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**']
+  });
+  
+  for (const file of jsFiles.slice(0, 200)) {
+    try {
+      const content = readFileSync(resolve(projectDir, file), 'utf-8');
+      
+      const routePatterns = [
+        /<Route\s+path=["']([^"']+)["']/g,
+        /path:\s*["']([^"']+)["']/g,
+        /path\s*:\s*["']([^"']+)["']/g,
+        /createBrowserRouter\s*\(\s*\[([^\]]+)\]/gs,
+        /createRoutesFromElements\s*\([^)]*\)/gs
+      ];
+      
+      for (const pattern of routePatterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+          let path = match[1];
+          
+          if (!path) {
+            if (match[0].includes('createBrowserRouter')) {
+              const routesMatch = content.match(/createBrowserRouter\s*\(\s*\[([^\]]+)\]/s);
+              if (routesMatch) {
+                const routesContent = routesMatch[1];
+                const pathMatches = routesContent.matchAll(/path\s*:\s*["']([^"']+)["']/g);
+                for (const pathMatch of pathMatches) {
+                  path = pathMatch[1];
+                  if (path && !routeSet.has(path)) {
+                    routeSet.add(path);
+                    routes.push({
+                      path: path,
+                      source: file,
+                      public: true
+                    });
+                  }
+                }
+              }
+            }
+            continue;
+          }
+          
+          if (path && !routeSet.has(path)) {
+            routeSet.add(path);
+            routes.push({
+              path: path,
+              source: file,
+              public: true
+            });
+          }
+        }
+      }
+    } catch (error) {
+      continue;
+    }
+  }
+  
+  routes.sort((a, b) => a.path.localeCompare(b.path));
+  
+  return routes;
+}
+

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

@@ -0,0 +1,122 @@
+import { glob } from 'glob';
+import { resolve } from 'path';
+
+const INTERNAL_PATH_PATTERNS = [
+  /^\/admin/,
+  /^\/dashboard/,
+  /^\/account/,
+  /^\/settings/,
+  /\/internal/,
+  /\/private/
+];
+
+function isInternalRoute(path) {
+  return INTERNAL_PATH_PATTERNS.some(pattern => pattern.test(path));
+}
+
+function fileToAppRouterPath(file) {
+  let path = file.replace(/[\\\/]/g, '/');
+  path = path.replace(/(^|\/)page\.(js|jsx|ts|tsx)$/, '');
+  path = path.replace(/^\./, '');
+  
+  if (path === '' || path === '/') {
+    return '/';
+  }
+  
+  if (!path.startsWith('/')) {
+    path = '/' + path;
+  }
+  
+  path = path.replace(/\[([^\]]+)\]/g, ':$1');
+  path = path.replace(/\([^)]+\)/g, '');
+  
+  return path || '/';
+}
+
+function fileToPagesRouterPath(file) {
+  let path = file.replace(/[\\\/]/g, '/');
+  path = path.replace(/\.(js|jsx|ts|tsx)$/, '');
+  path = path.replace(/^index$/, '');
+  path = path.replace(/^\./, '');
+  
+  if (path === '' || path === '/') {
+    return '/';
+  }
+  if (!path.startsWith('/')) {
+    path = '/' + path;
+  }
+  
+  path = path.replace(/\[([^\]]+)\]/g, ':$1');
+  
+  return path || '/';
+}
+
+import { extractStaticRoutes } from './static-extractor.js';
+import { extractReactRouterRoutes } from './react-router-extractor.js';
+import { hasReactRouterDom } from './project-detector.js';
+
+export async function extractRoutes(projectDir, projectType) {
+  const routes = [];
+  const routeSet = new Set();
+  
+  if (projectType === 'static') {
+    return await extractStaticRoutes(projectDir);
+  }
+  
+  if (projectType === 'react_spa') {
+    const hasRouter = await hasReactRouterDom(projectDir);
+    if (hasRouter) {
+      return await extractReactRouterRoutes(projectDir);
+    }
+    return [];
+  }
+  
+  if (projectType === 'nextjs_app_router') {
+    const appDir = resolve(projectDir, 'app');
+    const pageFiles = await glob('**/page.{js,jsx,ts,tsx}', {
+      cwd: appDir,
+      absolute: false,
+      ignore: ['node_modules/**']
+    });
+    
+    for (const file of pageFiles) {
+      const routePath = fileToAppRouterPath(file);
+      const routeKey = routePath;
+      
+      if (!routeSet.has(routeKey)) {
+        routeSet.add(routeKey);
+        routes.push({
+          path: routePath,
+          source: `app/${file}`,
+          public: !isInternalRoute(routePath)
+        });
+      }
+    }
+  } else if (projectType === 'nextjs_pages_router') {
+    const pagesDir = resolve(projectDir, 'pages');
+    const pageFiles = await glob('**/*.{js,jsx,ts,tsx}', {
+      cwd: pagesDir,
+      absolute: false,
+      ignore: ['node_modules/**', '_app.*', '_document.*', '_error.*']
+    });
+    
+    for (const file of pageFiles) {
+      const routePath = fileToPagesRouterPath(file);
+      const routeKey = routePath;
+      
+      if (!routeSet.has(routeKey)) {
+        routeSet.add(routeKey);
+        routes.push({
+          path: routePath,
+          source: `pages/${file}`,
+          public: !isInternalRoute(routePath)
+        });
+      }
+    }
+  }
+  
+  routes.sort((a, b) => a.path.localeCompare(b.path));
+  
+  return routes;
+}
+

package/src/verax/learn/route-validator.js

@@ -0,0 +1,215 @@
+import { chromium } from 'playwright';
+import { isExternalUrl } from '../observe/domain-boundary.js';
+
+const VALIDATION_TIMEOUT_MS = 8000;
+const MAX_ROUTES_TO_VALIDATE = 50;
+
+export async function validateRoutes(manifest, baseUrl) {
+  let baseOrigin;
+  try {
+    const urlObj = new URL(baseUrl);
+    baseOrigin = urlObj.origin;
+  } catch (error) {
+    return {
+      routesValidated: 0,
+      routesReachable: 0,
+      routesUnreachable: 0,
+      details: [],
+      warnings: []
+    };
+  }
+  
+  const projectType = manifest.projectType;
+  const shouldValidate = projectType === 'nextjs_app_router' || 
+                        projectType === 'nextjs_pages_router' ||
+                        projectType === 'react_spa' ||
+                        projectType === 'static';
+  
+  if (!shouldValidate) {
+    return {
+      routesValidated: 0,
+      routesReachable: 0,
+      routesUnreachable: 0,
+      details: [],
+      warnings: []
+    };
+  }
+  
+  const publicRoutes = manifest.publicRoutes || [];
+  if (publicRoutes.length === 0) {
+    return {
+      routesValidated: 0,
+      routesReachable: 0,
+      routesUnreachable: 0,
+      details: [],
+      warnings: []
+    };
+  }
+  
+  const routesToValidate = publicRoutes.slice(0, MAX_ROUTES_TO_VALIDATE);
+  const wasCapped = publicRoutes.length > MAX_ROUTES_TO_VALIDATE;
+  
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 }
+  });
+  const page = await context.newPage();
+  
+  const details = [];
+  let reachableCount = 0;
+  let unreachableCount = 0;
+  
+  try {
+    for (const routePath of routesToValidate) {
+      page.removeAllListeners('response');
+      let routeUrl;
+      let normalizedPath;
+      
+      if (routePath.startsWith('http://') || routePath.startsWith('https://')) {
+        routeUrl = routePath;
+      } else {
+        normalizedPath = routePath.startsWith('/') ? routePath : '/' + routePath;
+        if (normalizedPath === '') {
+          normalizedPath = '/';
+        }
+        routeUrl = baseOrigin + normalizedPath;
+      }
+      
+      let status = 'UNREACHABLE';
+      let httpStatus = null;
+      let finalUrl = null;
+      let reason = null;
+      
+      let redirectTargetUrl = null;
+      let hasExternalRedirect = false;
+      
+      try {
+        const response = await page.goto(routeUrl, {
+          waitUntil: 'domcontentloaded',
+          timeout: VALIDATION_TIMEOUT_MS
+        });
+        
+        await page.waitForTimeout(300);
+        
+        finalUrl = page.url();
+        
+        // Check redirect chain in response object - PRIMARY detection method
+        if (response) {
+          httpStatus = response.status();
+          
+          const request = response.request();
+          
+          // Use redirectChain() if available (preferred), otherwise use redirectedFrom()
+          let redirectChain = [];
+          if (typeof request.redirectChain === 'function') {
+            try {
+              redirectChain = request.redirectChain();
+            } catch (e) {
+              // redirectChain may not be available, fall back to redirectedFrom
+            }
+          }
+          
+          // If redirectChain is empty or not available, build chain from redirectedFrom
+          if (redirectChain.length === 0) {
+            let currentRequest = request.redirectedFrom();
+            while (currentRequest) {
+              redirectChain.unshift(currentRequest);
+              currentRequest = currentRequest.redirectedFrom();
+            }
+          }
+          
+          // Check each request in the redirect chain for external origin
+          for (const chainRequest of redirectChain) {
+            const chainRequestUrl = chainRequest.url();
+            try {
+              const chainUrlObj = new URL(chainRequestUrl);
+              if (chainUrlObj.origin !== baseOrigin) {
+                hasExternalRedirect = true;
+                redirectTargetUrl = chainRequestUrl;
+                break;
+              }
+            } catch (e) {
+              // URL parsing failed, try with isExternalUrl
+              if (isExternalUrl(chainRequestUrl, baseOrigin)) {
+                hasExternalRedirect = true;
+                redirectTargetUrl = chainRequestUrl;
+                break;
+              }
+            }
+          }
+        }
+        
+        if (hasExternalRedirect) {
+          status = 'UNREACHABLE';
+          reason = 'external_redirect_blocked';
+          finalUrl = redirectTargetUrl || finalUrl;
+          unreachableCount++;
+        } else if (isExternalUrl(finalUrl, baseOrigin)) {
+          status = 'UNREACHABLE';
+          reason = 'external_redirect_blocked';
+          unreachableCount++;
+        } else if (response) {
+          if (httpStatus >= 200 && httpStatus < 300) {
+            status = 'REACHABLE';
+            reachableCount++;
+          } else {
+            status = 'UNREACHABLE';
+            reason = `http_${httpStatus}`;
+            unreachableCount++;
+          }
+        } else {
+          status = 'REACHABLE';
+          reachableCount++;
+        }
+      } catch (error) {
+        if (error.name === 'TimeoutError' || error.message.includes('timeout')) {
+          reason = 'timeout';
+        } else if (error.message.includes('net::ERR')) {
+          reason = 'network_error';
+        } else {
+          reason = 'navigation_failed';
+        }
+        unreachableCount++;
+      }
+      
+      details.push({
+        path: routePath,
+        status: status,
+        httpStatus: httpStatus,
+        finalUrl: finalUrl,
+        reason: reason
+      });
+    }
+  } finally {
+    await browser.close();
+  }
+  
+  const warnings = [];
+  
+  if (wasCapped) {
+    warnings.push({
+      code: 'ROUTE_VALIDATION_CAPPED',
+      message: `Route validation capped at ${MAX_ROUTES_TO_VALIDATE} routes. ${publicRoutes.length - MAX_ROUTES_TO_VALIDATE} routes were not validated.`
+    });
+  }
+  
+  const totalValidated = details.length;
+  if (totalValidated > 0) {
+    const reachabilityRatio = reachableCount / totalValidated;
+    if (reachabilityRatio < 0.5) {
+      warnings.push({
+        code: 'LOW_ROUTE_REACHABILITY',
+        message: `Only ${reachableCount} of ${totalValidated} validated routes are reachable (${Math.round(reachabilityRatio * 100)}%). This may indicate incorrect route extraction or server configuration issues.`
+      });
+    }
+  }
+  
+  return {
+    routesValidated: totalValidated,
+    routesReachable: reachableCount,
+    routesUnreachable: unreachableCount,
+    details: details,
+    warnings: warnings
+  };
+}
+