spaghetti-slicer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neerajram30
+
+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,259 @@
+# 🍝 spaghetti-slicer
+
+[![npm version](https://img.shields.io/npm/v/spaghetti-slicer.svg?style=flat-square)](https://www.npmjs.com/package/spaghetti-slicer)
+[![license](https://img.shields.io/npm/l/spaghetti-slicer.svg?style=flat-square)](https://github.com/neerajram30/spaghetti-slicer/blob/main/LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+
+A highly opinionated frontend best practices auditor for React & TypeScript codebases. It is designed to automatically scan, analyze, and slice away "spaghetti code" before it reaches production—especially code generated by AI coding assistants like Cursor, v0, Bolt, and Lovable.
+
+---
+
+## ✨ Features
+
+- ⚡ **Zero Config**: Works out of the box with zero setup. Point it at your code and let it slice.
+- 📊 **Quantifiable Scores**: Generates a weighted score out of 100 across 5 core categories, grading your repository from **Excellent** to **Poor**.
+- 🛠️ **Built for AI-Generated Code**: Catches common anti-patterns that LLMs frequently introduce (such as state bloat, inline fetching, and missing dimensions).
+- 🤖 **CI/CD Friendly**: Fail pipelines automatically with `--min-score` when code quality falls below your team's threshold.
+- 📋 **Flexible Output**: Print beautiful console summaries with `ora` spinners and `boxen` layouts, or stream raw JSON to stdout using `--json`.
+
+---
+
+## 🚀 Installation
+
+### Run instantly with `npx` (No Install)
+```bash
+npx spaghetti-slicer ./src
+```
+
+### Install Globally
+```bash
+npm install -g spaghetti-slicer
+
+# Run audit
+spaghetti-slicer ./src
+```
+
+---
+
+## 🛠️ Usage & CLI Flags
+
+```bash
+# Audit a whole folder or specific files
+spaghetti-slicer ./src
+spaghetti-slicer ./src/components/Button.tsx
+
+# Exit with code 1 if score drops below 80 (perfect for CI checks)
+spaghetti-slicer ./src --min-score=80
+
+# Filter rules to run only a specific category
+spaghetti-slicer ./src --rule=architecture
+spaghetti-slicer ./src --rule=react
+
+# Print clean JSON for external scripting
+spaghetti-slicer ./src --json
+
+# Show interactive lint/eslint autofix recommendations
+spaghetti-slicer ./src --fix
+```
+
+---
+
+## 🔍 Code Quality Rules
+
+`spaghetti-slicer` runs rules in several core categories:
+
+### 🏛️ Architecture (Weight: 25%)
+
+| Rule ID | Severity | Description |
+|:---|:---:|:---|
+| `component-length` | 🔴 Critical | Components exceeding 200 lines should be broken up |
+| `business-logic-in-jsx` | 🟡 Warning | Inline data operations (`.filter()`, `.reduce()`, `.sort()`) in JSX |
+| `direct-fetch-in-component` | 🔴 Critical | Making raw HTTP fetch/axios requests directly inside component bodies |
+| `state-bloat` | 🟡 Warning | Defining more than 5 `useState` hooks in a single component |
+| `hardcoded-secrets-endpoints` | 🔴 Critical | Hardcoded raw URL strings or potential API credentials/keys |
+
+### ⚛️ React (Weight: 20%)
+
+| Rule ID | Severity | Description |
+|:---|:---:|:---|
+| `index-as-key` | 🔴 Critical | Array iteration index used as the React `key` prop |
+| `missing-error-boundary` | 🟡 Warning | Codebase lacks any React Error Boundary components |
+| `no-sub-renders` | 🟡 Warning | Helper render functions (e.g. `renderHeader()`) nested in components |
+| `fat-controller` | 🟡 Warning | Non-JSX javascript logic exceeds 75% of a component's total line length |
+
+### ⚡ Performance (Weight: 15%)
+
+| Rule ID | Severity | Description |
+|:---|:---:|:---|
+| `image-missing-dimensions` | 🟡 Warning | `<img>` or `<Image>` tags missing `width` or `height` attributes (causes CLS) |
+
+---
+
+## 💡 Code Patterns: Bad vs. Good
+
+Here's how `spaghetti-slicer` helps you clean up common code smells:
+
+### 1. Direct Fetch in Component (`direct-fetch-in-component`)
+* ❌ **Bad:** Making raw API calls inside a render or useEffect lifecycle.
+  ```tsx
+  export function UserProfile() {
+    useEffect(() => {
+      fetch('/api/user/profile').then(res => res.json()).then(data => {...});
+    }, []);
+    return <div>User Profile</div>;
+  }
+  ```
+*  **Good:** Extract to a custom hook or API service layer.
+  ```tsx
+  import { useUserProfile } from '../hooks/useUserProfile';
+  
+  export function UserProfile() {
+    const { profile, loading } = useUserProfile();
+    return <div>User Profile</div>;
+  }
+  ```
+
+### 2. State Bloat (`state-bloat`)
+* ❌ **Bad:** Managing component states using too many individual hooks.
+  ```tsx
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [age, setAge] = useState(0);
+  const [address, setAddress] = useState('');
+  const [phone, setPhone] = useState('');
+  const [company, setCompany] = useState(''); // ⚠️ State Bloat Triggered (6 hooks)
+  ```
+*  **Good:** Merge related states or delegate to `useReducer` / state containers.
+  ```tsx
+  const [formData, setFormData] = useState({
+    name: '', email: '', age: 0, address: '', phone: '', company: ''
+  });
+  ```
+
+### 3. Nested Helper Renders (`no-sub-renders`)
+* ❌ **Bad:** Defining sub-rendering helper functions inside the main component body.
+  ```tsx
+  export function ProductCard({ title, price }) {
+    const renderBadge = () => <span className="badge">New</span>; // ⚠️ Defined inside Card
+    return (
+      <div>
+        <h3>{title}</h3>
+        {renderBadge()}
+      </div>
+    );
+  }
+  ```
+*  **Good:** Extract to its own component.
+  ```tsx
+  function Badge() {
+    return <span className="badge">New</span>;
+  }
+
+  export function ProductCard({ title, price }) {
+    return (
+      <div>
+        <h3>{title}</h3>
+        <Badge />
+      </div>
+    );
+  }
+  ```
+
+---
+
+## 📈 Scoring System
+
+Your project starts with a score of **100** for each category. Points are deducted per violation:
+* 🔴 **Critical Violation**: `-10 points`
+* 🟡 **Warning Violation**: `-5 points`
+* 🔵 **Info Violation**: `-2 points`
+
+A total score is calculated using the weighted averages of all categories. Your repository is then assigned a Grade:
+
+| Score | Grade | Description |
+|:---:|:---:|:---|
+| **90 – 100** | ✅ **Excellent** | Clean codebase, minimal code smells |
+| **75 – 89** | ✅ **Good** | Solid structure, minor refactoring recommended |
+| **60 – 74** | ⚠️ **Needs Work** | Code smells present, potential architectural issues |
+| **< 60** | ❌ **Poor** | High risk of bugs and difficult maintenance |
+
+---
+
+## 🤖 GitHub Actions CI/CD Integration
+
+Catch regressions automatically on every Pull Request. Add this workflow as `.github/workflows/spaghetti-slicer.yml`:
+
+```yaml
+name: Code Quality Audit
+on: [pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Build Project
+        run: npm run build
+
+      - name: Run Spaghetti Slicer
+        # Exit and fail the action if quality score falls below 80%
+        run: npx spaghetti-slicer ./src --min-score=80
+```
+
+---
+
+## ⚙️ Local Development & Contributing
+
+We welcome community contributions to add more rules or improve CLI performance!
+
+### Prerequisites & Setup
+1. Fork and clone the repository.
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+### Running Tests
+We use `vitest` for fast static-analysis rule validation:
+```bash
+# Run tests once
+npm run test:run
+
+# Run tests in watch mode
+npm run test
+```
+
+### Linking the CLI locally
+Test your local changes against any separate project directory on your computer:
+```bash
+# 1. From the spaghetti-slicer repository directory
+npm run build
+npm link
+
+# 2. Run globally linked CLI in another project directory
+spaghetti-slicer /path/to/other-project/src
+```
+
+### Adding a New Rule
+1. Create your rule under `src/rules/<category>/<rule-name>.ts` implementing the `Rule` interface.
+2. Register the rule in `src/rules/index.ts`.
+3. Write test cases covering pass and fail fixtures under `tests/rules/<category>/<rule-name>.test.ts`.
+4. Run `npm run test:run` to confirm everything works!
+
+---
+
+## 📄 License
+
+This project is open-source and licensed under the [MIT License](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node