@veraxhq/verax 0.1.0 → 0.2.0

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

@@ -0,0 +1,280 @@
+/**
+ * CODE INTELLIGENCE v1 — Route Extraction (AST-based)
+ * 
+ * Extracts routes from Next.js and React Router using AST analysis.
+ * Includes dynamic routes with example paths.
+ * 
+ * Supported:
+ * - Next.js pages router (file-system)
+ * - Next.js app router (file-system)
+ * - React Router <Route path="...">
+ * - Dynamic routes: /users/[id] → /users/1
+ */
+
+import ts from 'typescript';
+import { resolve, relative, sep, basename, dirname, extname } from 'path';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { parseFile, findNodes, getStringLiteral, getNodeLocation } from './ts-program.js';
+import { extractVueRoutes } from './vue-router-extractor.js';
+import { normalizeDynamicRoute } from '../shared/dynamic-route-utils.js';
+
+const INTERNAL_PATH_PATTERNS = [
+  /^\/admin/,
+  /^\/dashboard/,
+  /^\/account/,
+  /^\/settings/,
+  /\/internal/,
+  /\/private/
+];
+
+function isInternalRoute(path) {
+  return INTERNAL_PATH_PATTERNS.some(pattern => pattern.test(path));
+}
+
+/**
+ * Extract routes from project.
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {Object} program - TypeScript program from createTSProgram
+ * @returns {Array} - Array of route objects
+ */
+export function extractRoutes(projectRoot, program) {
+  const routes = [];
+  
+  // Detect Next.js
+  const hasNextConfig = existsSync(resolve(projectRoot, 'next.config.js')) ||
+                        existsSync(resolve(projectRoot, 'next.config.mjs'));
+  const hasPagesDir = existsSync(resolve(projectRoot, 'pages'));
+  const hasAppDir = existsSync(resolve(projectRoot, 'app'));
+  
+  if (hasNextConfig || hasPagesDir || hasAppDir) {
+    // Next.js detected
+    if (hasPagesDir) {
+      routes.push(...extractNextPagesRoutes(projectRoot));
+    }
+    if (hasAppDir) {
+      routes.push(...extractNextAppRoutes(projectRoot));
+    }
+  }
+  
+  // React Router detection
+  if (program && program.program) {
+    routes.push(...extractReactRouterRoutes(projectRoot, program));
+  }
+  
+  // Vue Router detection
+  if (program && program.program) {
+    routes.push(...extractVueRoutes(projectRoot, program));
+  }
+  
+  return routes;
+}
+
+/**
+ * Extract Next.js pages router routes (file-system based).
+ * 
+ * @param {string} projectRoot - Project root
+ * @returns {Array} - Routes with sourceRef
+ */
+function extractNextPagesRoutes(projectRoot) {
+  const routes = [];
+  const pagesDir = resolve(projectRoot, 'pages');
+  
+  if (!existsSync(pagesDir)) return routes;
+  
+  function walk(dir, urlPath = '') {
+    const entries = readdirSync(dir);
+    
+    for (const entry of entries) {
+      const fullPath = resolve(dir, entry);
+      const stat = statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        // Nested route
+        walk(fullPath, `${urlPath}/${entry}`);
+      } else if (stat.isFile()) {
+        const ext = extname(entry);
+        if (!['.js', '.jsx', '.ts', '.tsx'].includes(ext)) continue;
+        
+        const baseName = basename(entry, ext);
+        
+        // Skip special files
+        if (baseName.startsWith('_')) continue;
+        if (baseName === 'index') {
+          // index.tsx -> /path or /
+          const route = urlPath || '/';
+          const relativePath = relative(projectRoot, fullPath);
+          routes.push({
+            path: route,
+            sourceRef: `${relativePath.replace(/\\/g, '/')}:1`,
+            file: relativePath.replace(/\\/g, '/'),
+            framework: 'next-pages'
+          });
+        } else {
+          // file.tsx -> /path/file
+          const route = `${urlPath}/${baseName}`;
+          const relativePath = relative(projectRoot, fullPath);
+          const routeObj = {
+            path: route,
+            sourceRef: `${relativePath.replace(/\\/g, '/')}:1`,
+            file: relativePath.replace(/\\/g, '/'),
+            framework: 'next-pages'
+          };
+          
+          // Normalize dynamic routes to example paths
+          const normalized = normalizeDynamicRoute(route);
+          if (normalized) {
+            routeObj.path = normalized.examplePath;
+            routeObj.originalPattern = normalized.originalPattern;
+            routeObj.isDynamic = true;
+            routeObj.exampleExecution = true;
+          }
+          
+          routes.push(routeObj);
+        }
+      }
+    }
+  }
+  
+  walk(pagesDir);
+  return routes;
+}
+
+/**
+ * Extract Next.js app router routes (file-system based).
+ * 
+ * @param {string} projectRoot - Project root
+ * @returns {Array} - Routes with sourceRef
+ */
+function extractNextAppRoutes(projectRoot) {
+  const routes = [];
+  const appDir = resolve(projectRoot, 'app');
+  
+  if (!existsSync(appDir)) return routes;
+  
+  function walk(dir, urlPath = '') {
+    const entries = readdirSync(dir);
+    
+    for (const entry of entries) {
+      const fullPath = resolve(dir, entry);
+      const stat = statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        // Nested route segment
+        walk(fullPath, `${urlPath}/${entry}`);
+      } else if (stat.isFile()) {
+        const ext = extname(entry);
+        const baseName = basename(entry, ext);
+        
+        // App router: page.tsx defines the route
+        if (baseName === 'page' && ['.js', '.jsx', '.ts', '.tsx'].includes(ext)) {
+          const route = urlPath || '/';
+          const relativePath = relative(projectRoot, fullPath);
+          const routeObj = {
+            path: route,
+            sourceRef: `${relativePath.replace(/\\/g, '/')}:1`,
+            file: relativePath.replace(/\\/g, '/'),
+            framework: 'next-app'
+          };
+          
+          // Normalize dynamic routes to example paths
+          const normalized = normalizeDynamicRoute(route);
+          if (normalized) {
+            routeObj.path = normalized.examplePath;
+            routeObj.originalPattern = normalized.originalPattern;
+            routeObj.isDynamic = true;
+            routeObj.exampleExecution = true;
+          }
+          
+          routes.push(routeObj);
+        }
+      }
+    }
+  }
+  
+  walk(appDir);
+  return routes;
+}
+
+/**
+ * Extract React Router routes from JSX.
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {Object} program - TypeScript program
+ * @returns {Array} - Routes with sourceRef
+ */
+function extractReactRouterRoutes(projectRoot, program) {
+  const routes = [];
+  
+  for (const sourceFile of program.sourceFiles) {
+    const ast = parseFile(sourceFile, true);
+    if (!ast) continue;
+    
+    // Find <Route path="..."> elements
+    const routeElements = findNodes(ast, node => {
+      return ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node);
+    });
+    
+    for (const element of routeElements) {
+      const tagName = element.tagName;
+      if (!ts.isIdentifier(tagName)) continue;
+      if (tagName.text !== 'Route') continue;
+      
+      // Find path attribute
+      const attributes = element.attributes;
+      if (!attributes || !attributes.properties) continue;
+      
+      for (const attr of attributes.properties) {
+        if (!ts.isJsxAttribute(attr)) continue;
+        
+        const name = attr.name;
+        if (!ts.isIdentifier(name)) continue;
+        if (name.text !== 'path') continue;
+        
+        const initializer = attr.initializer;
+        if (!initializer) continue;
+        
+        let pathValue = null;
+        
+        // StringLiteral: path="..."
+        if (ts.isStringLiteral(initializer)) {
+          pathValue = initializer.text;
+        }
+        // JsxExpression: path={"..."}
+        else if (ts.isJsxExpression(initializer)) {
+          const expr = initializer.expression;
+          if (expr && (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))) {
+            pathValue = expr.text;
+          }
+        }
+        
+        if (pathValue) {
+          const location = getNodeLocation(ast, element, projectRoot);
+          
+          // Normalize dynamic routes to example paths
+          const normalized = normalizeDynamicRoute(pathValue);
+          const routeObj = normalized ? {
+            path: normalized.examplePath,
+            originalPattern: normalized.originalPattern,
+            isDynamic: true,
+            exampleExecution: true,
+            sourceRef: location.sourceRef,
+            file: location.file,
+            line: location.line,
+            framework: 'react-router'
+          } : {
+            path: pathValue,
+            sourceRef: location.sourceRef,
+            file: location.file,
+            line: location.line,
+            framework: 'react-router'
+          };
+          
+          routes.push(routeObj);
+        }
+      }
+    }
+  }
+  
+  return routes;
+}

