renderpilot 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# RenderPilot ✈️
+
+**The Intelligent React Performance Analysis CLI**
+
+RenderPilot statically analyzes your React (**JS/TS/JSX/TSX**) codebase to detect performance anti-patterns, explain why they occur, estimate their impact, and suggest pragmatic fixes. It generates a comprehensive **Performance Score** and provides a developer-friendly interactive dashboard to track your fixes.
+
+---
+
+## 🌟 Key Features
+
+- **Built for Modern Stacks:** Seamlessly supports TypeScript (`.ts`, `.tsx`) and modern JavaScript syntax out of the box using Babel. No complex configuration required.
+- **Smart Component Detection:** Uses an advanced AST (Abstract Syntax Tree) engine to identify React Component boundaries. This means it safely ignores backend files (Express, NestJS), utility functions, and non-React files—preventing false positives.
+- **Interactive Developer Dashboard:** Generates a stunning, Vercel-inspired HTML report with collapsible file accordions, line-number highlighting, and a **"Mark as Fixed"** workflow to easily track your debugging progress.
+- **Pragmatic, Senior-Level Advice:** RenderPilot is designed to be a Performance Advisor, not a dogmatic linter.
+  - Differentiates between array mutations (`.sort()`) vs pure array methods (`.filter()`).
+  - Only recommends `React.memo` for components that actually receive props.
+- **Performance Grading:** Get an intelligent overall grade (A-F) based on severity-weighted categories (Rendering, Hooks, Architecture, Maintainability).
+
+## 🚀 Installation
+
+```bash
+npm install -g renderpilot
+# or
+npx renderpilot scan .
+```
+
+## 🛠️ Usage
+
+Scan your current directory (Outputs to Terminal):
+```bash
+renderpilot scan .
+```
+
+**Recommended:** Generate the interactive HTML dashboard:
+```bash
+renderpilot report .
+# Equivalent to: renderpilot scan . --html
+```
+*(This will automatically open `renderpilot-report.html` in your default browser).*
+
+Generate a JSON payload for CI integration:
+```bash
+renderpilot scan . --json
+```
+
+Get just the score (useful for CI/CD pipeline gates):
+```bash
+renderpilot scan . --score
+```
+
+## ⚙️ Configuration
+
+RenderPilot works zero-config out of the box. To customize it, create a `renderpilot.config.js` file in your project root:
+
+```javascript
+module.exports = {
+  // Directories to ignore during scan
+  ignoreDirs: ['node_modules', 'dist', 'build', '.next'],
+  
+  // Maximum component lines before triggering a warning
+  maxComponentLines: 300,
+  
+  // Override severity for specific rules
+  severityOverrides: {
+    'R001': 'critical', // Missing key prop
+  },
+  
+  // Explicitly disable certain rules
+  disabledRules: ['R004', 'R007'],
+  
+  // Output directory for HTML and JSON reports
+  outputDir: '.renderpilot'
+};
+```
+
+## 📏 Core Rules
+
+| ID | Name | Category | Severity |
+|----|------|----------|----------|
+| **R001** | Missing Key Prop | Rendering | Warning |
+| **R002** | Infinite useEffect Loop | Hooks | Critical |
+| **R003** | Incorrect Dependency Array | Hooks | Warning |
+| **R004** | Large Component | Architecture | Info |
+| **R005** | Inline Callback Detection | Rendering | Info |
+| **R006** | Heavy Calculations in Render | Rendering | Warning |
+| **R007** | React.memo Candidate | Rendering | Info |
+| **R008** | Nested Component Declarations | Architecture | Critical |
+| **R009** | Unused React State | Maintainability| Warning |
+
+## 💯 How the Scoring Works
+
+Your project starts with 100 points. Points are deducted based on rule violations, severity, and category weight.
+- **Critical Issues (-15 points)** (Multiplied by category weight)
+- **Warnings (-5 points)**
+- **Info (-1 point)**
+
+Categories are weighted by performance impact:
+- **Rendering** (1.5x)
+- **Hooks** (1.3x)
+- **Architecture** (1.0x)
+- **Maintainability** (0.7x)
+
+## 💻 Programmatic API
+
+You can use RenderPilot as a Node.js library to integrate it into your own tools:
+
+```javascript
+const { ProjectScanner, ScoreCalculator, loadConfig } = require('renderpilot');
+
+async function run() {
+  const config = loadConfig('./src');
+  const scanResult = await ProjectScanner.scan('./src', config);
+  const score = ScoreCalculator.compute(scanResult.allViolations);
+  
+  console.log('Score:', score.overall);
+}
+```
+
+## 📄 License
+
+MIT © RenderPilot Contributors

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "renderpilot",
+  "version": "1.0.0",
+  "description": "The Intelligent React (JS/TSX) Performance Analysis CLI — detects anti-patterns, generates interactive HTML reports, and provides pragmatic fixes.",
+  "keywords": [
+    "react",
+    "performance",
+    "cli",
+    "static-analysis",
+    "ast",
+    "jsx",
+    "tsx",
+    "react-performance",
+    "code-analysis",
+    "developer-tools"
+  ],
+  "author": "RenderPilot Contributors",
+  "license": "MIT",
+  "homepage": "https://github.com/ADITYA-user18/renderpilot#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ADITYA-user18/renderpilot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ADITYA-user18/renderpilot/issues"
+  },
+  "main": "./src/index.js",
+  "bin": {
+    "renderpilot": "./src/cli/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node src/cli/index.js",
+    "dev": "node src/cli/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.js\""
+  },
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0",
+    "@babel/types": "^7.24.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "open": "^8.4.2",
+    "ora": "^5.4.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "prettier": "^3.3.2"
+  },
+  "type": "commonjs"
+}

