@next-vibe/checker 1.0.22 → 1.0.24

package/.dist/README.md

@@ -1,283 +1,234 @@
-# vibe-check
+# @next-vibe/checker
 
-> Minimal TypeScript code quality checker with CLI and MCP support
+> Comprehensive TypeScript code quality checker combining Oxlint, ESLint, and TypeScript
 
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![npm version](https://badge.fury.io/js/vibe-check.svg)](https://www.npmjs.com/package/vibe-check)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 
-A lightning-fast, zero-config code quality tool that combines **Oxlint**, **ESLint**, and **TypeScript** checking with built-in release management and MCP server support.
+Run parallel code quality checks (Oxlint + ESLint + TypeScript) with auto-fix enabled by default. Built with Rust-powered Oxlint for maximum performance.
 
 ## Features
 
-### 🚀 Code Quality
+- **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)
 
-- **Triple-layer validation**: Oxlint (Rust-powered speed) + ESLint (custom rules) + TypeScript (type safety)
-- **Zero configuration**: Works out of the box with sensible defaults
-- **Parallel execution**: Multi-core processing for maximum performance
-- **Auto-fix support**: Automatically fix linting and formatting issues
-- **Comprehensive rules**: 100+ built-in rules for React, TypeScript, a11y, and more
+## Performance
 
-### 📦 Release Management
+Times vary by project size and cache state. **tsgo is enabled by default** (2-3x faster than tsc).
 
-- **Semantic versioning**: Automated version bumping (major, minor, patch)
-- **Git integration**: Automatic tagging, committing, and pushing
-- **Interactive prompts**: Guided release workflow with confirmations
-- **npm publishing**: Built-in support for publishing to npm registry
-- **Changelog generation**: Optional automated changelog creation
-- **Multi-package support**: Manage monorepo releases
+### With tsgo (default)
 
-### 🤖 MCP Server
+**Small project:**
+- With cache: ~1s total (Oxlint: 0.5s, ESLint: 1.1s, TypeScript: 0.2s)
+- Without cache: ~1s total (Oxlint: 0.5s, ESLint: 1.1s, TypeScript: 0.2s)
 
-- **Claude Desktop integration**: Use vibe-check as a Model Context Protocol server
-- **AI-powered code review**: Let Claude analyze your codebase quality
-- **Interactive debugging**: Real-time feedback on code issues
+**Medium project:**
+- With cache: ~3s total (Oxlint: 2.5s, ESLint: 2.8s, TypeScript: 0.6s)
+- Without cache: ~6s total (Oxlint: 3.2s, ESLint: 4.4s, TypeScript: 5.8s)
 
-### 🛠️ Developer Experience
+**Large project:**
+- With cache: ~10s total (Oxlint: 9.8s, ESLint: 3.7s, TypeScript: 3.8s)
+- Without cache: ~51s total (Oxlint: 16.8s, ESLint: 23.9s, TypeScript: 51.3s)
 
-- **Fast**: Rust-based oxlint + parallel processing
-- **Smart**: Auto-detects project structure and configuration
-- **Flexible**: Customize via `check.config.ts`
-- **Universal**: Works with any TypeScript/JavaScript project
+### With tsc (if tsgo disabled)
 
-## Installation
+**Small project:**
+- With cache: ~1s total (Oxlint: 0.4s, ESLint: 1.1s, TypeScript: 1.0s)
+- Without cache: ~2s total (Oxlint: 0.5s, ESLint: 1.4s, TypeScript: 1.5s)
 
-### NPM
+**Medium project:**
+- With cache: ~13s total (Oxlint: 2.8s, ESLint: 2.1s, TypeScript: 12.5s)
+- Without cache: ~14s total (Oxlint: 3.3s, ESLint: 4.8s, TypeScript: 13.9s)
 
-```bash
-npm install -g vibe-check
-```
+**Large project:**
+- With cache: ~13s total (Oxlint: 10.8s, ESLint: 2.9s, TypeScript: 12.7s)
+- Without cache: ~73s total (Oxlint: 16.3s, ESLint: 24.2s, TypeScript: 72.9s)
 
