react-code-smell-detector 1.4.1 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@ A CLI tool that analyzes React projects and detects common code smells, providin
 
 ## Features
 
-- 🔍 **Detect Code Smells**: Identifies common React anti-patterns (51+ smell types)
+- 🔍 **Detect Code Smells**: Identifies common React anti-patterns (70+ smell types)
 - 📊 **Technical Debt Score**: Grades your codebase from A to F
 - 💡 **Refactoring Suggestions**: Actionable recommendations for each issue
 - 📝 **Multiple Output Formats**: Console (colored), JSON, Markdown, and HTML
@@ -21,6 +21,20 @@ A CLI tool that analyzes React projects and detects common code smells, providin
 - 🗑️ **Unused Code Detection**: Find unused exports and dead imports
 - 📈 **Baseline Tracking**: Track code smell trends over time with git commit history
 - 💬 **Chat Notifications**: Send analysis results to Slack, Discord, or custom webhooks
+- 🔗 **Dependency Graph Visualization**: Visual SVG/HTML of component and import relationships
+- 📦 **Bundle Size Impact**: Per-component bundle size estimates and optimization suggestions
+- ⚙️ **Custom Rules Engine**: Define project-specific code quality rules in configuration
+- 🔧 **Interactive Fix Mode**: Review and apply fixes one by one with diff preview
+- 💬 **GitHub PR Comments**: Auto-comment analysis results on pull requests
+- 📊 **Performance Budget**: Set thresholds and enforce limits in CI/CD
+- 📚 **Component Documentation**: Auto-generate docs from component analysis
+- ⚛️ **React 19 Server Components**: Detect Server/Client boundary issues
+- 🔮 **Context API Analysis**: Detect context overuse, missing memoization, re-render issues
+- 🛡️ **Error Boundary Detection**: Find missing ErrorBoundary and Suspense wrappers
+- 📋 **Form Validation Smells**: Detect uncontrolled inputs, missing validation
+- 🗃️ **State Management Analysis**: Redux/Zustand anti-patterns, selector issues
+- 🧪 **Testing Gap Detection**: Identify complex components likely needing tests
+- 🤖 **AI Refactoring Suggestions**: LLM-powered smart refactoring recommendations
 
 ### Detected Code Smells
 
@@ -38,7 +52,14 @@ A CLI tool that analyzes React projects and detects common code smells, providin
 | **Code Complexity** | Cyclomatic complexity, cognitive complexity, deep nesting |
 | **Import Issues** | Circular dependencies, barrel file imports, excessive imports |
 | **Unused Code** | Unused exports, dead imports |
+| **Custom Rules** | User-defined code quality rules |
+| **Server Components** | React 19 client/server boundary issues, async components |
 | **Framework-Specific** | Next.js, React Native, Node.js, TypeScript issues |
+| **Context API** | Context overuse, missing memoization, large context values |
+| **Error Boundaries** | Missing ErrorBoundary, Suspense without fallback |
+| **Form Validation** | Uncontrolled forms, missing validation, controlled inputs without onChange |
+| **State Management** | Redux selector anti-patterns, derived state issues, state sync problems |
+| **Testing Gaps** | Complex untestable components, side-effect heavy code, tight coupling |
 
 ## Installation
 
@@ -124,6 +145,20 @@ Or create manually:
 | `--discord <url>` | Discord webhook URL for notifications | - |
 | `--webhook <url>` | Generic webhook URL for notifications | - |
 | `--webhook-threshold <number>` | Only notify if smells exceed threshold | `10` |
+| `--graph` | Generate dependency graph visualization | `false` |
+| `--graph-format <format>` | Graph output format: svg, html | `html` |
+| `--bundle` | Analyze bundle size impact per component | `false` |
+| `--rules <file>` | Custom rules configuration file | - |
+| `--fix-interactive` | Interactive fix mode: review fixes one by one | `false` |
+| `--fix-preview` | Preview fixable issues without applying | `false` |
+| `--pr-comment` | Generate PR comment (for GitHub Actions) | `false` |
+| `--budget` | Check against performance budget | `false` |
+| `--budget-config <file>` | Path to budget config file | `.smellbudget.json` |
+| `--docs` | Generate component documentation | `false` |
+| `--docs-format <format>` | Documentation format: markdown, html, json | `markdown` |
+| `--ai` | Enable AI-powered refactoring suggestions | `false` |
+| `--ai-key <key>` | API key for AI provider | - |
+| `--ai-model <model>` | AI model to use (gpt-4, claude-3-sonnet, etc.) | `gpt-4` |
 
 ### Auto-Fix
 
