vibertest 0.1.0 → 0.1.2

package/README.md

@@ -12,418 +12,103 @@
 
 **Your AI writes code. ViberTest makes sure it doesn't suck.**
 
-*Got sick of vibecoders' mess, so I vibecoded this.*
+Static analyzer for JavaScript & TypeScript that detects quality issues commonly produced by AI-assisted development.
 
-A CLI tool + Web Dashboard that analyzes JavaScript/TypeScript projects to detect quality issues commonly produced by AI-assisted development (vibecoding).
-
-**[Full Documentation →](https://vibertest.chyste.dev/docs)**
-
-[Getting Started](#getting-started) · [24 Rules](#the-24-rules) · [Grading System](#grading-system) · [Dashboard](#web-dashboard) · [Configuration](#configuration)
+24 rules · Zero config · One command
 
 </div>
 
 ---
 
-## The Problem
-
-AI coding tools (Cursor, Copilot, v0, Bolt) generate code that **works** but is often:
-
-- Copy-pasted across files with no abstraction
-- Missing error handling, tests, and proper architecture
-- Full of `console.log`, generic variable names, and TODO comments
-- Using outdated patterns (`var`, class components, callback hell)
-- Dumping everything into god files with circular dependencies
-
-**ViberTest catches all of this.** It scans your project, scores it 0-100, and tells you exactly what to fix.
-
-## Getting Started
-
-### Prerequisites
-
-- **Node.js** >= 20.0.0
-- **pnpm** >= 10.x
-
-### Installation
+## Quick Start
 
 ```bash
-# Clone the repository
-git clone https://github.com/Chyste/vibertest.git
-cd vibertest
-
-# Install dependencies
-pnpm install
-
-# Build all packages
-pnpm run build
-
-# Link the CLI globally
-cd packages/cli
-pnpm link --global
+npm i -g vibertest
+vibertest scan .
 ```
 
-### Run Your First Scan
+Or run without installing:
 
 ```bash
-# Scan the current directory
-vibertest scan .
+npx vibertest scan .
+```
 
-# Scan a specific project
-vibertest scan ~/my-project
+## Usage
 
-# Export results as JSON
+```bash
+# JSON output
 vibertest scan . --format json --output report.json
 
-# Run only specific rules
-vibertest scan . --rules oversized-files,dead-code,ai-smell
+# Specific rules only
+vibertest scan . --rules hardcoded-secrets,dead-code,ai-smell
 
-# Silent mode (no terminal output, just JSON)
-vibertest scan . --format json --silent
-```
-
-### Initialize Config
+# Silent mode (no terminal output, just the report)
+vibertest scan . --format json --silent --output report.json
 
-```bash
-# Create a .vibertestrc.json in your project
+# Initialize config
 vibertest init
 ```
 
----
-
-## The 24 Rules
-
-ViberTest analyzes your codebase with **24 rules** organized by what they detect. Each rule is specifically designed to catch patterns that AI tools produce when developers accept generated code without review.
-
-### Architecture & Structure
-
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Oversized Files** | Medium | Files exceeding line threshold. AI dumps everything in one file. |
-| **God File** | High | Files with >10 exports, mixed concerns, and high import fan-in. The "does everything" file. |
-| **Bloated Barrel** | Medium/High | `index.ts` files with >15 re-exports. Kills tree-shaking and slows bundlers. |
-| **Circular Dependencies** | High | Import cycles (A → B → C → A) detected via DFS graph traversal. Causes runtime errors. |
-| **Separation of Concerns** | Medium | `fetch()` in React components, SQL outside data layers, business logic in route handlers. |
-
-### Code Quality
-
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Dead Code & Unused Exports** | High | Exported functions, types, and variables that are never imported anywhere. |
-| **Code Duplication** | High/Medium | 6+ duplicate lines across different files. Copy-paste without abstraction. |
-| **Poor Maintainability** | High/Medium/Low | Long functions (>50 lines), too many parameters (>4), excessive imports (>10), magic numbers. |
-| **Missing Error Handling** | High/Medium | `async` functions without try/catch, unhandled Promise chains, empty/swallowed catch blocks, console-only error handling. |
-| **Missing Tests** | High/Medium | No test files, low test-to-source ratio, empty tests, trivial assertions (`expect(true).toBe(true)`), generic test names, skipped/todo tests. |
-
-### Style & Patterns
-
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Style Inconsistency** | Medium | Mixed camelCase/snake_case, function declarations vs arrows, single vs double quotes, semicolons. |
-| **Pattern Inconsistency** | Medium | Mixed styling approaches (Tailwind + CSS Modules + inline styles in the same project). |
-| **Obsolete Patterns** | Medium | `var` declarations, `.then()` chains (3+ deep), React class components, CommonJS in `.ts` files, `arguments` keyword. |
-
-### Dependencies & Config
-
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Unused Dependencies** | High/Medium | Packages in `package.json` that are never imported in your code. |
-| **Duplicate Dependencies** | High | Multiple packages for the same purpose: axios + fetch, jest + vitest, moment + dayjs, etc. |
-| **Hardcoded Secrets** | Critical | API keys, tokens, passwords, and connection strings hardcoded in source files. |
-
-### AI-Specific Smells
+## What It Detects
 
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **AI Smell** | High/Medium/Info | `console.log` in production, generic names (`data`, `result`, `temp`) as info-level, obvious comments, `utils.ts` dumping grounds, placeholder logic (`throw new Error('Not implemented')`) as high. |
-| **Abandoned TODO/FIXME** | Medium/Low | Unresolved `TODO`, `FIXME`, `HACK`, `XXX` comments — unfinished work that shipped anyway. |
+| Category | Rules | Focus |
+|----------|:-----:|-------|
+| **Architecture** | 5 | Oversized files, god files, bloated barrels, circular dependencies, mixed concerns |
+| **Code Quality** | 5 | Dead code, copy-paste duplication, long functions, missing error handling, missing tests |
+| **Style & Patterns** | 3 | Inconsistent naming, mixed styling approaches, `var` declarations, `.then()` chains |
+| **Dependencies** | 3 | Unused packages, duplicate libraries (axios + fetch), hardcoded secrets |
+| **AI Smells** | 2 | `console.log` in production, generic names (`data`, `temp`), placeholder logic, abandoned TODOs |
+| **Ship-Readiness** | 6 | Security anti-patterns, accessibility violations, missing linter, no favicon, missing legal pages |
 
-### Security & Compliance
+## Scoring
 
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Security Anti-Patterns** | Critical/High | SQL injection risks, `eval()` with dynamic input, hardcoded credentials, CORS wildcards, sensitive data in localStorage, `innerHTML` with user input, `Math.random()` for security, `dangerouslySetInnerHTML`. |
-| **Missing Compliance Pages** | Critical/High | Missing Terms of Service, Privacy Policy, unresolved legal placeholders (`[Company Name]`), analytics without cookie consent, auth without account deletion. |
-| **Accessibility Anti-Patterns** | Medium/Low | Images without `alt` text, non-semantic click handlers (`<div onClick>`), form inputs without labels, missing ARIA landmarks, non-descriptive link text ("click here"). |
-
-### Ship-Readiness
-
-| Rule | Severity | What It Detects |
-|------|----------|-----------------|
-| **Missing Project Standards** | High/Medium/Low | Missing `tsconfig.json`, no linter config (ESLint/Biome), missing `.gitignore`, `.env` without `.env.example`, no formatter config, missing `.editorconfig`, no `README.md`. |
-| **Missing Production Basics** | Medium/Low | Generic page titles ("Create Next App"), missing meta description, default/missing favicon, no Open Graph tags, missing custom 404 page, no `robots.txt`, no `sitemap.xml`. |
-| **React Performance** | High/Medium/Low | Array index as key, problematic `useEffect` patterns, `setState` in loops, nested component definitions, inline objects/functions in JSX, spreading all props. *(Disabled by default — very noisy)* |
-
----
-
-## Grading System
-
-ViberTest scores your project **0 to 100** and assigns a letter grade:
+Each scan produces a **health score (10–100)** with a letter grade (A–F). Issues are weighted by severity with diminishing returns — 15 medium issues from one rule won't crush your score the same as 5 critical ones.
 
 | Grade | Score | Meaning |
-|-------|-------|---------|
-| **A** | 90–100 | Excellent — Clean, well-structured code |
-| **B** | 75–89 | Good — Minor issues, solid foundation |
-| **C** | 60–74 | Needs Work — Noticeable quality gaps |
-| **D** | 40–59 | Poor — Significant structural problems |
-| **F** | 0–39 | Critical — Major issues across the board |
-
-### How Scoring Works
-
-Each issue deducts penalty points based on severity:
-
-| Severity | Penalty | Scaling |
-|----------|---------|---------|
-| **Critical** | 5 pts | Linear — every instance fully counts |
-| **High** | 3 pts | Linear — every instance fully counts |
-| **Medium** | 1 pt | Diminishing returns — `log₂(count + 1)` per rule |
-| **Low** | 0.5 pts | Diminishing returns — `log₂(count + 1)` per rule |
-| **Info** | 0 pts | No penalty |
-
-**Why diminishing returns?** Having 15 medium issues from the same rule shouldn't crush your score the same as 15 critical issues. The logarithmic curve means the first few instances of a medium/low rule matter, but additional ones have decreasing impact. This keeps the scoring fair while still rewarding cleanup.
-
-**Example:** 15 medium issues from one rule = **4 points** (not 15). But 5 critical issues = **25 points** (every one counts).
-
----
-
-## Web Dashboard
-
-ViberTest includes a built-in web dashboard for visualizing scan results. Upload a JSON report and get interactive charts, file rankings, and a visual health thermometer.
-
-<!-- Replace with your actual screenshot -->
-<div align="center">
-  <img src="docs/assets/dashboard.png" alt="ViberTest Web Dashboard" width="800" />
-</div>
-
-### Features
-
-- **Health Thermometer** — Vertical segmented gauge showing your score at a glance
-- **Severity Breakdown** — Pie chart of issues by severity level
-- **Rule Distribution** — Bar chart showing which rules found the most issues
-- **File Ranking** — Top problematic files sorted by issue count
-- **Scan Metadata** — Project name, scan duration, file count, timestamp
-
-### Running the Dashboard Locally
-
-```bash
-# From the project root
-cd packages/web
-
-# Development mode (with hot reload)
-pnpm dev
-
-# Open http://localhost:3000
-```
-
-### How to Use
-
-1. **Generate a JSON report** from the CLI:
-   ```bash
-   vibertest scan ~/my-project --format json --output report.json
-   ```
-
-2. **Open the dashboard** at `http://localhost:3000`
-
-3. **Upload the JSON file** — drag & drop or click to browse
-
-4. **Explore the results** — interactive charts, file rankings, and detailed breakdowns
-
-### Production Build
-
-```bash
-cd packages/web
-pnpm build
-pnpm start
-# Dashboard available at http://localhost:3000
-```
-
----
+|:-----:|:-----:|---------|
+| **A** | 90–100 | Excellent |
+| **B** | 75–89 | Good |
+| **C** | 60–74 | Needs Work |
+| **D** | 40–59 | Poor |
+| **F** | 0–39 | Critical |
 
 ## Configuration
 
-Create a `.vibertestrc.json` in your project root to customize ViberTest:
-
 ```bash
 vibertest init
 ```
 
-### Default Configuration
+Creates a `.vibertestrc.json` where you can enable/disable rules, set thresholds, and configure ignore patterns:
 
 ```jsonc
 {
   "rules": {
-    // Architecture & Structure
-    "oversized-files": { "enabled": true },
-    "god-file": { "enabled": true },
-    "bloated-barrel": { "enabled": true },
-    "circular-deps": { "enabled": true },
-    "separation-of-concerns": { "enabled": true },
-    
-    // Code Quality
-    "dead-code": { "enabled": true },
-    "code-duplication": { "enabled": true },
-    "poor-maintainability": { "enabled": true },
-    "missing-error-handling": { "enabled": true },
-    "missing-tests": { "enabled": true },
-    
-    // Style & Patterns
-    "style-inconsistency": { "enabled": true },
-    "pattern-inconsistency": { "enabled": true },
-    "obsolete-patterns": { "enabled": true },
-    
-    // Dependencies & Config
-    "unused-deps": { "enabled": true },
-    "duplicate-deps": { "enabled": true },
-    "hardcoded-secrets": { "enabled": true },
-    
-    // AI-Specific Smells
-    "ai-smell": { "enabled": true },
-    "abandoned-todo": { "enabled": true },
-    
-    // Security & Compliance
-    "security-antipatterns": { "enabled": true },
-    "missing-compliance": { "enabled": true },
-    "accessibility": { "enabled": true },
-    
-    // Ship-Readiness
-    "missing-project-standards": { "enabled": true },
-    "missing-production-basics": { "enabled": true },
-    "react-performance": { "enabled": false }  // Disabled by default (very noisy)
+    "react-performance": { "enabled": true },
+    "pattern-inconsistency": { "enabled": false }
   },
-  "ignore": [
-    "node_modules", "dist", "build",
-    ".next", "coverage", ".turbo", ".git"
-  ],
+  "ignore": ["generated", "legacy"],
   "thresholds": {
-    "maxFileLines": 300,
-    "maxFunctionLines": 50,
-    "maxFunctionParams": 4,
-    "maxImports": 10,
-    "minTestRatio": 0.05
-  }
-}
-```
-
-### Disabling Rules
-
-```jsonc
-{
-  "rules": {
-    // Disable rules you don't need
-    "pattern-inconsistency": { "enabled": false },
-    "style-inconsistency": { "enabled": false }
+    "maxFileLines": 500,
+    "maxFunctionLines": 60
   }
 }
 ```
 
-### Custom Thresholds
-
-```jsonc
-{
-  "thresholds": {
-    "maxFileLines": 500,      // Allow larger files
-    "maxFunctionLines": 80,   // Allow longer functions
-    "maxFunctionParams": 5,   // Allow more parameters
-    "maxImports": 15,         // Allow more imports
-    "minTestRatio": 0.1       // Lower test coverage requirement
-  }
-}
-```
-
-### Ignoring Files
-
-```jsonc
-{
-  "ignore": [
-    "node_modules", "dist", "build",
-    "generated",           // Skip generated code
-    "legacy",              // Skip legacy modules
-    "**/*.generated.ts"    // Skip generated files
-  ]
-}
-```
-
----
-
 ## CI Integration
 
-ViberTest exits with code **1** when issues are found, making it easy to integrate into CI pipelines:
+Exits with code **1** when issues are found, **0** when clean:
 
 ```yaml
-# GitHub Actions example
 - name: Run ViberTest
-  run: vibertest scan . --format json --output vibertest-report.json
-```
-
-```bash
-# Or in any CI script
-vibertest scan . || echo "ViberTest found issues"
-```
-
----
-
-## Project Structure
-
-```
-vibertest/
-├── packages/
-│   ├── cli/              # CLI tool (@vibertest/cli)
-│   │   ├── src/
-│   │   │   ├── rules/    # 24 analysis rules
-│   │   │   ├── scorer/   # Scoring engine with diminishing returns
-│   │   │   ├── scanner/  # File collection & orchestration
-│   │   │   ├── reporter/ # Terminal & JSON output
-│   │   │   └── config/   # Config loading & validation (Zod)
-│   │   └── bin/          # CLI entry point
-│   ├── shared/           # Shared types & constants (@vibertest/shared)
-│   └── web/              # Web Dashboard (@vibertest/web)
-│       └── src/
-│           ├── app/      # Next.js 15 App Router pages
-│           ├── components/ # Dashboard UI components
-│           ├── stores/   # Zustand state management
-│           └── lib/      # Utilities
-├── docs/                 # Specs & design system
-├── turbo.json            # Turborepo config
-├── biome.json            # Linting & formatting
-└── pnpm-workspace.yaml   # Monorepo workspace
-```
-
-## Tech Stack
-
-| Package | Stack |
-|---------|-------|
-| **CLI** | TypeScript, Commander.js, Chalk, Ora, Zod 3, Cosmiconfig |
-| **Shared** | TypeScript, tsup |
-| **Web** | Next.js 15, React 19, Tailwind CSS 4, Zustand 5, Recharts, Lucide Icons |
-| **Tooling** | pnpm workspaces, Turborepo, Biome, Vitest |
-
----
-
-## Self-Scan Results
-
-ViberTest analyzes itself and scores **88/100 (Grade B)** with 24 rules enabled:
-
-```
-HEALTH SCORE
-
-       ██████╗
-       ██╔══██╗
-       ██████╔╝
-       ██╔══██╗
-       ██████╔╝
-       ╚═════╝
-
-  88/100  ██████████████████████████░░░░  Good
+  run: npx vibertest scan . --format json --output vibertest-report.json
 ```
 
----
-
-## License
+## Links
 
-AGPL-3.0 — See [LICENSE](LICENSE) for details.
-
----
-
-<div align="center">
-
-**ViberTest** — Stop shipping AI slop.
-
-</div>
+- [Documentation](https://vibertest.chyste.dev/docs)
+- [Report Viewer](https://vibertest.chyste.dev/report)
+- [All 24 Rules](https://vibertest.chyste.dev/docs/rules)
+- [Configuration Guide](https://vibertest.chyste.dev/docs/configuration)
+- [CI Integration](https://vibertest.chyste.dev/docs/ci-integration)
+- [GitHub](https://github.com/Chyste/vibertest)
+- [Issues & Feature Requests](https://github.com/Chyste/vibertest/issues)