@next-vibe/checker 1.0.49 → 1.0.51

package/.dist/README.md

@@ -1,57 +1,50 @@
-# @next-vibe/checker
+# @next-vibe/checker aka vibe check
 
-> Comprehensive TypeScript code quality checker combining Oxlint, ESLint, and TypeScript
+Run Oxlint, ESLint, and TypeScript in parallel. Fast caching, auto-fix by default.
 
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 
-Run parallel code quality checks (Oxlint + ESLint + TypeScript) with auto-fix enabled by default. Built with Rust-powered Oxlint for maximum performance.
-
 ## Features
 
 - **Parallel execution** - All checks run simultaneously
-- **Smart caching** - Dramatically faster on subsequent runs
-- **Auto-fix** - Automatically fixes issues (enabled by default)
-- **100+ rules** - React, TypeScript, a11y, Next.js, Node.js
-- **Custom plugins** - i18n validation, JSX capitalization, restricted syntax
-- **MCP server** - Expose tools via Model Context Protocol
-- **Fast type checking** - Uses tsgo (2-3x faster than tsc)
+- **Smart caching** - 10x faster on large projects (41s → 4s)
+- **Auto-fix** - Fixes issues by default
+- **100+ rules** - React, TypeScript, a11y, Next.js, Node.js, custom plugins
+- **MCP server** - Integrate with Claude via Model Context Protocol
+- **Fast type checking** - tsgo (2-3x faster than tsc)
 
 ## Performance
 
-Times vary by project size and cache state. **tsgo is enabled by default** (2-3x faster than tsc).
-
-**Small project:**
-
-- With cache: 1.1s total (Oxlint: 0.48s, ESLint: 1.06s, TypeScript: 0.20s)
-- Without cache: 1.1s total (Oxlint: 0.48s, ESLint: 1.06s, TypeScript: 0.20s)
-- **With tsc: 1.1s cached / 1.5s uncached**
-
-**Medium project:**
+| Project | Cold Cache | Warm Cache | Speed |
+| ------- | ---------- | ---------- | ----- |
+| Small   | 0.69s      | 0.71s      | 1x    |
+| Medium  | 5.51s      | 1.30s      | 4x    |
+| Large   | 41.24s     | 4.29s      | 10x   |
 
-- With cache: 2.8s total (Oxlint: 2.55s, ESLint: 2.76s, TypeScript: 0.62s)
-- Without cache: 5.9s total (Oxlint: 3.17s, ESLint: 4.37s, TypeScript: 5.81s)
-- **With tsc: 12.5s cached / 13.9s uncached**
+Caching is automatic. Add `.tmp/` to `.gitignore`.
 
-**Large project:**
-
-- With cache: 9.8s total (Oxlint: 9.80s, ESLint: 3.71s, TypeScript: 3.83s)
-- Without cache: 51.3s total (Oxlint: 16.76s, ESLint: 23.87s, TypeScript: 51.30s)
-- **With tsc: 12.7s cached / 72.9s uncached**
+## Quick Start
 
-**Key insights:**
+```bash
+npm install --save-dev @next-vibe/checker
+npx @next-vibe/checker config-create
+npm run check
+```
 
-- **Caching provides 5x speedup on large projects**
-- **tsgo is 2-3x faster than tsc for TypeScript checking**
-- **ESLint can be disabled** if you only need Oxlint rules (saves ~3s on large projects)
+That's it. `config-create` adds check/lint/typecheck scripts to package.json. Then just use `npm run check`.
 
-## Installation
+For global install (optional):
 
-### Recommended: AI-Assisted Setup (Clean Migration)
+```bash
+npm install -g @next-vibe/checker
+vibe config-create # or shorter: v cc
+vibe check # or shorter: v c
+```
 
-**Best for:** Migrating from existing linters (ESLint, Prettier, etc.) or setting up from scratch.
+## Migrate from ESLint/Prettier
 