@@ -252,6 +287,285 @@ react-smell ./src \
   --ci
 ```
 
+### Dependency Graph Visualization
+
+Generate interactive dependency graphs showing component and file relationships:
+
+```bash
+# Generate dependency graph
+react-smell ./src --graph
+
+# Auto-generates: dependency-graph.html
+```
+
+**Features:**
+- Visual representation of file imports and dependencies
+- Circular dependency detection and highlighting
+- Force-directed layout for clarity
+- Exportable SVG or HTML format
+- Legend showing node types and relationships
+
+**Example Usage:**
+```bash
+# Generate and analyze all at once
+react-smell ./src --graph --bundle --baseline --ci
+```
+
+### Bundle Size Impact Analysis
+
+Estimate per-component bundle size impact:
+
+```bash
+# Analyze bundle impact
+react-smell ./src --bundle
+
+# Auto-generates: bundle-analysis.html
+```
+
+**Features:**
+- Estimated size per component (in bytes)
+- Line of code (LOC) analysis
+- Dependency complexity scoring
+- Impact level classification (low/medium/high/critical)
+- Recommendations for optimization
+- Breakdown of largest components
+
+**Impact Levels:**
+- 🟢 **Low**: <2KB, <150 LOC, low complexity
+- 🟡 **Medium**: 2-5KB, 150-300 LOC, medium complexity
+- 🟠 **High**: 5-10KB, 300-500 LOC, high complexity
+- 🔴 **Critical**: >10KB, >500 LOC, very complex
+
+### Custom Rules Engine
+
+Define project-specific code quality rules:
+
+**Configuration File (.smellrc-rules.json):**
+```json
+{
+  "rules": [
+    {
+      "name": "no-hardcoded-strings",
+      "description": "Prevent hardcoded strings (use i18n)",
+      "severity": "warning",
+      "pattern": "\"(hello|world|test)\"",
+      "patternType": "regex",
+      "enabled": true
+    },
+    {
+      "name": "require-display-name",
+      "description": "All components must have displayName",
+      "severity": "info",
+      "pattern": "displayName",
+      "patternType": "text",
+      "enabled": true
+    }
+  ]
+}
+```
+
+**CLI Usage:**
+```bash
+# Use custom rules
+react-smell ./src --rules .smellrc-rules.json
+
+# Combined with other features
+react-smell ./src --rules .smellrc-rules.json --format json --ci
+```
+
+**Rule Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string | Unique rule identifier |
+| `description` | string | Human-readable explanation |
+| `severity` | string | error, warning, or info |
+| `pattern` | string | Regex or text pattern |
+| `patternType` | string | regex, text, or ast |
+| `enabled` | boolean | Enable/disable rule |
+
+**Pattern Types:**
+
+- **regex**: Regular expression matching (e.g., `"hardcoded.*string"`)
+- **text**: Simple string matching
+- **ast**: Babel AST node type matching (e.g., `FunctionExpression`)
+
+**Real-World Examples:**
+
+```json
+{
+  "rules": [
+    {
+      "name": "no-console-in-production",
+      "pattern": "console\\.(log|warn|info)",
+      "patternType": "regex",
+      "severity": "error"
+    },
+    {
+      "name": "enforce-prop-types",
+      "pattern": "PropTypes",
+      "patternType": "text",
+      "severity": "warning",
+      "message": "Consider using TypeScript instead of PropTypes"
+    },
+    {
+      "name": "limit-nesting",
+      "description": "Flag deeply nested JSX",
+      "pattern": "<.*>.*<.*>.*<.*>.*<.*>.*<",
+      "patternType": "regex",
+      "severity": "info"
+    }
+  ]
+}
+```
+
+### Interactive Fix Mode
+
+Review and apply fixes one by one with diff preview:
+
+```bash
+# Interactive mode - review each fix
+react-smell ./src --fix-interactive
+
+# Preview fixable issues without applying
+react-smell ./src --fix-preview
+```
+
+**Output:**
+```
+🔧 Interactive Fix Mode
+Found 5 fixable issue(s). Review each one:
+
+Commands: [y]es, [n]o, [a]ll, [q]uit
+
+────────────────────────────────────────────────────────────────
+src/utils/helper.ts:15
+  debug-statement: console.log found
+  Fix: Remove console.log/debugger statements
+
+  - console.log('debug:', value);
+  + (line removed)
+
+Apply this fix? [y/n/a/q]: y
+  ✓ Applied
+```
+
+### GitHub PR Comments
+
+Auto-comment code smell analysis on pull requests:
+
+```bash
+# Generate PR comment (outputs markdown)
+react-smell ./src --pr-comment
+
+# In GitHub Actions (auto-posts to PR)
+react-smell ./src --pr-comment --ci
+```
+
+**GitHub Actions workflow:**
+```yaml
+- name: Analyze Code
+  run: npx react-smell ./src --pr-comment --ci
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Performance Budget
+
+Set thresholds for code quality and enforce in CI/CD:
+
+```bash
+# Create budget config
+react-smell init-budget
+
+# Check against budget
+react-smell ./src --budget
+
+# With custom config
+react-smell ./src --budget --budget-config my-budget.json
+```
+
+**Budget config (`.smellbudget.json`):**
+```json
+{
+  "maxErrors": 0,
+  "maxWarnings": 10,
+  "minScore": 70,
+  "minGrade": "C",
+  "maxSmellsPerFile": 5,
+  "maxByType": {
+    "useEffect-overuse": 3,
+    "prop-drilling": 5
+  }
+}
+```
+
+**Output:**
+```
+✗ Performance budget check failed
+
+Violations:
+  ✗ Errors (2) exceeds budget (0)
+  ⚠ Warnings (15) exceeds budget (10)
+
+Checks: 3 passed, 2 failed
+```
+
+### Component Documentation
+
+Auto-generate documentation from component analysis:
+
+```bash
+# Generate markdown docs
+react-smell docs ./src
+
+# Generate HTML docs
+react-smell docs ./src -f html
+
+# Output to specific directory
+react-smell docs ./src -f html -o ./docs
+```
+
+**Output (COMPONENTS.md):**
+```markdown
+# Component Documentation
+
+## Summary
+| Metric | Value |
+|--------|-------|
+| Total Components | 25 |
+| Technical Debt Grade | B |
+
+## Components
+
+#### Button
+📄 `components/Button.tsx`
+
+| Metric | Value |
+|--------|-------|
+| Lines | 45 |
+| Complexity | 🟢 Low |
+| Maintainability | 🟢 Good |
+
+**Hooks:** useState (2), useCallback (1)
+```
+
+### React 19 Server Components
+
+Detect Server/Client component boundary issues:
+
+```bash
+# Enabled by default for app/ directory components
+react-smell ./src
+```
+
+**Detected issues:**
+- `server-component-hooks`: Using useState/useEffect in Server Components
+- `server-component-events`: Using onClick/onChange in Server Components
+- `server-component-browser-api`: Using window/document in Server Components
+- `async-client-component`: Async function in 'use client' component
+- `mixed-directives`: Both 'use client' and 'use server' in same file
+
 ## Example Output
 
 ```
@@ -281,9 +595,23 @@ react-smell ./src \
 ## Programmatic API
 
 ```typescript
