react-anti-pattern-sniffer 0.1.0

package/.snifferrc.json

@@ -0,0 +1,29 @@
+{
+  "include": ["**/*.{jsx,tsx}"],
+  "exclude": ["node_modules", "dist", "build", "**/*.test.*", "**/*.spec.*"],
+  "parallel": true,
+  "maxWorkers": 4,
+  "timeoutMs": 30000,
+  "outputFormat": "markdown",
+  "outputPath": null,
+  "sniffers": {
+    "prop-explosion": {
+      "enabled": true,
+      "threshold": 7,
+      "severity": "warning"
+    },
+    "god-hook": {
+      "enabled": true,
+      "maxUseState": 4,
+      "maxUseEffect": 3,
+      "maxTotalHooks": 10,
+      "severity": "warning"
+    },
+    "prop-drilling": {
+      "enabled": true,
+      "severity": "warning",
+      "whitelistedProps": ["className", "style", "children", "key", "ref", "id", "data-testid"]
+    }
+  },
+  "plugins": []
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-anti-pattern-sniffer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# react-anti-pattern-sniffer
+
+Zero-dependency CLI tool that detects React anti-patterns in your codebase using regex-based heuristics and parallel worker threads.
+
+## Features
+
+- **Zero runtime dependencies** — uses only Node.js built-ins
+- **Three built-in sniffers**: prop explosion, god hook, prop drilling
+- **Interactive TUI** — browse results, copy as AI prompt, ignore components
+- **Batch mode** — focus on the first N issues at a time
+- **Parallel execution** via `worker_threads` for fast analysis
+- **Plugin system** — register custom sniffers with security validation
+- **Markdown & JSON output** — human-readable reports or structured data
+- **`.snifferignore`** — persistently ignore specific components
+- **Git hook friendly** — exit codes for CI/CD and husky integration
+
+## Installation
+
+```bash
+npm install --save-dev react-anti-pattern-sniffer
+```
+
+## Quick Start
+
+```bash
+# Scan current directory
+npx react-sniff
+
+# Short alias
+npx ras
+
+# Interactive mode — browse results in a TUI
+ras -i
+
+# Batch mode — show only the first 10 issues
+ras -b 10
+
+# Interactive + batch — browse first 20 issues in TUI
+ras -i -b 20
+
+# Output JSON report
+react-sniff --format json --output report.json
+```
+
+## CLI Options
+
+```
+Usage: react-sniff [options] [dir]
+
+Options:
+  -d, --dir <path>         Target directory (default: cwd)
+  -c, --config <path>      Config file path (default: .snifferrc.json)
+  -s, --sniffers <list>    Comma-separated sniffers to run
+  -f, --format <type>      Output format: markdown | json
+  -o, --output <path>      Write report to file
+  -w, --workers <n>        Worker thread count (default: 4)
+  -i, --interactive        Launch interactive TUI to browse results
+  -b, --batch <n>          Limit output to the first N issues (default: 10)
+      --parallel           Enable parallel execution (default)
+      --no-parallel        Run sequentially
+      --verbose            Debug output
+  -q, --quiet              Exit code only, no output
+  -h, --help               Show help
+  -v, --version            Show version
+```
+
+## Interactive Mode
+
+Launch with `ras -i` to get a keyboard-driven TUI for browsing results, organized by code smell:
+
+```
+  React Anti-Pattern Sniffer  │  12/42 issues shown  •  85 files scanned
+
+  ▸ ▼ Prop Explosion (6 issues)
+      ● src/components/UserProfile.tsx:15 UserProfile — has 10 props
+      ● src/components/Dashboard.tsx:42 Dashboard — has 8 props
+      ● src/pages/Settings.tsx:23 SettingsForm — has 9 props
+
+    ▶ God Hook (3 issues)
+
+    ▶ Prop Drilling (3 issues)
+
+  [c]opy as prompt  [a]ll as md  [x] ignore  [f]ilter  [d]etails  [q]uit
+  ↑/↓ navigate  ←/→ or enter collapse/expand  tab next group
+```
+
+### Keyboard Controls
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` or `j`/`k` | Navigate between items |
+| `Enter`/`→`/`←` | Expand/collapse smell groups |
+| `Tab` | Jump to next group |
+| `d` | Toggle details (show suggestion + metadata) |
+| `c` | Copy current issue as AI prompt (markdown to clipboard) |
+| `a` | Copy all visible issues as markdown |
+| `x` | Ignore component (adds to `.snifferignore`) |
+| `f` | Cycle filter by smell type |
+| `p` | Print current issue markdown (clipboard fallback) |
+| `q` | Quit |
+
+## Batch Mode
+
+Use `-b` to limit output to the first N issues. Works in both interactive and non-interactive mode:
+
+```bash
+# Show first 5 issues as markdown
+ras -b 5
+
+# Browse first 20 issues in TUI
+ras -i -b 20
+
+# Only god-hook issues, first 3
+ras -b 3 -s god-hook
+```
+
+## Sniffers
+
+### Prop Explosion
+
+Detects components with too many props, suggesting decomposition.
+
+```jsx
+// ⚠ Flagged: 10 props exceeds threshold of 7
+const UserProfile = ({ firstName, lastName, email, phone, avatar, address, role, permissions, isActive, onUpdate }) => { ... }
+```
+
+**Fix:** Group related props into objects, use Context, or split the component.
+
+### God Hook
+
+Detects custom hooks with excessive state, effects, or responsibilities.
+
+```jsx
+// ⚠ Flagged: 6 useState, 4 useEffect
+function useUserDashboard(userId) {
+  const [user, setUser] = useState(null);
+  const [posts, setPosts] = useState([]);
+  // ...6 more useState, 4 useEffect
+}
+```
+
+**Fix:** Split into focused sub-hooks (`useUser`, `usePosts`, `useNotifications`).
+
+### Prop Drilling
+
+Detects props that are received but only forwarded to children without local use.
+
+```jsx
+// ⚠ Flagged: theme, locale passed through without use
+const Wrapper = ({ theme, locale, children }) => (
+  <Header theme={theme} locale={locale} />
+);
+```
+
+**Fix:** Use React Context or component composition.
+
+## `.snifferignore`
+
+Create a `.snifferignore` file in your project root to persistently skip specific components or files. This file is automatically updated when you press `x` in interactive mode.
+
+```gitignore
+# Ignore a specific component for a specific sniffer
+src/components/UserProfile.tsx:UserProfile  # prop-explosion
+
+# Ignore all issues in a file
+src/legacy/OldDashboard.tsx
+
+# Ignore a hook
+src/hooks/useMonolith.ts:useMonolith  # god-hook
+```
+
+Format: `<file-path>:<ComponentName>  # <sniffer-name>`
+
+- `ComponentName` and `# sniffer-name` are optional
+- Lines starting with `#` are comments
+
+## Configuration
+
+Create `.snifferrc.json` in your project root:
+
+```json
+{
+  "include": ["**/*.{jsx,tsx}"],
+  "exclude": ["node_modules", "dist", "build", "**/*.test.*"],
+  "parallel": true,
+  "maxWorkers": 4,
+  "timeoutMs": 30000,
+  "outputFormat": "markdown",
+  "sniffers": {
+    "prop-explosion": {
+      "enabled": true,
+      "threshold": 7,
+      "severity": "warning"
+    },
+    "god-hook": {
+      "enabled": true,
+      "maxUseState": 4,
+      "maxUseEffect": 3,
+      "maxTotalHooks": 10,
+      "severity": "warning"
+    },
+    "prop-drilling": {
+      "enabled": true,
+      "severity": "warning",
+      "whitelistedProps": ["className", "style", "children", "key", "ref", "id"]
+    }
+  },
+  "plugins": []
+}
+```
+
+## Git Hooks (Husky)
+
+Add to `.husky/pre-commit`:
+
+```bash
+npx react-sniff --quiet
+```
+
+Exit codes:
+- `0` — no issues found
+- `1` — anti-patterns detected
+- `2` — configuration or runtime error
+
+## Custom Plugins
+
+Create a sniffer module:
+
+```js
+// my-sniffer.js
+module.exports = {
+  name: 'no-inline-styles',
+  description: 'Detects inline style objects in JSX',
+  meta: {
+    name: 'no-inline-styles',
+    description: 'Flags inline style={{}} usage',
+    category: 'custom',
+    severity: 'info',
+    defaultConfig: {},
+  },
+  detect(fileContent, filePath, config) {
+    const detections = [];
+    // Your detection logic here
+    // Return array of Detection objects:
+    // { snifferName, filePath, line, column, message, severity, suggestion }
+    return detections;
+  },
+};
+```
+
+Register in `.snifferrc.json`:
+
+```json
+{
+  "plugins": [
+    { "path": "./my-sniffer.js" }
+  ]
+}
+```
+
+### Plugin Security
+
+Plugins are validated before execution:
+1. **Schema check** — must export `name`, `description`, `meta`, `detect`
+2. **Security scan** — warns on `eval()`, `Function()`, `child_process`, etc.
+3. **Smoke test** — must return an array on empty input
+4. **Worker isolation** — runs in separate V8 isolate with memory limits
+5. **Timeout** — killed after `timeoutMs` (default 30s)
+
+## Programmatic API
+
+```js
+const { orchestrate } = require('react-anti-pattern-sniffer');
+
+const result = await orchestrate(config, targetDir);
+console.log(result.output);      // formatted report
+console.log(result.issueCount);  // number of issues
+console.log(result.fileCount);   // files scanned
+console.log(result.grouped);     // Map<string, SnifferResult[]>
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+
+## License
+
+MIT

package/bin/react-sniff.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../dist/src/cli/index.js');

package/dist/src/cli/arg-parser.d.ts

@@ -0,0 +1,10 @@
+export interface ParsedArgs {
+    flags: Record<string, string | boolean>;
+    positionals: string[];
+}
+/**
+ * Parse CLI arguments with zero dependencies.
+ * Supports: --key=value, --key value, --boolean, --no-x (negation), -short aliases
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+//# sourceMappingURL=arg-parser.d.ts.map

package/dist/src/cli/arg-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-parser.d.ts","sourceRoot":"","sources":["../../../src/cli/arg-parser.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAgBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAyDpD"}

package/dist/src/cli/arg-parser.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+const SHORT_ALIASES = {
+    '-c': '--config',
+    '-d': '--dir',
+    '-f': '--format',
+    '-o': '--output',
+    '-s': '--sniffers',
+    '-w': '--workers',
+    '-h': '--help',
+    '-v': '--version',
+    '-q': '--quiet',
+    '-i': '--interactive',
+    '-b': '--batch',
+};
+/**
+ * Parse CLI arguments with zero dependencies.
+ * Supports: --key=value, --key value, --boolean, --no-x (negation), -short aliases
+ */
+function parseArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    let i = 0;
+    while (i < argv.length) {
+        let token = argv[i];
+        // Expand short aliases
+        if (SHORT_ALIASES[token]) {
+            token = SHORT_ALIASES[token];
+        }
+        if (token.startsWith('--no-')) {
+            // Negation: --no-parallel => parallel = false
+            const key = token.substring(5);
+            flags[key] = false;
+            i++;
+        }
+        else if (token.startsWith('--')) {
+            const eqIndex = token.indexOf('=');
+            if (eqIndex !== -1) {
+                // --key=value
+                const key = token.substring(2, eqIndex);
+                const value = token.substring(eqIndex + 1);
+                flags[key] = value;
+                i++;
+            }
+            else {
+                const key = token.substring(2);
+                const next = argv[i + 1];
+                // If next token exists and doesn't start with -, it's the value
+                if (next !== undefined && !next.startsWith('-')) {
+                    flags[key] = next;
+                    i += 2;
+                }
+                else {
+                    // Boolean flag
+                    flags[key] = true;
+                    i++;
+                }
+            }
+        }
+        else if (token.startsWith('-') && token.length === 2) {
+            // Single-char flag not in aliases
+            const key = token.substring(1);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                flags[key] = next;
+                i += 2;
+            }
+            else {
+                flags[key] = true;
+                i++;
+            }
+        }
+        else {
+            positionals.push(token);
+            i++;
+        }
+    }
+    return { flags, positionals };
+}
+//# sourceMappingURL=arg-parser.js.map

package/dist/src/cli/arg-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-parser.js","sourceRoot":"","sources":["../../../src/cli/arg-parser.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/config-loader.d.ts

@@ -0,0 +1,11 @@
+import type { SnifferConfig } from '../sniffers/sniffer-interface.js';
+declare const DEFAULT_CONFIG: SnifferConfig;
+/**
+ * Load configuration by merging:
+ * 1. Built-in defaults
+ * 2. Config file (.snifferrc.json or --config path)
+ * 3. CLI flags
+ */
+export declare function loadConfig(flags: Record<string, string | boolean>): SnifferConfig;
+export { DEFAULT_CONFIG };
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/src/cli/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../../src/cli/config-loader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE,QAAA,MAAM,cAAc,EAAE,aAkBrB,CAAC;AAoDF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,aAAa,CA6EjF;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/src/cli/config-loader.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.loadConfig = loadConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const DEFAULT_CONFIG = {
+    include: ['**/*.{jsx,tsx}'],
+    exclude: ['node_modules', 'dist', 'build', '**/*.test.*', '**/*.spec.*'],
+    parallel: true,
+    maxWorkers: 4,
+    timeoutMs: 30000,
+    outputFormat: 'markdown',
+    outputPath: null,
+    sniffers: {
+        'prop-explosion': { enabled: true, threshold: 7, severity: 'warning' },
+        'god-hook': { enabled: true, maxUseState: 4, maxUseEffect: 3, maxTotalHooks: 10, severity: 'warning' },
+        'prop-drilling': {
+            enabled: true,
+            severity: 'warning',
+            whitelistedProps: ['className', 'style', 'children', 'key', 'ref', 'id', 'data-testid'],
+        },
+    },
+    plugins: [],
+};
+exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+/**
+ * Deep merge two objects. Source values override target values.
+ * Arrays are replaced, not merged.
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceVal = source[key];
+        const targetVal = target[key];
+        if (sourceVal !== null &&
+            typeof sourceVal === 'object' &&
+            !Array.isArray(sourceVal) &&
+            targetVal !== null &&
+            typeof targetVal === 'object' &&
+            !Array.isArray(targetVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+/**
+ * Find a config file by searching common names in the given directory.
+ */
+function findConfigFile(dir) {
+    const candidates = [
+        '.snifferrc.json',
+        '.snifferrc.js',
+        'sniffer.config.json',
+        'sniffer.config.js',
+    ];
+    for (const name of candidates) {
+        const fullPath = (0, node_path_1.join)(dir, name);
+        if ((0, node_fs_1.existsSync)(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+/**
+ * Load configuration by merging:
+ * 1. Built-in defaults
+ * 2. Config file (.snifferrc.json or --config path)
+ * 3. CLI flags
+ */
+function loadConfig(flags) {
+    let fileConfig = {};
+    // Determine config file path
+    const configPath = typeof flags.config === 'string'
+        ? (0, node_path_1.resolve)(flags.config)
+        : findConfigFile(process.cwd());
+    if (configPath) {
+        if (!(0, node_fs_1.existsSync)(configPath)) {
+            if (flags.config) {
+                throw new Error(`Config file not found: ${configPath}`);
+            }
+        }
+        else {
+            try {
+                const raw = (0, node_fs_1.readFileSync)(configPath, 'utf8');
+                fileConfig = JSON.parse(raw);
+            }
+            catch (e) {
+                throw new Error(`Failed to parse config file ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+    // Merge defaults + file config
+    const merged = deepMerge(DEFAULT_CONFIG, fileConfig);
+    // Apply CLI flag overrides
+    if (typeof flags.dir === 'string') {
+        // Dir is handled at orchestrator level, not in config
+    }
+    if (typeof flags.format === 'string') {
+        if (flags.format !== 'markdown' && flags.format !== 'json') {
+            throw new Error(`Invalid format "${flags.format}". Supported: markdown, json`);
+        }
+        merged.outputFormat = flags.format;
+    }
+    if (typeof flags.output === 'string') {
+        merged.outputPath = flags.output;
+    }
+    if (typeof flags.workers === 'string') {
+        const n = parseInt(flags.workers, 10);
+        if (isNaN(n) || n < 1) {
+            throw new Error(`Invalid workers count "${flags.workers}". Must be a positive integer.`);
+        }
+        merged.maxWorkers = n;
+    }
+    if (flags.parallel === false || flags.parallel === 'false') {
+        merged.parallel = false;
+    }
+    else if (flags.parallel === true || flags.parallel === 'true') {
+        merged.parallel = true;
+    }
+    if (typeof flags.sniffers === 'string') {
+        const requested = flags.sniffers.split(',').map(s => s.trim());
+        // Disable all, then enable only requested
+        for (const key of Object.keys(merged.sniffers)) {
+            merged.sniffers[key].enabled = false;
+        }
+        for (const name of requested) {
+            if (merged.sniffers[name]) {
+                merged.sniffers[name].enabled = true;
+            }
+            else {
+                throw new Error(`Unknown sniffer "${name}". Available: ${Object.keys(merged.sniffers).join(', ')}`);
+            }
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/src/cli/config-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../../src/cli/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/help.d.ts

@@ -0,0 +1,3 @@
+export declare function printHelp(): void;
+export declare function printVersion(): void;
+//# sourceMappingURL=help.d.ts.map

package/dist/src/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/help.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,IAAI,IAAI,CA0ChC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAQnC"}

package/dist/src/cli/help.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printHelp = printHelp;
+exports.printVersion = printVersion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function printHelp() {
+    const help = `
+Usage: react-sniff [options] [dir]
+
+Detect React anti-patterns in your codebase.
+
+Options:
+  -d, --dir <path>         Target directory to scan (default: cwd)
+  -c, --config <path>      Path to config file (default: .snifferrc.json)
+  -s, --sniffers <list>    Comma-separated list of sniffers to run
+  -f, --format <type>      Output format: markdown | json (default: markdown)
+  -o, --output <path>      Write report to file instead of stdout
+  -w, --workers <n>        Number of worker threads (default: 4)
+  -i, --interactive        Launch interactive TUI to browse results
+  -b, --batch <n>          Show first N issues in interactive mode (default: 10)
+      --parallel           Enable parallel execution (default: true)
+      --no-parallel         Disable parallel execution
+      --verbose            Show debug output
+  -q, --quiet              Suppress all output (exit code only)
+  -h, --help               Show this help message
+  -v, --version            Show version number
+
+Examples:
+  react-sniff                              Scan current directory
+  react-sniff src/                         Scan specific directory
+  ras -i                                   Interactive mode
+  ras -i -b 20                             Interactive, show first 20 issues
+  react-sniff --sniffers prop-explosion    Run only prop explosion sniffer
+  react-sniff --format json -o report.json Output JSON report to file
+  ras --no-parallel --verbose              Run sequentially with debug output
+
+Sniffers:
+  prop-explosion   Detects components with too many props
+  god-hook         Detects custom hooks that do too much
+  prop-drilling    Detects props passed through without being used
+
+Configuration:
+  Create a .snifferrc.json in your project root to customize thresholds.
+  See https://github.com/your-repo/react-anti-pattern-sniffer for details.
+`.trim();
+    console.log(help);
+}
+function printVersion() {
+    try {
+        const pkgPath = (0, node_path_1.join)(__dirname, '..', '..', '..', 'package.json');
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, 'utf8'));
+        console.log(`react-anti-pattern-sniffer v${pkg.version}`);
+    }
+    catch {
+        console.log('react-anti-pattern-sniffer (unknown version)');
+    }
+}
+//# sourceMappingURL=help.js.map