package/src/cli/commands/scan.js

@@ -0,0 +1,83 @@
+/**
+ * @file cli/commands/scan.js
+ * @description
+ * The main 'scan' command.
+ */
+
+'use strict';
+
+const path = require('path');
+const ora = require('ora');
+const chalk = require('chalk');
+const open = require('open');
+const { loadConfig } = require('../../config/ConfigLoader');
+const { ProjectScanner } = require('../../scanner/ProjectScanner');
+const { ScoreCalculator } = require('../../score/ScoreCalculator');
+const { TerminalReporter } = require('../../reporters/TerminalReporter');
+const { JsonReporter } = require('../../reporters/JsonReporter');
+const { HtmlReporter } = require('../../reporters/HtmlReporter');
+
+/**
+ * Handle the 'scan' command.
+ * @param {string} targetDir
+ * @param {object} cmdOptions
+ */
+async function handleScan(targetDir = '.', cmdOptions) {
+  const rootDir = path.resolve(process.cwd(), targetDir);
+  
+  // 1. Load config
+  const config = loadConfig(rootDir); // In the future, cmdOptions.config can override
+  
+  // 2. Initialize Spinner
+  const spinner = ora(`Discovering React files in ${chalk.bold(rootDir)}...`).start();
+
+  try {
+    // 3. Run Scan
+    const scanResult = await ProjectScanner.scan(rootDir, config);
+    
+    spinner.succeed(`Scanned ${scanResult.totalFiles} files in ${scanResult.durationMs}ms`);
+
+    // 4. Calculate Score
+    const score = ScoreCalculator.compute(scanResult.allViolations);
+
+    const reportData = {
+      version: require('../../../package.json').version,
+      scan: scanResult,
+      score,
+      config,
+    };
+
+    // 5. Generate Outputs
+    if (cmdOptions.score) {
+      // Just print the score
+      console.log(`\n🏆 Performance Score: ${chalk.bold.green(score.overall + '/100')} (${score.grade})`);
+      return;
+    }
+
+    TerminalReporter.generate(reportData);
+
+    if (cmdOptions.json) {
+      const jsonPath = JsonReporter.generate(reportData);
+      console.log(`💾 JSON report saved to: ${chalk.blue(jsonPath)}`);
+    }
+
+    if (cmdOptions.html) {
+      const htmlPath = HtmlReporter.generate(reportData);
+      console.log(`🌐 HTML report saved to: ${chalk.blue(htmlPath)}`);
+      
+      // Auto-open if possible
+      try {
+        await open(htmlPath);
+      } catch (err) {
+        console.log(chalk.dim(`(Could not auto-open browser: ${err.message})`));
+      }
+    }
+
+  } catch (error) {
+    spinner.fail('Scan failed due to an internal error.');
+    console.error(chalk.red('\nError Details:'), error);
+    process.exit(1);
+  }
+}
+
+module.exports = { handleScan };