-Copy this prompt to your AI agent (Claude Code, Cursor, etc.):
+Copy this prompt to your AI agent:
 
 ```
 Migrate to @next-vibe/checker:
@@ -65,180 +58,105 @@ STEP 1: Ask user questions
 - Enable pedantic rules?
 - Enable restricted syntax? (no throw, unknown, any, object)
 - Create .mcp.json?
-- Install globally? (makes `vibe` and `v` commands available everywhere)
-- VSCode integration? (only ask if .vscode folder doesn't exist - auto-enable if it exists)
+- Install globally?
+- VSCode integration?
 
 STEP 2: Install and create config
-1. Detect package manager (check for bun.lockb, package-lock.json, yarn.lock, pnpm-lock.yaml)
-2. Install locally: <pm> add -D @next-vibe/checker
-3. If user wants global: <pm> add -g @next-vibe/checker (or global install command for pm)
-4. Delete old check.config.ts if it exists
-5. Detect VSCode: Check if .vscode folder exists
-6. Create config with user's answers:
-   <pm-exec> @next-vibe/checker config-create \
-     --update-package-json=true \
-     --create-mcp-config=<true|false> \
-     --update-vscode-settings=<true if .vscode exists OR user said yes> \
-     --enable-react-rules=<true|false> \
-     --enable-nextjs-rules=<true|false> \
-     --enable-i18n-rules=<true|false> \
-     --enable-pedantic-rules=<true|false> \
-     --enable-restricted-syntax=<true|false>
-   Note: package.json scripts updated automatically to "v c"
-
-STEP 3: Customize check.config.ts and editor
+1. Detect package manager (bun.lockb, package-lock.json, yarn.lock, pnpm-lock.yaml)
+2. Install: npm add -D @next-vibe/checker (or equivalent for your package manager)
+3. If global: npm install -g @next-vibe/checker
+4. Run: npm exec @next-vibe/checker config-create
+   (or: npx @next-vibe/checker config-create)
+
+STEP 3: Configure
 1. Read check.config.ts
-2. If user wants to disable ESLint: Change line 721 from `enabled: true,` to `enabled: false,`
-3. If strictness is pedantic: Change line 47 from `pedantic: false,` to `pedantic: true,`
-4. Analyze old linter configs (.eslintrc.*, .prettierrc, etc.) for custom rules
-5. Port custom rules to Oxlint plugins (create files in oxlint-plugins/*.ts)
-6. Add custom plugin paths to jsPlugins array around line 125
-7. Setup editor integration:
-   - VSCode: Already configured via .vscode/settings.json (oxc extension, tsgo)
-   - Other editors: Detect editor, configure for tsgo and oxlint:
-     * JetBrains IDEs: Setup oxlint file watcher, configure tsgo for TypeScript
-     * Neovim/Vim: Configure LSP for oxlint and tsgo
-     * Sublime/Atom/etc: Setup linter plugins
+2. To disable ESLint: Change `skipEslint: false` to `skipEslint: true`
+3. To enable pedantic: In the `features` object at line 46, change `pedantic: false` to `pedantic: true`
+4. Analyze old .eslintrc, .prettierrc, eslint config files
+5. Port custom rules to Oxlint plugins (oxlint-plugins/*.ts)
+6. Add plugin paths to jsPlugins array in config (around line 124)
+7. Setup editor:
+   - VSCode: .vscode/settings.json (oxc extension, tsgo)
+   - JetBrains: oxlint file watcher, tsgo for TypeScript
+   - Neovim/Vim: LSP for oxlint and tsgo
 8. Remove old linter packages and configs
-9. Test: <pm-exec> @next-vibe/checker check
-10. Report results (what was changed, what rules were ported, editor setup)
-
-Oxlint plugins are much faster than ESLint - always prefer them for custom rules.
-```
+9. Test: npm exec @next-vibe/checker check (or: npx @next-vibe/checker check)
+10. Report what was changed and migrated
 
-The AI agent will handle the complete migration automatically.
-
-### Manual Installation
-
-```bash
-npm install --save-dev @next-vibe/checker
-# or
-bun add -d @next-vibe/checker
-```
-
-Optional global install for `vibe` command:
-
-```bash
-npm install -g @next-vibe/checker
-# or
-bun add -g @next-vibe/checker
+Note: Oxlint plugins are much faster than ESLint rules - prefer them.
 ```
 
-Without global install, use `npx @next-vibe/checker` instead of `vibe`.
+The AI will handle the complete migration automatically.
 
-## Quick Start
+## Commands
 
 ```bash
-# 1. Install in your project
-npm install --save-dev @next-vibe/checker
-
-# 2. Create configuration (interactive)
-vibe config-create
-
-# 3. Run checks
-vibe check
-# or use the short version:
-v c
+vibe check [paths]              # Run all checks
+vibe check src                  # Check specific directory
+vibe check src app.tsx          # Check multiple paths
+vibe check --limit=50           # Show first 50 issues (default: 200)
+vibe check --fix                # Auto-fix issues
+vibe check --timeout=600        # Max execution time (seconds)
+vibe check --page=2             # View page 2 of results
+vibe config-create              # Create/update configuration
+vibe mcp                         # Start MCP server
+vibe list                        # All available commands
 ```
 
