renderpilot 1.0.0

package/src/parser/ASTUtils.js

@@ -0,0 +1,241 @@
+/**
+ * @file parser/ASTUtils.js
+ * @description
+ * Reusable AST traversal helpers shared across all rules.
+ * Centralizing these prevents each rule from reimplementing
+ * common AST patterns, keeping rule code focused on detection logic.
+ */
+
+'use strict';
+
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+// ─── JSX Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if a JSX element has a specific prop by name.
+ * @param {import('@babel/types').JSXOpeningElement} openingElement
+ * @param {string} propName
+ * @returns {boolean}
+ */
+function jsxHasProp(openingElement, propName) {
+  return openingElement.attributes.some(
+    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: propName })
+  );
+}
+
+/**
+ * Get the value of a JSX attribute.
+ * @param {import('@babel/types').JSXOpeningElement} openingElement
+ * @param {string} propName
+ * @returns {import('@babel/types').Node|null}
+ */
+function getJSXPropValue(openingElement, propName) {
+  const attr = openingElement.attributes.find(
+    (a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name, { name: propName })
+  );
+  return attr ? attr.value : null;
+}
+
+// ─── Function / Component Helpers ────────────────────────────────────────────
+
+/**
+ * Determine if a node is a React function component.
+ * Heuristics: starts with uppercase, returns JSX.
+ * @param {import('@babel/types').Node} node
+ * @param {string} name - Detected name of the function
+ * @returns {boolean}
+ */
+function isReactComponent(node, name) {
+  if (!name) return false;
+  // Must start with uppercase letter
+  if (!/^[A-Z]/.test(name)) return false;
+  // Must be some kind of function
+  return (
+    t.isFunctionDeclaration(node) ||
+    t.isFunctionExpression(node) ||
+    t.isArrowFunctionExpression(node)
+  );
+}
+
+/**
+ * Extract the name from a function node in common React component patterns:
+ *   - function MyComponent() {}
+ *   - const MyComponent = () => {}
+ *   - const MyComponent = function() {}
+ *   - export default function MyComponent() {}
+ *
+ * @param {import('@babel/types').Node} node
+ * @param {import('@babel/traverse').NodePath} path
+ * @returns {string|null}
+ */
+function getComponentName(node, path) {
+  // Named function declaration
+  if (t.isFunctionDeclaration(node) && node.id) {
+    return node.id.name;
+  }
+
+  // Arrow function or function expression assigned to variable
+  if (
+    (t.isArrowFunctionExpression(node) || t.isFunctionExpression(node)) &&
+    path.parent
+  ) {
+    if (t.isVariableDeclarator(path.parent) && t.isIdentifier(path.parent.id)) {
+      return path.parent.id.name;
+    }
+    // Named function expression
+    if (t.isFunctionExpression(node) && node.id) {
+      return node.id.name;
+    }
+  }
+
+  return null;
+}
+
+// ─── Hook Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if a CallExpression is a call to a named hook.
+ * @param {import('@babel/types').Node} node
+ * @param {string} hookName - e.g. 'useEffect', 'useState'
+ * @returns {boolean}
+ */
+function isHookCall(node, hookName) {
+  if (!t.isCallExpression(node)) return false;
+  const callee = node.callee;
+  // Direct call: useEffect(...)
+  if (t.isIdentifier(callee, { name: hookName })) return true;
+  // Namespaced call: React.useEffect(...)
+  if (
+    t.isMemberExpression(callee) &&
+    t.isIdentifier(callee.property, { name: hookName })
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Get the dependency array from a useEffect / useCallback / useMemo call.
+ * Returns null if the dep array argument is not present.
+ * @param {import('@babel/types').CallExpression} node
+ * @returns {import('@babel/types').ArrayExpression|null}
+ */
+function getDepsArray(node) {
+  if (node.arguments.length < 2) return null;
+  const depsArg = node.arguments[1];
+  return t.isArrayExpression(depsArg) ? depsArg : null;
+}
+
+// ─── Traversal Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Collect all Identifier names referenced inside a given AST node.
+ * Used to find which variables a callback depends on.
+ * @param {import('@babel/types').Node} node
+ * @returns {Set<string>}
+ */
+function collectIdentifiers(node) {
+  const names = new Set();
+  traverse(node, {
+    Identifier(innerPath) {
+      // Skip property keys in member expressions (obj.foo — 'foo' is not a reference)
+      if (
+        t.isMemberExpression(innerPath.parent) &&
+        innerPath.parent.property === innerPath.node &&
+        !innerPath.parent.computed
+      ) {
+        return;
+      }
+      // Skip JSX attribute names
+      if (t.isJSXAttribute(innerPath.parent)) return;
+      names.add(innerPath.node.name);
+    },
+  }, null, {});
+  return names;
+}
+
+/**
+ * Extract the names from an ArrayExpression (dep array).
+ * Only extracts simple Identifier elements (ignores complex expressions).
+ * @param {import('@babel/types').ArrayExpression} arrayExpr
+ * @returns {Set<string>}
+ */
+function extractDepArrayNames(arrayExpr) {
+  const names = new Set();
+  for (const element of arrayExpr.elements) {
+    if (element && t.isIdentifier(element)) {
+      names.add(element.name);
+    } else if (element && t.isMemberExpression(element)) {
+      // e.g. obj.prop — extract the root identifier
+      let current = element;
+      while (t.isMemberExpression(current)) {
+        current = current.object;
+      }
+      if (t.isIdentifier(current)) names.add(current.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Get a short code snippet from source lines around a given line number.
+ * @param {string[]} lines - Source file lines
+ * @param {number} line - 1-indexed line number
+ * @param {number} [context=1] - Number of lines before/after to include
+ * @returns {string}
+ */
+function getCodeSnippet(lines, line, context = 1) {
+  const start = Math.max(0, line - 1 - context);
+  const end = Math.min(lines.length - 1, line - 1 + context);
+  return lines.slice(start, end + 1).join('\n').trim();
+}
+
+/**
+ * Check if a node contains JSX (returns JSX or has JSX children).
+ * @param {import('@babel/types').Node} node
+ * @returns {boolean}
+ */
+function containsJSX(node) {
+  let found = false;
+  try {
+    traverse(node, {
+      JSXElement() { found = true; },
+      JSXFragment() { found = true; },
+    }, null, {});
+  } catch (_) {
+    // traverse may throw on detached nodes — safe to ignore
+  }
+  return found;
+}
+
+/**
+ * Check if a CallExpression is an array method (map, filter, etc.)
+ * @param {import('@babel/types').Node} node
+ * @param {string[]} methods
+ * @returns {boolean}
+ */
+function isArrayMethod(node, methods) {
+  if (!t.isCallExpression(node)) return false;
+  const { callee } = node;
+  if (!t.isMemberExpression(callee)) return false;
+  const propName = t.isIdentifier(callee.property)
+    ? callee.property.name
+    : null;
+  return propName !== null && methods.includes(propName);
+}
+
+module.exports = {
+  jsxHasProp,
+  getJSXPropValue,
+  isReactComponent,
+  getComponentName,
+  isHookCall,
+  getDepsArray,
+  collectIdentifiers,
+  extractDepArrayNames,
+  getCodeSnippet,
+  containsJSX,
+  isArrayMethod,
+};

package/src/parser/BabelParser.js

@@ -0,0 +1,66 @@
+/**
+ * @file parser/BabelParser.js
+ * @description
+ * Wrapper around @babel/parser that handles JS, TS, JSX, and TSX.
+ * Provides consistent error handling and plugin selection.
+ */
+
+'use strict';
+
+const { parse } = require('@babel/parser');
+
+/**
+ * Babel parser plugins enabled for all files.
+ * Handles JSX, TypeScript, and common modern JS syntax.
+ * @type {import('@babel/parser').ParserPlugin[]}
+ */
+const BASE_PLUGINS = [
+  'jsx',
+  'typescript',
+  'decorators-legacy',
+  'classProperties',
+  'classPrivateProperties',
+  'classPrivateMethods',
+  'optionalChaining',
+  'nullishCoalescingOperator',
+  'objectRestSpread',
+  'dynamicImport',
+  'importMeta',
+  'exportDefaultFrom',
+  'exportNamespaceFrom',
+  'asyncGenerators',
+  'logicalAssignment',
+  'numericSeparator',
+  'optionalCatchBinding',
+];
+
+/**
+ * Parse a source file into a Babel AST.
+ * Returns a result object with either an AST or an error — never throws.
+ *
+ * @param {string} filePath - Absolute path to the file (used for error messages)
+ * @param {string} source - Raw source code content
+ * @returns {{ ast: import('@babel/parser').ParseResult<import('@babel/types').File>|null, error: Error|null }}
+ */
+function parseFile(filePath, source) {
+  try {
+    const ast = parse(source, {
+      sourceType: 'module',
+      allowImportExportEverywhere: true,
+      allowReturnOutsideFunction: true,
+      allowSuperOutsideMethod: true,
+      allowUndeclaredExports: true,
+      errorRecovery: true,   // Continue parsing even on syntax errors
+      plugins: BASE_PLUGINS,
+    });
+
+    return { ast, error: null };
+  } catch (err) {
+    return {
+      ast: null,
+      error: new Error(`Parse error in ${filePath}: ${err.message}`),
+    };
+  }
+}
+
+module.exports = { parseFile };

package/src/parser/ComponentDetector.js

@@ -0,0 +1,53 @@
+/**
+ * @file parser/ComponentDetector.js
+ * @description
+ * Utility to identify all React component declarations within an AST.
+ */
+
+'use strict';
+
+const traverse = require('@babel/traverse').default;
+const { isReactComponent, getComponentName } = require('./ASTUtils');
+
+/**
+ * Represents a detected React component in a file.
+ * @typedef {Object} ComponentInfo
+ * @property {string} name - Component name
+ * @property {number} startLine - 1-indexed start line
+ * @property {number} endLine - 1-indexed end line
+ * @property {import('@babel/traverse').NodePath} path - Babel AST path
+ */
+
+class ComponentDetector {
+  /**
+   * Extract all React components from an AST.
+   * @param {import('@babel/parser').ParseResult<import('@babel/types').File>} ast
+   * @returns {ComponentInfo[]}
+   */
+  static extract(ast) {
+    const components = [];
+
+    traverse(ast, {
+      enter(path) {
+        const node = path.node;
+        const name = getComponentName(node, path);
+        
+        if (name && isReactComponent(node, name)) {
+          // Additional heuristic: does it contain JSX? (optional, but good for filtering out plain utility functions with capitalized names)
+          // For now, we trust the uppercase name convention.
+          
+          components.push({
+            name,
+            startLine: node.loc ? node.loc.start.line : 0,
+            endLine: node.loc ? node.loc.end.line : 0,
+            path
+          });
+        }
+      }
+    });
+
+    return components;
+  }
+}
+
+module.exports = { ComponentDetector };

package/src/reporters/HtmlReporter.js

@@ -0,0 +1,42 @@
+/**
+ * @file reporters/HtmlReporter.js
+ * @description
+ * Generates an interactive HTML report by injecting scan results into a template.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getHtmlTemplate } = require('./templates/report.html');
+
+class HtmlReporter {
+  /**
+   * Generate an HTML report file.
+   * @param {import('../types').ReportData} reportData
+   * @returns {string} Absolute path to the generated HTML file
+   */
+  static generate(reportData) {
+    const outputDir = path.resolve(process.cwd(), reportData.config.outputDir);
+    
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    const outputPath = path.join(outputDir, 'renderpilot-report.html');
+    
+    // Inject the raw JSON data into the window object of the HTML template
+    const jsonString = JSON.stringify(reportData, null, 2);
+    
+    // Escape script tags in JSON to prevent XSS / broken HTML
+    const safeJsonString = jsonString.replace(/</g, '\\u003c');
+    
+    const htmlContent = getHtmlTemplate(safeJsonString);
+
+    fs.writeFileSync(outputPath, htmlContent, 'utf-8');
+    
+    return outputPath;
+  }
+}
+
+module.exports = { HtmlReporter };

package/src/reporters/JsonReporter.js

@@ -0,0 +1,52 @@
+/**
+ * @file reporters/JsonReporter.js
+ * @description
+ * Generates a machine-readable JSON report of the analysis.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class JsonReporter {
+  /**
+   * Write the scan results to a JSON file.
+   * @param {import('../types').ReportData} reportData
+   */
+  static generate(reportData) {
+    const outputDir = path.resolve(process.cwd(), reportData.config.outputDir);
+    
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    const outputPath = path.join(outputDir, 'renderpilot-report.json');
+    
+    // Create a clean JSON structure
+    const jsonOutput = {
+      version: reportData.version,
+      scan: {
+        root: reportData.scan.scanRoot,
+        startedAt: reportData.scan.startedAt,
+        completedAt: reportData.scan.completedAt,
+        durationMs: reportData.scan.durationMs,
+        stats: {
+          totalFiles: reportData.scan.totalFiles,
+          totalViolations: reportData.scan.totalViolations,
+          parseErrors: reportData.scan.parseErrors,
+          violationsBySeverity: reportData.scan.violationsBySeverity,
+          violationsByCategory: reportData.scan.violationsByCategory,
+        }
+      },
+      score: reportData.score,
+      violations: reportData.scan.allViolations
+    };
+
+    fs.writeFileSync(outputPath, JSON.stringify(jsonOutput, null, 2), 'utf-8');
+    
+    return outputPath;
+  }
+}
+
+module.exports = { JsonReporter };

package/src/reporters/TerminalReporter.js

@@ -0,0 +1,91 @@
+/**
+ * @file reporters/TerminalReporter.js
+ * @description
+ * Formats and prints a beautiful CLI report using chalk.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+
+class TerminalReporter {
+  /**
+   * Print the terminal report.
+   * @param {import('../types').ReportData} reportData
+   */
+  static generate({ scan, score }) {
+    console.log('\n' + chalk.bold.cyan('✈ RenderPilot Analysis Report'));
+    console.log(chalk.dim('=================================================='));
+
+    if (scan.totalViolations === 0) {
+      console.log(`\n🎉 ${chalk.green('No performance issues found!')}`);
+      console.log(`Scanned ${scan.totalFiles} files in ${scan.durationMs}ms.\n`);
+      return;
+    }
+
+    // Group violations by file for readable output
+    const filesWithIssues = scan.files.filter(f => f.violations.length > 0);
+
+    for (const file of filesWithIssues) {
+      console.log(`\n📄 ${chalk.bold.underline(file.relativePath)}`);
+      
+      for (const v of file.violations) {
+        const severityColor = this.getSeverityColor(v.severity);
+        const icon = this.getSeverityIcon(v.severity);
+        
+        console.log(`  ${icon} ${chalk.dim(`${v.line}:${v.column}`)} ${severityColor(v.message)} ${chalk.dim(`(${v.ruleId})`)}`);
+        
+        if (v.codeSnippet) {
+          console.log(chalk.dim(`    > ${v.codeSnippet.split('\n')[0].trim()}`));
+        }
+        
+        console.log(`    💡 ${chalk.italic(v.suggestion)}`);
+      }
+    }
+
+    console.log('\n' + chalk.dim('=================================================='));
+    console.log(chalk.bold('🏆 Performance Score'));
+    console.log(chalk.dim('=================================================='));
+    
+    const gradeColor = this.getGradeColor(score.grade);
+    console.log(`\n  Overall Score: ${gradeColor(score.overall)}/100 (${gradeColor(score.grade)}) — ${score.label}`);
+    
+    console.log('\n  Category Breakdown:');
+    for (const cat of score.categories) {
+       const catColor = this.getGradeColor(cat.grade);
+       const name = cat.category.charAt(0).toUpperCase() + cat.category.slice(1);
+       console.log(`    • ${name.padEnd(15)} : ${catColor(cat.score.toString().padStart(3))} (${cat.grade}) [${cat.violations} issues]`);
+    }
+
+    console.log('\n' + chalk.dim('=================================================='));
+    console.log(`⏱️  Scanned ${scan.totalFiles} files in ${scan.durationMs}ms.`);
+    
+    if (score.topRecommendation) {
+       console.log(`\n🎯 ${chalk.bold('Top Recommendation:')} ${score.topRecommendation}`);
+    }
+    console.log();
+  }
+
+  static getSeverityColor(severity) {
+    if (severity === 'critical') return chalk.red.bold;
+    if (severity === 'warning') return chalk.yellow;
+    return chalk.blue;
+  }
+
+  static getSeverityIcon(severity) {
+    if (severity === 'critical') return chalk.red('✖');
+    if (severity === 'warning') return chalk.yellow('⚠');
+    return chalk.blue('ℹ');
+  }
+
+  static getGradeColor(grade) {
+    if (grade === 'A') return chalk.green.bold;
+    if (grade === 'B') return chalk.green;
+    if (grade === 'C') return chalk.yellow;
+    if (grade === 'D') return chalk.keyword('orange');
+    return chalk.red.bold;
+  }
+}
+
+module.exports = { TerminalReporter };