package/src/cli/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * @file cli/index.js
+ * @description
+ * Main CLI entry point. Wires up Commander and parses arguments.
+ */
+
+'use strict';
+
+const { Command } = require('commander');
+const { version, description } = require('../../package.json');
+const { handleScan } = require('./commands/scan');
+const { options } = require('./options');
+
+// Ensure rules are registered before anything runs
+require('../rules/index');
+
+const program = new Command();
+
+program
+  .name('renderpilot')
+  .description(description)
+  .version(version);
+
+program
+  .command('scan [directory]')
+  .description('Scan a React project for performance issues')
+  .addOption(options.json)
+  .addOption(options.html)
+  .addOption(options.score)
+  .addOption(options.config)
+  .action((directory, cmdOptions) => {
+    handleScan(directory, cmdOptions);
+  });
+
+// renderpilot report is just an alias for scan --html for now
+program
+  .command('report [directory]')
+  .description('Scan a project and immediately open the HTML report')
+  .action((directory) => {
+    handleScan(directory, { html: true });
+  });
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/src/cli/options.js

@@ -0,0 +1,18 @@
+/**
+ * @file cli/options.js
+ * @description
+ * Reusable Commander.js options shared across multiple commands.
+ */
+
+'use strict';
+
+const { Option } = require('commander');
+
+const options = {
+  json: new Option('--json', 'Output results as a JSON file').default(false),
+  html: new Option('--html', 'Output results as an interactive HTML report').default(false),
+  score: new Option('--score', 'Only print the overall performance score').default(false),
+  config: new Option('-c, --config <path>', 'Path to custom config file'),
+};
+
+module.exports = { options };

package/src/config/ConfigLoader.js