-**Tip:** Use `v` as a short alias for `vibe` and `c` for `check` (e.g., `v c` instead of `vibe check`).
-
-The `config-create` command interactively sets up:
-
-- `check.config.ts` - Main configuration
-- ESLint enable/disable - Only needed for rules not in Oxlint (import sorting, React hooks)
-- `.mcp.json` - MCP server config (optional)
-- `.vscode/settings.json` - VSCode integration (optional)
-- `package.json` scripts - npm run check/lint/typecheck (optional)
+Without global install, replace `vibe` with `npx @next-vibe/checker` or `npm exec @next-vibe/checker`.
 
-## Commands
-
-```bash
-vibe check                # Run all checks (auto-fix enabled)
-vibe check src            # Check specific paths
-vibe check src public     # Check multiple paths
-vibe check some/path.ts   # Check specific file
-vibe check --limit=50     # Limit displayed issues
-vibe config-create        # Create/update configuration
-vibe mcp                  # Start MCP server
-vibe list                 # List all commands
-
-# Short versions
-v c                       # Same as: vibe check
-v c src                   # Same as: vibe check src
-v cc           # Same as: vibe config-create
-```
+**Short aliases** (global install only): `v c` = check, `v cc` = config-create
 
 ## Configuration
 
-The `check.config.ts` file controls all behavior:
+Edit `check.config.ts`. Key settings:
 
 ```typescript
-import type { CheckConfig } from "@next-vibe/checker/system/check/config/types";
-
-const config: CheckConfig = {
-  vibeCheck: {
-    fix: true, // Auto-fix (default: true)
-    limit: 200, // Max issues to display
-    timeout: 3600, // Max execution time (seconds)
-  },
-
-  oxlint: {
-    enabled: true,
-    configPath: ".tmp/.oxlintrc.json",
-    cachePath: ".tmp/oxlint-cache", // Enable caching
-  },
-
-  eslint: {
-    enabled: true,
-    configPath: ".tmp/eslint.config.mjs",
-    cachePath: ".tmp/eslint-cache", // Enable caching
-  },
-
-  typecheck: {
-    enabled: true,
-    useTsgo: true, // 2-3x faster than tsc
-  },
+const vibeCheck = {
+  fix: true, // Auto-fix enabled by default
+  limit: 200, // Max issues per page
+  timeout: 3600, // Max execution time (seconds)
+  skipEslint: false, // Set to true to disable ESLint
+  skipOxlint: false, // Set to true to disable Oxlint
+  skipTypecheck: false, // Set to true to skip TypeScript
 };
 
-export default config;
+const features = {
+  pedantic: false, // Set to true for stricter rules
+  react: true,
+  nextjs: true,
+  i18n: true,
+  tsgo: true, // ~2-3x faster than tsc
+  // ... other feature flags
+};
 ```
 
-See [check.config.ts](./check.config.ts) for complete example with all options.
+See [check.config.ts](./check.config.ts) for the complete configuration.
 
 ## What Gets Checked
 
-### Oxlint (Rust-powered)
+**Oxlint** (~1-5s) - React, TypeScript, a11y, custom plugins
 
-- 100+ built-in rules for React, TypeScript, a11y
-- Custom plugins:
-  - i18n validation (no hardcoded strings)
-  - JSX capitalization enforcement
-  - Restricted syntax (no `throw`, `unknown`, `object` types)
-- Promise best practices
-- Node.js patterns
-- Unicorn modern JS rules
-- **Uses cache** for faster subsequent runs
+- 100+ built-in rules
+- i18n validation (no hardcoded strings)
+- JSX capitalization enforcement
+- Restricted syntax (no throw/unknown/any)
 
-### ESLint (Optional)
+**ESLint** (~1-40s, optional) - Import sorting, React hooks, React compiler rules
 
-- Import/export sorting
-- React hooks validation
-- React compiler rules
-- **Uses cache** for faster subsequent runs
-- **Can be disabled** if you don't need these rules (Oxlint covers most cases)
-- Only needed for rules not yet supported by Oxlint
+- Disable: Set `skipEslint: true` in config
+- Without it: lose import sorting & React hook checks
 
-### TypeScript
+**TypeScript** (~0.05-5s) - Full type checking with tsgo
 
-- Full type checking with tsgo or tsc
+- ~2-3x faster than tsc
 - Strict type rules (optional)
 
-All checks run **in parallel** for maximum speed.
+All run in parallel. Total time ≈ slowest check.
 
 ## MCP Server
 
