renderpilot 1.0.0

package/src/rules/base/AbstractRule.js

@@ -0,0 +1,136 @@
+/**
+ * @file rules/base/AbstractRule.js
+ * @description
+ * Abstract base class for all RenderPilot rules.
+ * Every rule extends this and implements the detect() method.
+ *
+ * Design principle: detect() is the only required override.
+ * fixSuggestion() and estimatedImpact() have sensible defaults
+ * that rules can override for more specific guidance.
+ */
+
+'use strict';
+
+/**
+ * Abstract base class for a RenderPilot analysis rule.
+ * @abstract
+ */
+class AbstractRule {
+  /**
+   * @param {object} options - Rule metadata
+   * @param {string} options.id - Unique rule ID (e.g. "R001")
+   * @param {string} options.name - Human-readable rule name
+   * @param {string} options.description - What this rule detects
+   * @param {import('../../types').Severity} options.severity - Default severity
+   * @param {import('../../types').Category} options.category - Performance category
+   * @param {string} [options.docsUrl] - Documentation URL
+   */
+  constructor({ id, name, description, severity, category, docsUrl }) {
+    if (new.target === AbstractRule) {
+      throw new Error('AbstractRule cannot be instantiated directly.');
+    }
+
+    /** @type {string} */
+    this.id = id;
+    /** @type {string} */
+    this.name = name;
+    /** @type {string} */
+    this.description = description;
+    /** @type {import('../../types').Severity} */
+    this.severity = severity;
+    /** @type {import('../../types').Category} */
+    this.category = category;
+    /** @type {string} */
+    this.docsUrl = docsUrl || `https://renderpilot.dev/rules/${id.toLowerCase()}`;
+  }
+
+  /**
+   * Detect violations in the given rule context.
+   * Subclasses MUST implement this method.
+   *
+   * @abstract
+   * @param {import('../../types').RuleContext} context
+   * @returns {import('../../types').RuleViolation[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  detect(_context) {
+    throw new Error(`Rule ${this.id} must implement detect()`);
+  }
+
+  /**
+   * Generate a fix suggestion for a violation.
+   * Override for rule-specific guidance.
+   *
+   * @param {import('../../types').RuleViolation} _violation
+   * @returns {string}
+   */
+  // eslint-disable-next-line no-unused-vars
+  fixSuggestion(_violation) {
+    return 'Review the flagged code and apply performance best practices.';
+  }
+
+  /**
+   * Estimate the performance impact of a violation.
+   * Override to provide rule-specific estimates.
+   *
+   * @param {import('../../types').RuleViolation} _violation
+   * @returns {import('../../types').ImpactEstimate}
+   */
+  // eslint-disable-next-line no-unused-vars
+  estimatedImpact(_violation) {
+    const levelMap = {
+      critical: 'critical',
+      warning: 'medium',
+      info: 'low',
+    };
+    return {
+      level: levelMap[this.severity] || 'low',
+      description: 'Performance impact varies. Address to improve render efficiency.',
+    };
+  }
+
+  /**
+   * Helper: create a RuleViolation object.
+   * Rules call this instead of constructing raw objects.
+   *
+   * @param {object} options
+   * @param {string} options.filePath
+   * @param {number} options.line
+   * @param {number} options.column
+   * @param {string} options.message
+   * @param {string} options.suggestion
+   * @param {string} [options.codeSnippet]
+   * @param {string} [options.componentName]
+   * @param {import('../../types').Severity} [options.severity] - Override default severity
+   * @returns {import('../../types').RuleViolation}
+   */
+  createViolation({
+    filePath,
+    line,
+    column,
+    message,
+    suggestion,
+    codeSnippet,
+    componentName,
+    severity,
+  }) {
+    const effectiveSeverity = severity || this.severity;
+    const violation = {
+      ruleId: this.id,
+      ruleName: this.name,
+      severity: effectiveSeverity,
+      category: this.category,
+      filePath,
+      line,
+      column: column || 0,
+      message,
+      suggestion,
+      impact: this.estimatedImpact({ ruleId: this.id, severity: effectiveSeverity }),
+      codeSnippet,
+      componentName,
+    };
+    return violation;
+  }
+}
+
+module.exports = { AbstractRule };

package/src/rules/engine/RuleEngine.js