@@ -0,0 +1,102 @@
+/**
+ * @file config/ConfigLoader.js
+ * @description
+ * Loads and merges user configuration from renderpilot.config.js
+ * with built-in defaults. Performs validation and normalization.
+ *
+ * Resolution order:
+ *   1. Look for renderpilot.config.js in the scan root
+ *   2. Look for renderpilot.config.js in process.cwd()
+ *   3. Fall back to DEFAULT_CONFIG
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { DEFAULT_CONFIG } = require('./DefaultConfig');
+
+/**
+ * Attempts to load a renderpilot.config.js file from the given directory.
+ * @param {string} dir - Directory to search in
+ * @returns {import('../types').UserConfig|null} User config or null if not found
+ */
+function loadConfigFile(dir) {
+  const configPath = path.join(dir, 'renderpilot.config.js');
+  if (!fs.existsSync(configPath)) return null;
+
+  try {
+    // Clear require cache to support hot-reloading in watch mode
+    delete require.cache[require.resolve(configPath)];
+    return require(configPath);
+  } catch (err) {
+    console.warn(
+      `[RenderPilot] Warning: Failed to load config at ${configPath}: ${err.message}`
+    );
+    return null;
+  }
+}
+
+/**
+ * Merges user config with defaults and normalizes into a ResolvedConfig.
+ * @param {import('../types').UserConfig} userConfig - User-provided config
+ * @returns {import('../types').ResolvedConfig} Resolved config
+ */
+function mergeConfig(userConfig) {
+  const merged = { ...DEFAULT_CONFIG };
+
+  if (Array.isArray(userConfig.ignoreDirs)) {
+    // Merge user ignore dirs with defaults (union)
+    merged.ignoreDirs = [
+      ...new Set([...DEFAULT_CONFIG.ignoreDirs, ...userConfig.ignoreDirs]),
+    ];
+  }
+
+  if (typeof userConfig.maxComponentLines === 'number' && userConfig.maxComponentLines > 0) {
+    merged.maxComponentLines = userConfig.maxComponentLines;
+  }
+
+  if (userConfig.severityOverrides && typeof userConfig.severityOverrides === 'object') {
+    merged.severityOverrides = { ...userConfig.severityOverrides };
+  }
+
+  if (Array.isArray(userConfig.enabledRules) && userConfig.enabledRules.length > 0) {
+    merged.enabledRules = new Set(userConfig.enabledRules);
+  }
+
+  if (Array.isArray(userConfig.disabledRules) && userConfig.disabledRules.length > 0) {
+    merged.disabledRules = new Set(userConfig.disabledRules);
+  }
+
+  if (typeof userConfig.outputDir === 'string' && userConfig.outputDir.trim()) {
+    merged.outputDir = userConfig.outputDir.trim();
+  }
+
+  merged.hasCustomConfig = true;
+  return merged;
+}
+
+/**
+ * Loads and resolves configuration for a scan.
+ * Searches scanRoot first, then cwd, then uses defaults.
+ *
+ * @param {string} scanRoot - The root directory being scanned
+ * @returns {import('../types').ResolvedConfig} Fully resolved config
+ */
+function loadConfig(scanRoot) {
+  // Try scan root first
+  let userConfig = loadConfigFile(scanRoot);
+
+  // Fall back to cwd if not in scan root
+  if (!userConfig && scanRoot !== process.cwd()) {
+    userConfig = loadConfigFile(process.cwd());
+  }
+
+  if (!userConfig) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  return mergeConfig(userConfig);
+}
+
+module.exports = { loadConfig };

package/src/config/DefaultConfig.js

@@ -0,0 +1,33 @@
+/**
+ * @file config/DefaultConfig.js
+ * @description Built-in default configuration for RenderPilot.
+ * All defaults live here — never scattered across modules.
+ */
+
+'use strict';
+
+/** @type {import('../types').ResolvedConfig} */
+const DEFAULT_CONFIG = {
+  ignoreDirs: [
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.next',
+    '.nuxt',
+    'out',
+    '.cache',
+    'public',
+    'static',
+    'assets',
+  ],
+  maxComponentLines: 300,
+  severityOverrides: {},
+  enabledRules: null,       // null = all rules enabled
+  disabledRules: new Set(),
+  outputDir: '.renderpilot',
+  hasCustomConfig: false,
+};
+
+module.exports = { DEFAULT_CONFIG };

package/src/index.js

@@ -0,0 +1,34 @@
+/**
+ * @file index.js
+ * @description
+ * Main package export. Allows RenderPilot to be consumed programmatically
+ * by other Node.js scripts instead of just via the CLI.
+ */
+
+'use strict';
+
+// Ensure rules are registered
+require('./rules/index');
+
+const { ProjectScanner } = require('./scanner/ProjectScanner');
+const { ScoreCalculator } = require('./score/ScoreCalculator');
+const { loadConfig } = require('./config/ConfigLoader');
+const { ruleRegistry } = require('./rules/registry/RuleRegistry');
+
+module.exports = {
+  // Core APIs
+  ProjectScanner,
+  ScoreCalculator,
+  loadConfig,
+  
+  // Rule Registry access for custom rules
+  ruleRegistry,
+  
+  // Re-export base rule for custom rule creation
+  AbstractRule: require('./rules/base/AbstractRule').AbstractRule,
+  
+  // Reporters
+  TerminalReporter: require('./reporters/TerminalReporter').TerminalReporter,
+  JsonReporter: require('./reporters/JsonReporter').JsonReporter,
+  HtmlReporter: require('./reporters/HtmlReporter').HtmlReporter,
+};