@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/intel/handler-mapper.js

@@ -0,0 +1,249 @@
+/**
+ * CODE INTELLIGENCE v1 — JSX Handler Mapper
+ * 
+ * Maps JSX event handlers (onClick, onSubmit) to function declarations.
+ * Resolves handler identifiers to actual function bodies.
+ * Captures sourceRef for both element and handler.
+ */
+
+import ts from 'typescript';
+import { parseFile, findNodes, resolveIdentifier, isFunctionNode, getNodeLocation } from './ts-program.js';
+
+/**
+ * Extract handler mappings from JSX elements.
+ * 
+ * @param {string} projectRoot - Project root
+ * @param {Object} program - TypeScript program
+ * @returns {Array} - Handler mappings { element, handlerName, handlerNode, elementSourceRef, handlerSourceRef }
+ */
+export function extractHandlerMappings(projectRoot, program) {
+  const mappings = [];
+  
+  if (!program || !program.program || !program.typeChecker) return mappings;
+  
+  for (const filePath of program.sourceFiles) {
+    const ast = parseFile(filePath, true);
+    if (!ast) continue;
+    
+    // Find JSX elements with event handlers
+    const jsxElements = findNodes(ast, node => {
+      return ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node);
+    });
+    
+    for (const element of jsxElements) {
+      const tagName = getTagName(element);
+      const attributes = element.attributes;
+      if (!attributes || !attributes.properties) continue;
+      
+      for (const attr of attributes.properties) {
+        if (!ts.isJsxAttribute(attr)) continue;
+        
+        const attrName = attr.name;
+        if (!ts.isIdentifier(attrName)) continue;
+        
+        const eventType = attrName.text;
+        if (!['onClick', 'onSubmit', 'onChange', 'onBlur'].includes(eventType)) continue;
+        
+        const initializer = attr.initializer;
+        if (!initializer) continue;
+        
+        let handlerNode = null;
+        let handlerName = null;
+        
+        // JsxExpression: onClick={handleClick}
+        if (ts.isJsxExpression(initializer)) {
+          const expr = initializer.expression;
+          
+          if (ts.isIdentifier(expr)) {
+            // Reference to function: onClick={handleClick}
+            handlerName = expr.text;
+            const declaration = resolveIdentifier(program.typeChecker, expr);
+            if (declaration && isFunctionNode(declaration)) {
+              handlerNode = declaration;
+            } else if (declaration && ts.isVariableDeclaration(declaration)) {
+              // const handleClick = () => {...}
+              const init = declaration.initializer;
+              if (init && isFunctionNode(init)) {
+                handlerNode = init;
+              }
+            } else {
+              // Fallback for JS/JSX where typeChecker cannot resolve identifiers.
+              // Search the file for a matching function/variable declaration manually.
+              const localMatch = findNodes(ast, n => {
+                if (ts.isFunctionDeclaration(n) && n.name?.text === handlerName) return true;
+                if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === handlerName) {
+                  return isFunctionNode(n.initializer || n);
+                }
+                return false;
+              })[0];
+
+              if (localMatch) {
+                if (isFunctionNode(localMatch)) {
+                  handlerNode = localMatch;
+                } else if (ts.isVariableDeclaration(localMatch)) {
+                  const init = localMatch.initializer;
+                  if (init && isFunctionNode(init)) {
+                    handlerNode = init;
+                  }
+                }
+              }
+            }
+          } else if (isFunctionNode(expr)) {
+            // Inline arrow: onClick={() => {...}}
+            handlerNode = expr;
+            handlerName = 'inline';
+          }
+        }
+        
+        if (handlerNode) {
+          const elementLoc = getNodeLocation(ast, element, projectRoot);
+          const handlerSourceFile = program.program.getSourceFile(handlerNode.getSourceFile().fileName);
+          const handlerLoc = handlerSourceFile 
+            ? getNodeLocation(handlerSourceFile, handlerNode, projectRoot)
+            : null;
+          
+          // Capture simple attribute map for matching hints (e.g., href/to)
+          const attrMap = {};
+          for (const ap of attributes.properties) {
+            if (!ts.isJsxAttribute(ap)) continue;
+            if (!ts.isIdentifier(ap.name)) continue;
+            const aname = ap.name.text;
+            const init = ap.initializer;
+            if (!init) continue;
+            if (ts.isStringLiteral(init)) {
+              attrMap[aname] = init.text;
+            } else if (ts.isJsxExpression(init) && init.expression && ts.isStringLiteral(init.expression)) {
+              attrMap[aname] = init.expression.text;
+            }
+          }
+
+          mappings.push({
+            element: {
+              tag: tagName,
+              event: eventType,
+              attrs: attrMap,
+              sourceRef: elementLoc.sourceRef,
+              file: elementLoc.file,
+              line: elementLoc.line
+            },
+            handler: {
+              name: handlerName,
+              node: handlerNode,
+              sourceRef: handlerLoc?.sourceRef || elementLoc.sourceRef,
+              file: handlerLoc?.file || elementLoc.file,
+              line: handlerLoc?.line || elementLoc.line
+            }
+          });
+        }
+      }
+    }
+  }
+  
+  return mappings;
+}
+
+  /**
+   * Extract navigation-capable JSX elements (Link/NavLink/a) with static href/to.
+   * Returns minimal element records with attrs and sourceRef, independent of handlers.
+   */
+  export function extractNavElements(projectRoot, program) {
+    const elements = [];
+    if (!program || !program.program || !program.typeChecker) return elements;
+    for (const filePath of program.sourceFiles) {
+      const ast = parseFile(filePath, true);
+      if (!ast) continue;
+      const jsxElements = findNodes(ast, node => ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node));
+      for (const element of jsxElements) {
+        const tagName = getTagName(element);
+        if (!['Link', 'NavLink', 'a'].includes(tagName)) continue;
+        const attributes = element.attributes;
+        if (!attributes || !attributes.properties) continue;
+        let href = null, to = null;
+        for (const attr of attributes.properties) {
+          if (!ts.isJsxAttribute(attr)) continue;
+          if (!ts.isIdentifier(attr.name)) continue;
+          const an = attr.name.text;
+          const init = attr.initializer;
+          if (!init) continue;
+          if (an === 'href' || an === 'to') {
+            if (ts.isStringLiteral(init)) {
+              if (an === 'href') href = init.text; else to = init.text;
+            } else if (ts.isJsxExpression(init) && init.expression && ts.isStringLiteral(init.expression)) {
+              if (an === 'href') href = init.expression.text; else to = init.expression.text;
+            } else if (ts.isJsxExpression(init) && init.expression && ts.isNoSubstitutionTemplateLiteral(init.expression)) {
+              if (an === 'href') href = init.expression.text; else to = init.expression.text;
+            }
+          }
+        }
+        const target = to || href;
+        if (typeof target === 'string' && target.startsWith('/') && !target.startsWith('//')) {
+          const loc = getNodeLocation(ast, element, projectRoot);
+          elements.push({
+            tag: tagName,
+            attrs: { href, to },
+            sourceRef: loc.sourceRef,
+            file: loc.file,
+            line: loc.line
+          });
+        }
+      }
+    }
+    return elements;
+  }
+
+/**
+ * Get tag name from JSX element.
+ * 
+ * @param {ts.Node} element - JSX element node
+ * @returns {string} - Tag name
+ */
+function getTagName(element) {
+  const tagName = element.tagName;
+  if (ts.isIdentifier(tagName)) {
+    return tagName.text;
+  }
+  return 'unknown';
+}
+
+/**
+ * Extract selector hint from JSX element for stable identification.
+ * 
+ * @param {ts.Node} element - JSX element node
+ * @returns {string|null} - Selector hint (id, data-testid, or null)
+ */
+export function extractSelectorHint(element) {
+  const attributes = element.attributes;
+  if (!attributes || !attributes.properties) return null;
+  
+  // Priority: id > data-testid > data-cy > role
+  for (const attr of attributes.properties) {
+    if (!ts.isJsxAttribute(attr)) continue;
+    
+    const name = attr.name;
+    if (!ts.isIdentifier(name)) continue;
+    
+    const attrName = name.text;
+    const initializer = attr.initializer;
+    
+    if (attrName === 'id' && initializer && ts.isStringLiteral(initializer)) {
+      return `#${initializer.text}`;
+    }
+    
+    if (attrName === 'data-testid' && initializer) {
+      if (ts.isStringLiteral(initializer)) {
+        return `[data-testid="${initializer.text}"]`;
+      } else if (ts.isJsxExpression(initializer)) {
+        const expr = initializer.expression;
+        if (expr && ts.isStringLiteral(expr)) {
+          return `[data-testid="${expr.text}"]`;
+        }
+      }
+    }
+    
+    if (attrName === 'data-cy' && initializer && ts.isStringLiteral(initializer)) {
+      return `[data-cy="${initializer.text}"]`;
+    }
+  }
+  
+  return null;
+}