-### Bun (Recommended)
+**Key insights:**
+- **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)
 
-```bash
-bun add -g vibe-check
-```
+## Installation
 
-### Local Installation
+### Required: Install in Your Project
 
 ```bash
-npm install --save-dev vibe-check
+npm install --save-dev @next-vibe/checker
+# or
+bun add -d @next-vibe/checker
 ```
 
-## Quick Start
+### Optional: Install Globally
 
-### 1. Initialize Configuration
+For the `vibe` command:
 
 ```bash
-vibe check --create-config
+npm install -g @next-vibe/checker
+# or
+bun add -g @next-vibe/checker
 ```
 
-This creates a `check.config.ts` file with sensible defaults.
+Without global install, use `npx @next-vibe/checker` instead of `vibe`.
 
-### 2. Run Code Quality Checks
+## Quick Start
 
 ```bash
-vibe check
-```
-
-This runs:
-- ✓ **Oxlint** - Fast Rust linter (1-2s for most projects)
-- ✓ **ESLint** - Custom rules (import sorting, React hooks, i18n)
-- ✓ **TypeScript** - Type checking with tsgo
+# 1. Install in your project
+npm install --save-dev @next-vibe/checker
 
-### 3. Auto-fix Issues
-
-```bash
-vibe check --fix
-```
+# 2. Create configuration (interactive)
+vibe config-create
 
-Automatically fixes:
-- Formatting issues
-- Import order
-- Common linting violations
-
-## CLI Commands
-
-### Code Quality
-
-```bash
-# Run all checks
+# 3. Run checks
 vibe check
-
-# Run with auto-fix
-vibe check --fix
-
-# Run specific checks
-vibe check --skip-lint        # Skip linting
-vibe check --skip-typecheck   # Skip type checking
-
-# Verbose output
-vibe check --verbose
-```
-
-### Release Management
-
-```bash
-# Interactive release (recommended)
-vibe release
-
-# Automated release with version increment
-vibe release --version-increment patch  # 1.0.0 → 1.0.1
-vibe release --version-increment minor  # 1.0.0 → 1.1.0
-vibe release --version-increment major  # 1.0.0 → 2.0.0
-
-# CI/CD mode (non-interactive)
-vibe release --ci
-
-# Dry run (preview changes)
-vibe release --dry-run
 ```
 
-### Build & Setup
+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)
 
-```bash
-# Build the project
-vibe builder
-
-# Setup/update CLI
-vibe setup install
-vibe setup status
-vibe setup update
-vibe setup uninstall
-```
-
-### MCP Server
+## Commands
 
 ```bash
-# Start MCP server for Claude Desktop
-vibe mcp
-
-# Test MCP server
-bunx @modelcontextprotocol/inspector bun vibe mcp
+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
 ```
 
 ## Configuration
 
-### check.config.ts
-
-Create `check.config.ts` in your project root:
+The `check.config.ts` file controls all behavior:
 
 ```typescript
-import type { CheckConfig } from "vibe-check/system/check/config/types";
+import type { CheckConfig } from "@next-vibe/checker/system/check/config/types";
 
 const config: CheckConfig = {
-  // Oxlint (fast Rust linter)
+  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",
+    cachePath: ".tmp/oxlint-cache",  // Enable caching
   },
 
-  // ESLint (custom rules)
   eslint: {
     enabled: true,
     configPath: ".tmp/eslint.config.mjs",
-    cachePath: ".tmp/eslint-cache",
+    cachePath: ".tmp/eslint-cache",  // Enable caching
   },
 
-  // TypeScript type checking
   typecheck: {
     enabled: true,
-    cachePath: ".tmp/typecheck-cache",
-    useTsgo: true, // Use tsgo instead of tsc (faster)
-  },
-
-  // Prettier formatting
-  prettier: {
-    enabled: true,
-    configPath: ".tmp/.oxfmtrc.json",
-  },
-
-  // VSCode integration
-  vscode: {
-    enabled: true,
-    autoGenerateSettings: true,
+    useTsgo: true,  // 2-3x faster than tsc
   },
 };
 
 export default config;
 ```
 