package/src/verax/intel/ts-program.js

@@ -0,0 +1,256 @@
+/**
+ * CODE INTELLIGENCE v1 — TypeScript Program Foundation
+ * 
+ * Provides AST-based code understanding:
+ * - Creates TypeScript Program over project sources
+ * - Walks AST nodes
+ * - Resolves symbols
+ * - Tracks source locations (file:line)
+ * 
+ * NO REGEX. NO GUESSING. AST ONLY.
+ */
+
+import ts from 'typescript';
+import { resolve, relative, extname } from 'path';
+import { readdirSync, statSync, readFileSync, existsSync } from 'fs';
+
+/**
+ * Create a TypeScript Program for AST analysis.
+ * 
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} options - Options { includeJs: boolean }
+ * @returns {Object} - { program, typeChecker, sourceFiles }
+ */
+export function createTSProgram(projectRoot, options = {}) {
+  const { includeJs = true } = options;
+  
+  // Collect source files
+  const sourceFiles = collectSourceFiles(projectRoot, includeJs);
+  
+  if (sourceFiles.length === 0) {
+    return {
+      program: null,
+      typeChecker: null,
+      sourceFiles: [],
+      error: 'No source files found'
+    };
+  }
+  
+  // Create compiler options
+  const compilerOptions = {
+    target: ts.ScriptTarget.ES2020,
+    module: ts.ModuleKind.ESNext,
+    jsx: ts.JsxEmit.React,
+    allowJs: includeJs,
+    checkJs: false,
+    noEmit: true,
+    skipLibCheck: true,
+    skipDefaultLibCheck: true,
+    moduleResolution: ts.ModuleResolutionKind.NodeJs,
+    esModuleInterop: true,
+    resolveJsonModule: true
+  };
+  
+  // Create program
+  const program = ts.createProgram(sourceFiles, compilerOptions);
+  const typeChecker = program.getTypeChecker();
+  
+  return {
+    program,
+    typeChecker,
+    sourceFiles,
+    error: null
+  };
+}
+
+/**
+ * Collect source files (.ts, .tsx, .js, .jsx).
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {boolean} includeJs - Include .js/.jsx files
+ * @returns {string[]} - Array of absolute file paths
+ */
+function collectSourceFiles(projectRoot, includeJs) {
+  const files = [];
+  const extensions = includeJs 
+    ? ['.ts', '.tsx', '.js', '.jsx']
+    : ['.ts', '.tsx'];
+  
+  const ignoreDirs = ['node_modules', '.verax', 'dist', 'build', '.next', 'out', '.git'];
+  
+  function walk(dir) {
+    try {
+      const entries = readdirSync(dir);
+      
+      for (const entry of entries) {
+        const fullPath = resolve(dir, entry);
+        const stat = statSync(fullPath);
+        
+        if (stat.isDirectory()) {
+          // Skip ignored directories
+          if (ignoreDirs.includes(entry)) continue;
+          walk(fullPath);
+        } else if (stat.isFile()) {
+          const ext = extname(entry);
+          if (extensions.includes(ext)) {
+            files.push(fullPath);
+          }
+        }
+      }
+    } catch (err) {
+      // Skip directories we can't read
+    }
+  }
+  
+  walk(projectRoot);
+  return files;
+}
+
+/**
+ * Get source location for AST node.
+ * 
+ * @param {ts.SourceFile} sourceFile - TypeScript source file
+ * @param {ts.Node} node - AST node
+ * @param {string} projectRoot - Project root for relative path
+ * @returns {Object} - { file, line, column, sourceRef }
+ */
+export function getNodeLocation(sourceFile, node, projectRoot) {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  const relativePath = relative(projectRoot, sourceFile.fileName);
+  
+  return {
+    file: relativePath.replace(/\\/g, '/'),
+    line: line + 1, // 1-indexed
+    column: character + 1,
+    sourceRef: `${relativePath.replace(/\\/g, '/')}:${line + 1}`
+  };
+}
+
+/**
+ * Walk AST and invoke callback for each node.
+ * 
+ * @param {ts.Node} node - Root node
+ * @param {Function} callback - Callback(node) => void
+ */
+export function walkAST(node, callback) {
+  callback(node);
+  ts.forEachChild(node, child => walkAST(child, callback));
+}
+
+/**
+ * Find nodes matching a predicate.
+ * 
+ * @param {ts.Node} root - Root node
+ * @param {Function} predicate - Predicate(node) => boolean
+ * @returns {ts.Node[]} - Matching nodes
+ */
+export function findNodes(root, predicate) {
+  const results = [];
+  
+  walkAST(root, node => {
+    if (predicate(node)) {
+      results.push(node);
+    }
+  });
+  
+  return results;
+}
+
+/**
+ * Get string literal value from node.
+ * 
+ * @param {ts.Node} node - AST node
+ * @returns {string|null} - String value or null
+ */
+export function getStringLiteral(node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  return null;
+}
+
+/**
+ * Resolve identifier to its declaration.
+ * 
+ * @param {ts.TypeChecker} typeChecker - Type checker
+ * @param {ts.Identifier} identifier - Identifier node
+ * @returns {ts.Declaration|null} - Declaration node or null
+ */
+export function resolveIdentifier(typeChecker, identifier) {
+  try {
+    const symbol = typeChecker.getSymbolAtLocation(identifier);
+    if (!symbol || !symbol.declarations || symbol.declarations.length === 0) {
+      return null;
+    }
+    return symbol.declarations[0];
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Check if node is a function declaration or arrow function.
+ * 
+ * @param {ts.Node} node - AST node
+ * @returns {boolean}
+ */
+export function isFunctionNode(node) {
+  return ts.isFunctionDeclaration(node) ||
+         ts.isFunctionExpression(node) ||
+         ts.isArrowFunction(node) ||
+         ts.isMethodDeclaration(node);
+}
+
+/**
+ * Get function body statements.
+ * 
+ * @param {ts.Node} funcNode - Function node
+ * @returns {ts.Statement[]|null} - Statements or null
+ */
+export function getFunctionBody(funcNode) {
+  if (!isFunctionNode(funcNode)) return null;
+  
+  const body = funcNode.body;
+  if (!body) return null;
+  
+  // Arrow function with expression body
+  if (ts.isExpression(body)) {
+    return []; // No statements, just expression
+  }
+  
+  // Block body
+  if (ts.isBlock(body)) {
+    return Array.from(body.statements);
+  }
+  
+  return null;
+}
+
+/**
+ * Parse a single file into AST.
+ * 
+ * @param {string} filePath - File path
+ * @param {boolean} isJsx - Is JSX/TSX
+ * @returns {ts.SourceFile|null} - Parsed source file
+ */
+export function parseFile(filePath, isJsx = false) {
+  if (!existsSync(filePath)) return null;
+  
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const ext = extname(filePath);
+    const scriptKind = isJsx || ext === '.tsx' || ext === '.jsx'
+      ? ts.ScriptKind.TSX
+      : ts.ScriptKind.TS;
+    
+    return ts.createSourceFile(
+      filePath,
+      content,
+      ts.ScriptTarget.ES2020,
+      true,
+      scriptKind
+    );
+  } catch (err) {
+    return null;
+  }
+}