@@ -0,0 +1,67 @@
+/**
+ * @file rules/engine/RuleEngine.js
+ * @description
+ * The core execution engine. Takes an AST and configuration,
+ * runs all active rules against it, and aggregates the violations.
+ */
+
+'use strict';
+
+const { ruleRegistry } = require('../registry/RuleRegistry');
+const { getComponentName, isReactComponent } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+
+class RuleEngine {
+  /**
+   * Run all active rules on a given file.
+   *
+   * @param {import('../../types').RuleContext} context
+   * @returns {import('../../types').RuleViolation[]}
+   */
+  static run(context) {
+    if (!context.ast) return [];
+
+    const activeRules = ruleRegistry.getActiveRules(context.config);
+    if (activeRules.length === 0) return [];
+
+    let violations = [];
+
+    // Pre-process: Find components to enrich the context if needed, 
+    // but the actual detection is up to each rule.
+    // We pass the context directly to rules. Rules can traverse the AST themselves.
+    
+    // Note: Some rules might benefit from a shared traversal, but to keep the 
+    // architecture truly modular and decoupled, we let each rule run its own detect().
+    // Babel AST traversal is fast enough for our use cases, but if performance 
+    // becomes an issue on massive codebases, we could transition to a visitor pattern 
+    // where rules register visitors and the engine does a single pass.
+    
+    // For now, each rule is self-contained.
+    for (const rule of activeRules) {
+      try {
+        const ruleViolations = rule.detect(context);
+        
+        // Apply severity overrides if any
+        const override = context.config.severityOverrides[rule.id];
+        if (override) {
+          ruleViolations.forEach(v => {
+            v.severity = override;
+            // Re-evaluate impact if severity changed
+            v.impact = rule.estimatedImpact({ ...v, severity: override });
+          });
+        }
+        
+        violations.push(...ruleViolations);
+      } catch (err) {
+        console.error(`[RenderPilot] Error running rule ${rule.id} on ${context.filePath}:`, err);
+      }
+    }
+
+    // Sort violations by line number
+    violations.sort((a, b) => a.line - b.line);
+
+    return violations;
+  }
+}
+
+module.exports = { RuleEngine };

package/src/rules/implementations/R001_MissingKeyProp.js