-### release.config.ts
+See [check.config.ts](./check.config.ts) for complete example with all options.
 
-Create `release.config.ts` for release automation:
+## What Gets Checked
 
-```typescript
-import type { ReleaseFileConfig } from "vibe-check/system/release-tool/definition";
+### Oxlint (Rust-powered)
+- 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
 
-const releaseConfig: ReleaseFileConfig = {
-  packageManager: "bun", // or "npm", "yarn", "pnpm"
-  globalVersion: "1.0.0", // Synchronized version
+### ESLint (Optional)
+- 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
 
-  branch: {
-    main: "main",
-    develop: "dev",
-    allowNonMain: false,
-  },
+### TypeScript
+- Full type checking with tsgo or tsc
+- Strict type rules (optional)
 
-  packages: [
-    {
-      directory: "./",
-      updateDeps: true,
-      typecheck: "bun run vibe check",
-      build: true,
-
-      release: {
-        tagPrefix: "v",
-
-        git: {
-          skipPush: false,
-          skipTag: false,
-          commitMessage: "chore(release): ${version}",
-          remote: "origin",
-        },
-
-        npm: {
-          enabled: true,
-          access: "public",
-          provenance: true,
-        },
-
-        changelog: {
-          enabled: true,
-          file: "CHANGELOG.md",
-        },
-      },
-    },
-  ],
-};
+All checks run **in parallel** for maximum speed.
+
+## MCP Server
 
-export default releaseConfig;
+Configure in `.mcp.json` (created by `vibe config-create`):
+
+```json
+{
+  "mcpServers": {
+    "vibe": {
+      "command": "npx",
+      "args": ["@next-vibe/checker", "mcp"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
 ```
 
-## Advanced Usage
+The MCP server exposes:
+- `check` - Run comprehensive code quality checks
 
-### Custom Rules
+Compatible with any MCP client.
 
-Customize linting rules in `check.config.ts`:
+## Usage in Projects
 
-```typescript
-const config: CheckConfig = {
-  oxlint: {
-    enabled: true,
-    rules: {
-      "no-console": "error",
-      "no-debugger": "error",
-      "typescript/no-explicit-any": "error",
-    },
-    ignorePatterns: ["dist", "node_modules", ".next"],
-  },
-};
+### With npm Scripts
+
+If you selected package.json update during `config-create`:
+
+```json
+{
+  "scripts": {
+    "check": "vibe check",
+    "lint": "vibe check",
+    "typecheck": "vibe check"
+  }
+}
 ```
 
-### CI/CD Integration
+Then run:
+```bash
+npm run check
+```
+
+### Without Global Install
 
-#### GitHub Actions
+```bash
+npx @next-vibe/checker check
+```
+
+## CI/CD Integration
+
+### GitHub Actions
 
 ```yaml
 name: Code Quality
-
 on: [push, pull_request]
 
 jobs:
@@ -285,173 +236,181 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bun vibe check
+      - uses: actions/setup-node@v4
+      - run: npm install
+      - run: npm run check
 ```
 
-#### GitLab CI
+### GitLab CI
 
 ```yaml
 check:
-  image: oven/bun:latest
+  image: node:18
   script:
-    - bun install
-    - bun vibe check
+    - npm install
+    - npm run check
 ```
 
-### Programmatic Usage
+## Caching
 
-```typescript
-import { vibeCheck } from "vibe-check/system/check/vibe-check/repository";
-import { EndpointLogger } from "vibe-check/system/unified-interface/shared/logger/endpoint";
+The checker uses caching to speed up subsequent runs:
 
-const logger = new EndpointLogger({ level: "info" });
+- **Oxlint cache**: `.tmp/oxlint-cache`
+- **ESLint cache**: `.tmp/eslint-cache`
 
-const result = await vibeCheck.execute(
-  {
-    path: "./src",
-    fix: true,
-    skipTypecheck: false,
-  },
-  logger,
-);
+Cache directories are created automatically. Add `.tmp/` to your `.gitignore`.
 
-if (!result.success) {
-  console.error("Check failed:", result.data.issues);
-  process.exit(1);
-}
-```
+On first run (cold cache), checks are slower. Subsequent runs are significantly faster.
 
-## MCP Server Setup
+## Migrating from Existing Linters
 
-### Claude Desktop Configuration
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "vibe-check": {
-      "command": "bun",
-      "args": ["vibe", "mcp"]
-    }
-  }
-}
-```
+If you have existing ESLint, Prettier, or other linter configurations, use this AI agent prompt to migrate cleanly to vibe-check. The agent will port your custom rules to **Oxlint plugins** (preferred, faster) or ESLint where necessary.
 
-### Available MCP Tools
+### AI Agent Migration Prompt
 
-- `check_code_quality` - Run comprehensive code quality checks
-- `fix_code_issues` - Auto-fix linting and formatting issues
-- `analyze_typescript` - Deep TypeScript analysis
-- `get_lint_config` - View current linting configuration
+Copy and paste this into your AI agent (Claude, Cursor, etc.):
 
-## Performance
-
-### Benchmark Results
-
-Tested on a typical Next.js project (500 files, 50k LoC):
-
-| Tool      | Time   | Files/sec |
-| --------- | ------ | --------- |
-| Oxlint    | 1.2s   | ~417      |
-| ESLint    | 3.5s   | ~143      |
-| TypeScript| 2.8s   | ~179      |
-| **Total** | **3.9s** | **~128** |
-
-*Parallel execution ensures total time ≈ slowest check, not sum of all checks*
-
-### Optimization Tips
-
-1. **Use tsgo**: 2-3x faster than `tsc`
-2. **Enable caching**: Reuse results across runs
-3. **Parallel workers**: Auto-scales to CPU cores
-4. **Incremental checks**: Only check changed files
-
-## Troubleshooting
-
-### Common Issues
-
-**Q: "Config file not found"**
-```bash
-vibe check --create-config
 ```
-
-**Q: "Oxlint fails to parse config"**
-- Ensure you're using `ignorePatterns` not `ignores`
-- Check schema URL: `./node_modules/oxlint/configuration_schema.json`
-
-**Q: "Type checking is slow"**
-```typescript
-// In check.config.ts
-typecheck: {
-  enabled: true,
-  useTsgo: true, // Enable tsgo instead of tsc
-}
+I need to migrate my project to @next-vibe/checker and port all existing linting configurations.
+
+PROJECT CONTEXT:
+- Current linters: [list your linters: ESLint, Prettier, TSLint, etc.]
+- Custom rules: [describe any custom rules you have]
+- Config files: [list: .eslintrc.js, .prettierrc, etc.]
+
+MIGRATION REQUIREMENTS:
+
+1. INSTALL & SETUP
+   - Install: npm install --save-dev @next-vibe/checker
+   - Run: vibe config-create (interactive setup)
+   - Select all relevant options (React, Next.js, i18n, etc.)
+
+2. PORT CUSTOM RULES TO OXLINT PLUGINS (PREFERRED)
+   - Analyze my existing custom ESLint rules
+   - Create Oxlint plugins as TypeScript files in oxlint-plugins/
+   - Follow the pattern from check.config.ts jsPlugins configuration
+   - Oxlint plugins are FASTER than ESLint - prefer this approach
+   - Only use ESLint for rules that absolutely cannot be implemented in Oxlint
+
+3. OXLINT PLUGIN STRUCTURE
+   Each plugin should be a TypeScript file that exports rules:
+   ```typescript
+   // oxlint-plugins/my-custom-rule.ts
+   export default {
+     rules: {
+       'my-rule-name': {
+         create(context) {
+           // Rule implementation
+         }
+       }
+     }
+   };
+   ```
+
+   Register in check.config.ts:
+   ```typescript
+   jsPlugins: [
+     "oxlint-plugins/my-custom-rule.ts"
+   ]
+   ```
+
+4. UPDATE check.config.ts
+   - Port all rule configurations from old config files
+   - Map ESLint rules to equivalent Oxlint rules where possible
+   - Configure custom Oxlint plugins
+   - Only add ESLint rules that have no Oxlint equivalent
+   - Set appropriate severity levels (error/warn)
+
+5. CLEAN UP OLD CONFIGS
+   - Remove old config files: .eslintrc.*, .prettierrc, etc.
+   - Remove old linter packages from package.json
+   - Update package.json scripts to use vibe check
+   - Remove old linter-specific ignore files
+
+6. TEST THE MIGRATION
+   - Run: vibe check
+   - Verify all custom rules are working
+   - Test auto-fix functionality
+   - Compare results with old linter to ensure nothing is missed
+   - Run on a few test files with known issues
+   - Verify TypeScript checking works correctly
+
+7. VERIFY CUSTOM RULES
+   - Create test files that should trigger each custom rule
+   - Confirm rules are enforced correctly
+   - Test that auto-fix works for fixable rules
+   - Document any rules that couldn't be migrated and why
+
+8. UPDATE DOCUMENTATION
+   - Update project README with new lint commands
+   - Document any custom Oxlint plugins created
+   - Add notes about which rules are Oxlint vs ESLint
+
+PREFERENCES:
+- ALWAYS prefer Oxlint plugins over ESLint (much faster)
+- Use ESLint only when absolutely necessary
+- Maintain the same strictness level as before
+- Preserve all custom rule logic
+- Enable auto-fix where possible
+
+OUTPUT REQUIREMENTS:
+- List of all custom Oxlint plugins created
+- Explanation of which ESLint rules couldn't be ported and why
+- Summary of migration changes
+- Test results showing rules work correctly
+- Any recommendations for further optimization
+
+Please proceed with the migration step by step, asking for clarification if needed.
 ```
 
-**Q: "Release tool doesn't bump version correctly"**
-- Ensure `globalVersion` in `release.config.ts` matches your package.json
-- Version increments work from max(git tag, configured version)
+### After Migration
 
-### Debug Mode
+1. **Verify everything works:**
+   ```bash
+   vibe check
+   ```
 
-```bash
-vibe check --debug
-```
+2. **Test on specific files:**
+   ```bash
+   vibe check src/problematic-file.ts
+   ```
 
-Shows detailed execution logs, file discovery, and rule evaluation.
+3. **Check CI/CD:**
+   Update your CI configuration to use `npm run check`
 
-## Contributing
+4. **Commit changes:**
+   ```bash
+   git add .
+   git commit -m "Migrate to @next-vibe/checker with custom Oxlint plugins"
+   ```
 
-Contributions are welcome! This project is built with:
+### Oxlint Plugin Resources
 
-- **Bun** - Fast JavaScript runtime
-- **TypeScript** - Type safety
-- **Oxlint** - Rust-based linter
-- **Next.js** - Framework patterns
+- See `oxlint-plugins/` directory in this repository for examples
+- Oxlint plugins are TypeScript files that export rule definitions
+- Much faster than ESLint (Rust-powered execution)
+- Full access to AST for powerful custom rules
 
-### Development Setup
+## Contributing
+
+This project lives on the `vibe-check` branch:
 
 ```bash
-git clone https://github.com/maxbrandstatter/next-vibe.git
+git clone https://github.com/techfreaque/next-vibe.git
 cd next-vibe
 git checkout vibe-check
 bun install
 bun vibe check
 ```
 
-### Running Tests
-
-```bash
-bun test
-```
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
 ## License
 
-GPL-3.0-only - see [LICENSE](LICENSE) for details.
-
-## Credits
-
-Created by **Max Brandstätter** ([@maxbrandstatter](https://github.com/maxbrandstatter))
-
-Built with contributions from:
-- Claude Code
-- Augment
-- t3.chat
-- Cursor
-
-### Special Thanks
-
-Tools that didn't make the cut (RIP):
-- ~~ChatGPT~~ (fired)
-- ~~Copilot~~ (fired)
-- ~~v0.dev~~ (fired)
-- ~~Devin~~ (fired)
-
----
+GPL-3.0-only - see [LICENSE](LICENSE)
 
-**Need help?** [Open an issue](https://github.com/maxbrandstatter/next-vibe/issues)
+## Links
 
-**Love vibe-check?** [Star the repo](https://github.com/maxbrandstatter/next-vibe) ⭐
+- [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)