-Configure in `.mcp.json` (created by `vibe config-create`):
+Configure in `.mcp.json`:
 
 ```json
 {
@@ -246,115 +164,94 @@ Configure in `.mcp.json` (created by `vibe config-create`):
     "vibe": {
       "command": "npx",
       "args": ["@next-vibe/checker", "mcp"],
-      "env": {
-        "PROJECT_ROOT": "/path/to/your/project"
-      }
+      "env": { "PROJECT_ROOT": "/path/to/project" }
     }
   }
 }
 ```
 
-The MCP server exposes:
-
-- `check` - Run comprehensive code quality checks
+Compatible with any MCP-compatible client.
 
-Compatible with any MCP client.
+## CI/CD Integration
 
-## Usage in Projects
+### GitHub Actions
 
-### With npm Scripts
+```yaml
+- run: npm install
+- run: npm exec @next-vibe/checker check
+```
 
-If you selected package.json update during `config-create`:
+### GitLab CI
 
-```json
-{
-  "scripts": {
-    "check": "v c",
-    "lint": "v c",
-    "typecheck": "v c"
-  }
-}
+```yaml
+script:
+  - npm install
+  - npm exec @next-vibe/checker check
 ```
 
-The scripts use the short version `v c` (equivalent to `vibe check`).
+## Caching
 
-Then run:
+Caching is automatic and enabled by default.
 
-```bash
-npm run check
-# or
-npm run lint
-# or
-npm run typecheck
-```
+**Speed improvements:**
 
-### Without Global Install
+- Medium projects: 5.5s → 1.3s **(4x faster)**
+- Large projects: 41s → 4.3s **(10x faster)**
+
+**Cache directories:**
 
-```bash
-npx @next-vibe/checker check
+```
+.tmp/eslint-cache/
+.tmp/typecheck-cache/
 ```
 
-## CI/CD Integration
+Clear cache: `rm -rf .tmp/`
 
-### GitHub Actions
+## Troubleshooting
 
-```yaml
-name: Code Quality
-on: [push, pull_request]
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-      - run: npm install
-      - run: npm run check # Uses "v c" script from package.json
-```
+**Not finding issues?**
 
-### GitLab CI
+- Enable stricter rules: Set `pedantic: true` in `features`
+- Check that checks aren't disabled (skipEslint, skipOxlint, skipTypecheck)
 
-```yaml
-check:
-  image: node:18
-  script:
-    - npm install
-    - npm run check # Uses "v c" script from package.json
-```
+**Too slow?**
 
-**Note:** If you didn't add package.json scripts during `config-create`, use `npx @next-vibe/checker check` directly in CI.
+- Disable ESLint: `skipEslint: true`
 
-## Caching
+**Cache not working?**
+
+- Check that `.tmp/` directory is writable
+- Clear and rebuild: `rm -rf .tmp/ && vibe check`
 
-The checker uses caching to speed up subsequent runs:
+**MCP broken?**
 
-- **Oxlint cache**: `.tmp/oxlint-cache`
-- **ESLint cache**: `.tmp/eslint-cache`
+- Verify `.mcp.json` in project root
+- Check `PROJECT_ROOT` environment variable
+- Restart Claude/Cursor
 
-Cache directories are created automatically. Add `.tmp/` to your `.gitignore`.
+**Command not found?**
 
-On first run (cold cache), checks are slower. Subsequent runs are significantly faster.
+- If no global install: Add "check": `vibe check` to your `package.json` and use with `npm run check`
+- If globally installed: Ensure npm global bin is in PATH
 
-## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for more help.
 
-This project lives on the `vibe-check` branch:
+## Development
 
 ```bash
 git clone https://github.com/techfreaque/next-vibe.git
-cd next-vibe
-git checkout vibe-check
-bun install
-bun vibe check
+cd next-vibe && git checkout vibe-check
+bun install && vibe check --fix
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-GPL-3.0-only - see [LICENSE](LICENSE)
+GPL-3.0-only
 
 ## Links
 
-- [GitHub Repository](https://github.com/techfreaque/next-vibe/tree/vibe-check)
-- [npm Package](https://www.npmjs.com/package/@next-vibe/checker)
-- [Report Issues](https://github.com/techfreaque/next-vibe/issues)
+- [GitHub](https://github.com/techfreaque/next-vibe/tree/vibe-check)
+- [npm](https://www.npmjs.com/package/@next-vibe/checker)
+- [Issues](https://github.com/techfreaque/next-vibe/issues)