package/src/verax/intel/index.js

@@ -0,0 +1,281 @@
+/**
+ * CODE INTELLIGENCE v1 — Main Orchestrator
+ * 
+ * Combines all intelligence modules to emit PROVEN expectations:
+ * - Routes from AST
+ * - Handlers from JSX
+ * - Effects from function bodies
+ * 
+ * Every expectation has sourceRef. NO GUESSING.
+ */
+
+import { createTSProgram } from './ts-program.js';
+import { extractRoutes } from './route-extractor.js';
+import { extractHandlerMappings, extractSelectorHint, extractNavElements } from './handler-mapper.js';
+import { detectEffects } from './effect-detector.js';
+import { extractVueNavigationPromises } from './vue-navigation-extractor.js';
+import { normalizeDynamicRoute, normalizeTemplateLiteral } from '../shared/dynamic-route-utils.js';
+
+/**
+ * Run code intelligence analysis.
+ * 
+ * @param {string} projectRoot - Project root
+ * @returns {Promise<Object>} - { routes, handlerMappings, expectations, stats }
+ */
+export async function runCodeIntelligence(projectRoot) {
+  const result = {
+    routes: [],
+    handlerMappings: [],
+    expectations: [],
+    stats: {
+      routesFound: 0,
+      handlersFound: 0,
+      effectsFound: 0,
+      expectationsGenerated: 0,
+      expectationsProven: 0
+    },
+    error: null
+  };
+  
+  try {
+    // Step 1: Create TypeScript Program
+    const program = createTSProgram(projectRoot, { includeJs: true });
+    
+    if (program.error) {
+      result.error = program.error;
+      return result;
+    }
+    
+    // Step 2: Extract routes (AST-based, no regex)
+    const routes = extractRoutes(projectRoot, program);
+    result.routes = routes;
+    result.stats.routesFound = routes.length;
+    
+    // Step 3: Extract handler mappings (JSX → Function)
+    const handlerMappings = extractHandlerMappings(projectRoot, program);
+    result.handlerMappings = handlerMappings;
+    result.stats.handlersFound = handlerMappings.length;
+    
+    // Step 4: For each handler, detect effects
+    for (const mapping of handlerMappings) {
+      const handlerSourceFile = mapping.handler.node.getSourceFile();
+      // VALIDATION INTELLIGENCE v1: Pass eventType to detectEffects
+      const eventType = mapping.element?.event || null;
+      const effects = detectEffects(
+        mapping.handler.node,
+        handlerSourceFile,
+        projectRoot,
+        eventType
+      );
+      
+      mapping.effects = effects;
+      result.stats.effectsFound += effects.length;
+      
+      // Step 5a: Generate expectations from (element + handler + effect)
+      for (const effect of effects) {
+        const expectation = generateExpectation(mapping, effect);
+        if (expectation) {
+          result.expectations.push(expectation);
+          result.stats.expectationsGenerated++;
+          if (expectation.proof === 'PROVEN_EXPECTATION') {
+            result.stats.expectationsProven++;
+          }
+        }
+      }
+      
+      // Step 5b: Attribute-driven navigation expectations (href/to literal)
+      if ((effects?.length || 0) === 0) {
+        const attrs = mapping.element?.attrs || {};
+        const target = attrs.to || attrs.href || null;
+        if (target && typeof target === 'string' && target.startsWith('/')) {
+          const expectation = {
+            type: 'spa_navigation',
+            targetPath: target,
+            matchAttribute: attrs.to ? 'to' : (attrs.href ? 'href' : null),
+            proof: 'PROVEN_EXPECTATION',
+            sourceRef: mapping.element.sourceRef,
+            selectorHint: extractSelectorHint(mapping.element) || `${mapping.element.tag}`,
+            metadata: {
+              elementFile: mapping.element.file,
+              elementLine: mapping.element.line,
+              handlerName: mapping.handler.name,
+              handlerFile: mapping.handler.file,
+              handlerLine: mapping.handler.line,
+              eventType: mapping.element.event
+            }
+          };
+          result.expectations.push(expectation);
+          result.stats.expectationsGenerated++;
+          result.stats.expectationsProven++;
+        }
+      }
+    }
+    
+    // Step 5c: Generate expectations from plain Link/NavLink/a elements with static href/to
+    const navElements = extractNavElements(projectRoot, program);
+    for (const el of navElements) {
+      const target = el.attrs.to || el.attrs.href || null;
+      if (!target) continue;
+      const expectation = {
+        type: 'spa_navigation',
+        targetPath: target,
+        matchAttribute: el.attrs.to ? 'to' : (el.attrs.href ? 'href' : null),
+        proof: 'PROVEN_EXPECTATION',
+        sourceRef: el.sourceRef,
+        selectorHint: extractSelectorHint(/** @type {any} */ ({ attributes: { properties: [] } })) || `${el.tag}`,
+        metadata: {
+          elementFile: el.file,
+          elementLine: el.line,
+          handlerName: null,
+          handlerFile: null,
+          handlerLine: null,
+          eventType: 'click'
+        }
+      };
+      result.expectations.push(expectation);
+      result.stats.expectationsGenerated++;
+      result.stats.expectationsProven++;
+    }
+    
+    // Step 5d: Extract Vue navigation promises (router-link, RouterLink, router.push/replace)
+    const vueNavPromises = await extractVueNavigationPromises(projectRoot, program);
+    for (const promise of vueNavPromises) {
+      result.expectations.push(promise);
+      result.stats.expectationsGenerated++;
+      if (promise.proof === 'PROVEN_EXPECTATION') {
+        result.stats.expectationsProven++;
+      }
+    }
+    
+  } catch (err) {
+    result.error = err.message || 'Unknown error';
+  }
+  
+  return result;
+}
+
+/**
+ * Generate expectation from handler mapping and effect.
+ * 
+ * @param {Object} mapping - Handler mapping
+ * @param {Object} effect - Detected effect
+ * @returns {Object|null} - Expectation object
+ */
+function generateExpectation(mapping, effect) {
+  if (!effect || !effect.type) return null;
+  
+  const selectorHint = extractSelectorHint(mapping.element);
+  
+  const base = {
+    selectorHint: selectorHint || `${mapping.element.tag}`,
+    proof: 'PROVEN_EXPECTATION',
+    sourceRef: effect.sourceRef,
+    metadata: {
+      elementFile: mapping.element.file,
+      elementLine: mapping.element.line,
+      handlerName: mapping.handler.name,
+      handlerFile: mapping.handler.file,
+      handlerLine: mapping.handler.line,
+      effectFile: effect.file,
+      effectLine: effect.line,
+      eventType: mapping.element.event
+    }
+  };
+
+  // Navigation → spa_navigation expectation with matchAttribute
+  if (effect.type === 'navigation' && effect.target) {
+    const matchAttribute = mapping.element?.attrs?.to
+      ? 'to'
+      : (mapping.element?.attrs?.href ? 'href' : null);
+    // Extract navigation method (push/replace/navigate) from effect
+    const navMethod = effect.method || 'push'; // Default to push if not specified
+    
+    // Normalize dynamic routes to example paths
+    const normalized = normalizeDynamicRoute(effect.target) || normalizeTemplateLiteral(effect.target);
+    
+    if (normalized) {
+      return {
+        ...base,
+        type: 'spa_navigation',
+        targetPath: normalized.examplePath,
+        originalPattern: normalized.originalPattern,
+        isDynamic: true,
+        exampleExecution: true,
+        matchAttribute,
+        expectedTarget: normalized.examplePath,
+        navigationMethod: navMethod
+      };
+    }
+    
+    return {
+      ...base,
+      type: 'spa_navigation',
+      targetPath: effect.target,
+      matchAttribute,
+      expectedTarget: effect.target,
+      navigationMethod: navMethod
+    };
+  }
+
+  // Network → network_action expectation
+  if (effect.type === 'network') {
+    return {
+      ...base,
+      type: 'network_action',
+      method: effect.method || 'GET',
+      expectedTarget: effect.target || null,
+      urlPath: effect.target || null // Alias for compatibility
+    };
+  }
+
+  // VALIDATION INTELLIGENCE v1: validation_block → validation_block expectation
+  if (effect.type === 'validation_block') {
+    return {
+      ...base,
+      type: 'validation_block',
+      proof: 'PROVEN_EXPECTATION',
+      handlerRef: base.metadata.handlerFile ? `${base.metadata.handlerFile}:${base.metadata.handlerLine}` : null
+    };
+  }
+
+  // Validation → form submission expectation (legacy)
+  if (effect.type === 'validation') {
+    return {
+      ...base,
+      type: 'form_submission',
+      expectedTarget: effect.target || null
+    };
+  }
+
+  // State → state_action expectation
+  if (effect.type === 'state' && effect.target) {
+    return {
+      ...base,
+      type: 'state_action',
+      expectedTarget: effect.target,
+      storeType: effect.storeType || 'unknown',
+      method: effect.method || null
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Determine expectation type from effect.
+ * 
+ * @param {Object} effect - Effect object
+ * @returns {string} - Expectation type
+ */
+function _determineExpectationType(effect) {
+  switch (effect.type) {
+    case 'navigation':
+      return 'navigation';
+    case 'network':
+      return 'network_action';
+    case 'validation':
+      return 'form_submission'; // preventDefault typically in forms
+    default:
+      return 'unknown';
+  }
+}