-import { analyzeProject, reportResults } from 'react-code-smell-detector';
-import { initializeBaseline, recordBaseline, getTrendAnalysis, formatTrendReport } from 'react-code-smell-detector';
-import { sendWebhookNotification, getWebhookConfig } from 'react-code-smell-detector';
+import { 
+  analyzeProject, 
+  reportResults,
+  // Interactive fixing
+  runInteractiveFix,
+  previewFixes,
+  // PR Comments
+  generatePRComment,
+  postPRComment,
+  // Performance Budget
+  loadBudget,
+  checkBudget,
+  formatBudgetReport,
+  // Documentation
+  generateComponentDocs,
+  writeComponentDocs,
+} from 'react-code-smell-detector';
 
 const result = await analyzeProject({
   rootDir: './src',
@@ -291,32 +619,29 @@ const result = await analyzeProject({
     maxUseEffectsPerComponent: 3,
     maxComponentLines: 300,
     checkUnusedCode: true,
-    baselineEnabled: true,
+    checkServerComponents: true, // React 19
   },
 });
 
 console.log(`Grade: ${result.debtScore.grade}`);
 console.log(`Total issues: ${result.summary.totalSmells}`);
 
-// Track baseline
-initializeBaseline('./src');
-recordBaseline('./src', result.files.flatMap(f => f.smells));
-const trend = getTrendAnalysis('./src');
-console.log(formatTrendReport('./src'));
-
-// Send notification
-const webhookConfig = getWebhookConfig(
-  process.env.REACT_SMELL_SLACK_WEBHOOK,
-  process.env.REACT_SMELL_DISCORD_WEBHOOK
-);
-if (webhookConfig) {
-  await sendWebhookNotification(
-    webhookConfig,
-    result.files.flatMap(f => f.smells),
-    'my-project'
-  );
+// Check against performance budget
+const budget = await loadBudget();
+const budgetResult = checkBudget(result, budget);
+if (!budgetResult.passed) {
+  console.log(formatBudgetReport(budgetResult));
 }
 
+// Generate documentation
+const docsPath = await writeComponentDocs(result, './src', {
+  format: 'markdown',
+  includeSmells: true,
+});
+
+// Generate PR comment
+const prComment = generatePRComment(result, './src');
+
 // Or use the reporter
 const report = reportResults(result, {
   format: 'markdown',

package/dist/__tests__/parser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parser.test.d.ts.map

package/dist/__tests__/parser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/parser.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/parser.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { parseCode } from '../parser/index.js';
+describe('Parser', () => {
+    it('should parse a simple React component', () => {
+        const code = `
+      function Hello({ name }) {
+        return <div>Hello {name}</div>;
+      }
+    `;
+        const result = parseCode(code);
+        expect(result.components).toHaveLength(1);
+        expect(result.components[0].name).toBe('Hello');
+    });
+    it('should detect useState hook', () => {
+        const code = `
+      function Counter() {
+        const [count, setCount] = useState(0);
+        return <button onClick={() => setCount(count + 1)}>{count}</button>;
+      }
+    `;
+        const result = parseCode(code);
+        expect(result.components).toHaveLength(1);
+        expect(result.components[0].hooks.useState).toHaveLength(1);
+    });
+    it('should detect useEffect hook', () => {
+        const code = `
+      function Timer() {
+        const [time, setTime] = useState(0);
+        useEffect(() => {
+          const id = setInterval(() => setTime(t => t + 1), 1000);
+          return () => clearInterval(id);
+        }, []);
+        return <span>{time}</span>;
+      }
+    `;
+        const result = parseCode(code);
+        expect(result.components).toHaveLength(1);
+        expect(result.components[0].hooks.useEffect).toHaveLength(1);
+    });
+    it('should extract component props', () => {
+        const code = `
+      function Card({ title, description, onClick }) {
+        return (
+          <div onClick={onClick}>
+            <h1>{title}</h1>
+            <p>{description}</p>
+          </div>
+        );
+      }
+    `;
+        const result = parseCode(code);
+        expect(result.components[0].props).toContain('title');
+        expect(result.components[0].props).toContain('description');
+        expect(result.components[0].props).toContain('onClick');
+    });
+});

package/dist/__tests__/performanceBudget.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=performanceBudget.test.d.ts.map

package/dist/__tests__/performanceBudget.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performanceBudget.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/performanceBudget.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/performanceBudget.test.js

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { checkBudget } from '../performanceBudget.js';
+describe('Performance Budget', () => {
+    const createMockResult = (overrides = {}) => ({
+        files: [],
+        summary: {
+            totalFiles: 5,
+            totalComponents: 10,
+            totalSmells: 3,
+            smellsByType: Object.fromEntries([
+                'useEffect-overuse', 'prop-drilling', 'large-component', 'unmemoized-calculation',
+                'missing-dependency', 'state-in-loop', 'inline-function-prop', 'deep-nesting',
+                'missing-key', 'hooks-rules-violation', 'dependency-array-issue', 'nested-ternary',
+                'dead-code', 'magic-value', 'debug-statement', 'todo-comment', 'security-xss',
+                'security-eval', 'security-secrets', 'a11y-missing-alt', 'a11y-missing-label',
+                'a11y-interactive-role', 'a11y-keyboard', 'a11y-semantic',
+                'nextjs-client-server-boundary', 'nextjs-missing-metadata', 'nextjs-image-unoptimized',
+                'nextjs-router-misuse', 'rn-inline-style', 'rn-missing-accessibility', 'rn-performance-issue',
+                'nodejs-callback-hell', 'nodejs-unhandled-promise', 'nodejs-sync-io', 'nodejs-missing-error-handling',
+                'js-var-usage', 'js-loose-equality', 'js-implicit-coercion', 'js-global-pollution',
+                'ts-any-usage', 'ts-missing-return-type', 'ts-non-null-assertion', 'ts-type-assertion',
+                'high-cyclomatic-complexity', 'high-cognitive-complexity',
+                'memory-leak-event-listener', 'memory-leak-subscription', 'memory-leak-timer', 'memory-leak-async',
+                'circular-dependency', 'barrel-file-import', 'namespace-import', 'excessive-imports',
+                'unused-export', 'dead-import',
+                'server-component-hooks', 'server-component-events', 'server-component-browser-api',
+                'async-client-component', 'mixed-directives', 'custom-rule'
+            ].map(key => [key, 0])),
+            smellsBySeverity: { error: 0, warning: 2, info: 1 },
+        },
+        debtScore: {
+            score: 85,
+            grade: 'B',
+            breakdown: {
+                useEffectScore: 90,
+                propDrillingScore: 80,
+                componentSizeScore: 85,
+                memoizationScore: 85,
+            },
+            estimatedRefactorTime: '< 30 minutes',
+        },
+        ...overrides,
+    });
+    it('should pass when all budgets are met', () => {
+        const budget = {
+            maxTotalSmells: 10,
+            maxErrors: 5,
+            minGrade: 'C',
+        };
+        const result = checkBudget(createMockResult(), budget);
+        expect(result.passed).toBe(true);
+        expect(result.violations).toHaveLength(0);
+    });
+    it('should fail when total smells exceed budget', () => {
+        const budget = {
+            maxTotalSmells: 2,
+        };
+        const result = checkBudget(createMockResult(), budget);
+        expect(result.passed).toBe(false);
+        expect(result.violations).toHaveLength(1);
+        expect(result.violations[0].rule).toBe('maxTotalSmells');
+    });
+    it('should fail when errors exceed budget', () => {
+        const budget = {
+            maxErrors: 0,
+        };
+        const mockResult = createMockResult();
+        mockResult.summary.smellsBySeverity.error = 2;
+        const result = checkBudget(mockResult, budget);
+        expect(result.passed).toBe(false);
+        expect(result.violations[0].rule).toBe('maxErrors');
+    });
+    it('should fail when grade is below minimum', () => {
+        const budget = {
+            minGrade: 'A',
+        };
+        const result = checkBudget(createMockResult(), budget);
+        expect(result.passed).toBe(false);
+        expect(result.violations[0].rule).toBe('minGrade');
+    });
+    it('should allow warnings as non-blocking violations', () => {
+        const budget = {
+            maxWarnings: 1,
+        };
+        const result = checkBudget(createMockResult(), budget);
+        // Should have violation but still pass (warnings are non-blocking)
+        expect(result.violations).toHaveLength(1);
+        expect(result.violations[0].severity).toBe('warning');
+        expect(result.passed).toBe(true);
+    });
+});

package/dist/__tests__/prComments.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prComments.test.d.ts.map

package/dist/__tests__/prComments.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prComments.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/prComments.test.ts"],"names":[],"mappings":""}