@@ -0,0 +1,97 @@
+/**
+ * @file rules/implementations/R001_MissingKeyProp.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { getCodeSnippet } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+class R001_MissingKeyProp extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R001',
+      name: 'Missing Key Prop in Iterator',
+      description: 'Detects JSX elements returned from array iterations (like map) that are missing a "key" prop.',
+      severity: 'warning',
+      category: 'rendering',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+
+    traverse(context.ast, {
+      CallExpression: (path) => {
+        const callee = path.node.callee;
+        
+        // Check for .map()
+        if (
+          t.isMemberExpression(callee) &&
+          t.isIdentifier(callee.property, { name: 'map' })
+        ) {
+          const callback = path.node.arguments[0];
+          
+          if (
+            t.isArrowFunctionExpression(callback) ||
+            t.isFunctionExpression(callback)
+          ) {
+            let jsxElement = null;
+
+            if (t.isJSXElement(callback.body) || t.isJSXFragment(callback.body)) {
+              // Implicit return: .map(() => <div />)
+              jsxElement = callback.body;
+            } else if (t.isBlockStatement(callback.body)) {
+              // Explicit return: .map(() => { return <div />; })
+              const returnStmt = callback.body.body.find(stmt => t.isReturnStatement(stmt));
+              if (returnStmt && (t.isJSXElement(returnStmt.argument) || t.isJSXFragment(returnStmt.argument))) {
+                jsxElement = returnStmt.argument;
+              }
+            }
+
+            if (jsxElement) {
+              if (t.isJSXFragment(jsxElement)) {
+                // Fragments must use shorthand syntax or explicitly <React.Fragment key={...}>
+                // A bare <>...</> cannot have keys.
+                violations.push(
+                  this.createViolation({
+                    filePath: context.filePath,
+                    line: jsxElement.loc ? jsxElement.loc.start.line : 0,
+                    column: jsxElement.loc ? jsxElement.loc.start.column : 0,
+                    message: 'Missing "key" prop. Fragments returned from map() must use <React.Fragment key={...}> instead of <>...</>.',
+                    suggestion: 'Change <> to <React.Fragment key={uniqueId}>.',
+                    codeSnippet: getCodeSnippet(context.lines, jsxElement.loc ? jsxElement.loc.start.line : 0),
+                  })
+                );
+              } else if (t.isJSXElement(jsxElement)) {
+                // Check if 'key' exists
+                const hasKey = jsxElement.openingElement.attributes.some(
+                  attr => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: 'key' })
+                );
+
+                if (!hasKey) {
+                   violations.push(
+                    this.createViolation({
+                      filePath: context.filePath,
+                      line: jsxElement.loc ? jsxElement.loc.start.line : 0,
+                      column: jsxElement.loc ? jsxElement.loc.start.column : 0,
+                      message: 'Missing "key" prop on JSX element returned from array.map().',
+                      suggestion: 'Add a unique "key" prop to the root element returned by the map callback.',
+                      codeSnippet: getCodeSnippet(context.lines, jsxElement.loc ? jsxElement.loc.start.line : 0),
+                    })
+                  );
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    return violations;
+  }
+}
+
+module.exports = { R001_MissingKeyProp };

package/src/rules/implementations/R002_InfiniteUseEffect.js

@@ -0,0 +1,86 @@
+/**
+ * @file rules/implementations/R002_InfiniteUseEffect.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { getCodeSnippet, isHookCall, getDepsArray } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+class R002_InfiniteUseEffect extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R002',
+      name: 'Infinite useEffect Loop',
+      description: 'Detects useEffect hooks without a dependency array that contain state updates, which causes infinite rerenders.',
+      severity: 'critical',
+      category: 'hooks',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+
+    // Step 1: Find all state setters in the file so we know what they look like
+    const stateSetters = new Set();
+    traverse(context.ast, {
+      VariableDeclarator(path) {
+        if (
+          t.isCallExpression(path.node.init) &&
+          (t.isIdentifier(path.node.init.callee, { name: 'useState' }) || 
+           (t.isMemberExpression(path.node.init.callee) && t.isIdentifier(path.node.init.callee.property, { name: 'useState' }))) &&
+          t.isArrayPattern(path.node.id) &&
+          path.node.id.elements.length === 2 &&
+          t.isIdentifier(path.node.id.elements[1])
+        ) {
+          stateSetters.add(path.node.id.elements[1].name);
+        }
+      }
+    });
+
+    // Step 2: Check useEffects
+    traverse(context.ast, {
+      CallExpression: (path) => {
+        if (isHookCall(path.node, 'useEffect')) {
+          const deps = getDepsArray(path.node);
+          
+          // If there is NO dependency array (not even an empty one)
+          if (!deps) {
+            const callback = path.node.arguments[0];
+            let callsStateSetter = false;
+
+            if (callback && (t.isArrowFunctionExpression(callback) || t.isFunctionExpression(callback))) {
+              traverse(callback, {
+                CallExpression(innerPath) {
+                  if (t.isIdentifier(innerPath.node.callee) && stateSetters.has(innerPath.node.callee.name)) {
+                    callsStateSetter = true;
+                    innerPath.stop();
+                  }
+                }
+              }, path.scope, null, path);
+            }
+
+            if (callsStateSetter) {
+               violations.push(
+                this.createViolation({
+                  filePath: context.filePath,
+                  line: path.node.loc ? path.node.loc.start.line : 0,
+                  column: path.node.loc ? path.node.loc.start.column : 0,
+                  message: 'useEffect without a dependency array calls a state setter. This will cause an infinite render loop.',
+                  suggestion: 'Add a dependency array [] to run only on mount, or include specific dependencies.',
+                  codeSnippet: getCodeSnippet(context.lines, path.node.loc ? path.node.loc.start.line : 0),
+                })
+              );
+            }
+          }
+        }
+      }
+    });
+
+    return violations;
+  }
+}
+
+module.exports = { R002_InfiniteUseEffect };

package/src/rules/implementations/R003_IncorrectDepsArray.js

@@ -0,0 +1,112 @@
+/**
+ * @file rules/implementations/R003_IncorrectDepsArray.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { getCodeSnippet, isHookCall, getDepsArray, collectIdentifiers, extractDepArrayNames } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+class R003_IncorrectDepsArray extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R003',
+      name: 'Incorrect Dependency Array',
+      description: 'Detects variables referenced inside useEffect/useCallback/useMemo that are missing from the dependency array.',
+      severity: 'warning',
+      category: 'hooks',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+    const hooksToCheck = ['useEffect', 'useCallback', 'useMemo'];
+
+    traverse(context.ast, {
+      CallExpression: (path) => {
+        const hookName = hooksToCheck.find(h => isHookCall(path.node, h));
+        if (hookName) {
+          const depsArray = getDepsArray(path.node);
+          
+          if (depsArray) {
+            const callback = path.node.arguments[0];
+            if (callback && (t.isArrowFunctionExpression(callback) || t.isFunctionExpression(callback))) {
+              
+              // 1. Get all variables referenced inside the callback
+              const referencedIds = new Set();
+              
+              // Walk the callback body and collect variables that are NOT declared locally
+              path.get('arguments.0').traverse({
+                Identifier(innerPath) {
+                  // Ignore object properties
+                  if (t.isMemberExpression(innerPath.parent) && innerPath.parent.property === innerPath.node && !innerPath.parent.computed) return;
+                  
+                  // Must be a reference, not a declaration
+                  if (innerPath.isReferencedIdentifier()) {
+                    const name = innerPath.node.name;
+                    
+                    // Is it bound in the scope outside the hook, but inside the component?
+                    const binding = innerPath.scope.getBinding(name);
+                    
+                    // We only care about variables bound in the outer scope (e.g. component scope)
+                    // If binding is null, it's a global (like window).
+                    // If binding exists but it's bound at the file root (module scope), it's static, ignore.
+                    if (binding && binding.scope !== path.scope.getProgramParent()) {
+                      // Also ensure it's not bound *inside* the callback itself
+                      const callbackScope = path.get('arguments.0').scope;
+                      let isLocal = false;
+                      let currentScope = binding.scope;
+                      while(currentScope) {
+                        if (currentScope === callbackScope) {
+                          isLocal = true;
+                          break;
+                        }
+                        currentScope = currentScope.parent;
+                      }
+                      
+                      if (!isLocal) {
+                        referencedIds.add(name);
+                      }
+                    }
+                  }
+                }
+              });
+
+              // 2. Get dependencies explicitly listed
+              const listedDeps = extractDepArrayNames(depsArray);
+
+              // 3. Find missing dependencies
+              const missing = [];
+              for (const ref of referencedIds) {
+                if (!listedDeps.has(ref) && ref !== 'dispatch' && ref !== 'set' + ref.substring(3)) {
+                   // Crude heuristic to ignore some setX functions, standard linter does this better with flow analysis
+                   // but this works for 90% of cases
+                   missing.push(ref);
+                }
+              }
+
+              if (missing.length > 0) {
+                violations.push(
+                  this.createViolation({
+                    filePath: context.filePath,
+                    line: depsArray.loc ? depsArray.loc.start.line : 0,
+                    column: depsArray.loc ? depsArray.loc.start.column : 0,
+                    message: `${hookName} has missing dependencies: ${missing.join(', ')}.`,
+                    suggestion: `Include [${missing.join(', ')}] in the dependency array.`,
+                    codeSnippet: getCodeSnippet(context.lines, depsArray.loc ? depsArray.loc.start.line : 0),
+                  })
+                );
+              }
+            }
+          }
+        }
+      }
+    });
+
+    return violations;
+  }
+}
+
+module.exports = { R003_IncorrectDepsArray };

package/src/rules/implementations/R004_LargeComponent.js

@@ -0,0 +1,47 @@
+/**
+ * @file rules/implementations/R004_LargeComponent.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { ComponentDetector } = require('../../parser/ComponentDetector');
+
+class R004_LargeComponent extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R004',
+      name: 'Large Component',
+      description: 'Warns when a component exceeds a configurable line count limit.',
+      severity: 'info',
+      category: 'architecture',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+    const maxLines = context.config.maxComponentLines || 300;
+    const components = ComponentDetector.extract(context.ast);
+
+    for (const comp of components) {
+      const lineCount = comp.endLine - comp.startLine + 1;
+      
+      if (lineCount > maxLines) {
+        violations.push(
+          this.createViolation({
+            filePath: context.filePath,
+            line: comp.startLine,
+            column: 0,
+            message: `Component "${comp.name}" is ${lineCount} lines long, exceeding the limit of ${maxLines}.`,
+            suggestion: 'Consider breaking this component down into smaller, focused sub-components.',
+            componentName: comp.name,
+          })
+        );
+      }
+    }
+
+    return violations;
+  }
+}
+
+module.exports = { R004_LargeComponent };

package/src/rules/implementations/R005_InlineCallback.js

@@ -0,0 +1,58 @@
+/**
+ * @file rules/implementations/R005_InlineCallback.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { getCodeSnippet } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+class R005_InlineCallback extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R005',
+      name: 'Inline Callback Detection',
+      description: 'Detects inline arrow functions passed to DOM events or components, which cause unnecessary recreations.',
+      severity: 'info',
+      category: 'rendering',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+
+    traverse(context.ast, {
+      JSXAttribute: (path) => {
+        const attrName = path.node.name.name;
+        
+        // Target common event handlers like onClick, onChange, onSubmit
+        if (typeof attrName === 'string' && attrName.startsWith('on') && attrName[2] === attrName[2]?.toUpperCase()) {
+          const value = path.node.value;
+          
+          if (t.isJSXExpressionContainer(value)) {
+            const expr = value.expression;
+            
+            if (t.isArrowFunctionExpression(expr) || t.isFunctionExpression(expr)) {
+               violations.push(
+                this.createViolation({
+                  filePath: context.filePath,
+                  line: path.node.loc ? path.node.loc.start.line : 0,
+                  column: path.node.loc ? path.node.loc.start.column : 0,
+                  message: `Inline callback detected on ${attrName}. This creates a new function on every render.`,
+                  suggestion: 'Consider useCallback if passing it to memoized children or if profiling indicates a performance issue.',
+                  codeSnippet: getCodeSnippet(context.lines, path.node.loc ? path.node.loc.start.line : 0),
+                })
+              );
+            }
+          }
+        }
+      }
+    });
+
+    return violations;
+  }
+}
+
+module.exports = { R005_InlineCallback };

package/src/rules/implementations/R006_HeavyRenderCalc.js

@@ -0,0 +1,86 @@
+/**
+ * @file rules/implementations/R006_HeavyRenderCalc.js
+ */
+
+'use strict';
+
+const { AbstractRule } = require('../base/AbstractRule');
+const { getCodeSnippet, isArrayMethod } = require('../../parser/ASTUtils');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+
+class R006_HeavyRenderCalc extends AbstractRule {
+  constructor() {
+    super({
+      id: 'R006',
+      name: 'Heavy Calculations Inside Render',
+      description: 'Detects heavy array operations (filter, map, reduce, sort) occurring directly inside the render path, which blocks painting.',
+      severity: 'warning',
+      category: 'rendering',
+    });
+  }
+
+  detect(context) {
+    const violations = [];
+    const heavyMethods = ['filter', 'reduce', 'sort', 'find'];
+    const { ComponentDetector } = require('../../parser/ComponentDetector');
+    const components = ComponentDetector.extract(context.ast);
+
+    traverse(context.ast, {
+      CallExpression: (path) => {
+        if (isArrayMethod(path.node, heavyMethods)) {
+          const line = path.node.loc ? path.node.loc.start.line : 0;
+          
+          // Only proceed if this call is inside an actual React component
+          const enclosingComponent = components.find(c => line >= c.startLine && line <= c.endLine);
+          
+          if (enclosingComponent) {
+            let isInHook = false;
+            
+            let current = path.parentPath;
+            while (current && current.node !== enclosingComponent.path.node) {
+               // Check if we hit a hook boundary before hitting the component root
+               if (t.isCallExpression(current.node) && 
+                  (t.isIdentifier(current.node.callee, {name: 'useEffect'}) || 
+                   t.isIdentifier(current.node.callee, {name: 'useCallback'}) ||
+                   t.isIdentifier(current.node.callee, {name: 'useMemo'}))) {
+                   isInHook = true;
+                   break;
+               }
+               current = current.parentPath;
+            }
+
+            if (!isInHook) {
+               const methodName = path.node.callee.property.name;
+               let message, suggestion;
+               
+               if (methodName === 'sort') {
+                 message = `Potential expensive calculation (.sort()). Array.sort() mutates the original array.`;
+                 suggestion = `Use [...data].sort(...) to avoid mutating state, and consider useMemo if the array is large.`;
+               } else {
+                 message = `Potential expensive calculation (.${methodName}()) inside render.`;
+                 suggestion = `If this computation is costly or the array is large, consider useMemo.`;
+               }
+
+               violations.push(
+                this.createViolation({
+                  filePath: context.filePath,
+                  line: path.node.loc ? path.node.loc.start.line : 0,
+                  column: path.node.loc ? path.node.loc.start.column : 0,
+                  message,
+                  suggestion,
+                  codeSnippet: getCodeSnippet(context.lines, path.node.loc ? path.node.loc.start.line : 0),
+                  componentName: enclosingComponent.name,
+                })
+              );
+            }
+          }
+        }
+      }
+    });
+
+    return violations;
+  }
+}
+
+module.exports = { R006_HeavyRenderCalc };