vibecode-linter

Advanced TypeScript linter with Git integration, dependency analysis, and comprehensive error reporting.

🚀 Installation

Quick Start (Recommended)

npx @ton-ai-core/vibecode-linter@latest src/

Global Installation

npm install @ton-ai-core/vibecode-linter
npx @ton-ai-core/vibecode-linter src/

📖 Usage

CLI Usage

# Lint a directory
npx @ton-ai-core/vibecode-linter src/

# Lint a specific file
npx @ton-ai-core/vibecode-linter src/main.ts

📚 Programmatic Usage

Use vibecode-linter as a library in your Node.js projects:

import { runLinter } from '@ton-ai-core/vibecode-linter';

// Run linter with custom options
const exitCode = await runLinter({
  targetPath: 'src/',           // Path to lint
  maxClones: 5,                 // Max code duplicates to display
  width: 120,                   // Terminal width for formatting
  noFix: false,                 // Enable auto-fix (default)
  noPreflight: false,           // Run preflight checks (default)
  fixPeers: false,              // Don't fix peer dependencies (default)
});

if (exitCode === 0) {
  console.log('✅ No errors found!');
} else {
  console.log('❌ Linting errors detected');
  process.exit(1);
}

Available Exports:

// Main orchestrator
import { runLinter } from '@ton-ai-core/vibecode-linter';

// Types
import type {
  CLIOptions,
  ExitCode,
  LintMessage,
  LintMessageWithFile,
  ESLintMessage,
  BiomeMessage,
  TypeScriptMessage,
} from '@ton-ai-core/vibecode-linter';

// Pure utility functions
import {
  computeExitCode,
  getPriorityLevel,
  groupByLevel,
  isESLintMessage,
  isTypeScriptMessage,
} from '@ton-ai-core/vibecode-linter';

📊 Example Output

[ERROR] /home/user/TradingBot/src/telegram/bot.ts:78:30 @ton-ai-core/suggest-members/suggest-imports (ESLint) — Variable "Comman1dHandlers" is not defined. Did you mean:
  - CommandHandlers
  - console
  - Console

--- git diff (workspace, U=3) -------------------------
@@ -75,7 +75,7 @@ export class TelegramNotificationBot implements TelegramBot {
    75 |                         logger: options.logger,
    76 |                 });
    77 | 
-      |                 this.commandHandlers = new CommandHandlers({
+   78 |                 this.commandHandlers = new Comman1dHandlers({
                                                    ^^^^^^^^^^^^^^^^  
    79 |                         gateway: this.gateway,
    80 |                         dbManager: options.dbManager,
    81 |                         appConfig: options.config,
---------------------------------------------------------------

    --- git diff b001809..b1662a1 -- src/telegram/bot.ts | cat
    b1662a1 (2025-09-30) by skulidropek: устранение дубликатов
    b001809 (2025-09-28) by skulidropek: implement code review
    @@ -75,7 +75,7 @@
        73 | logger: options.logger,
        74 | });
        75 | 
    -   76 | this.handlers = new BaseHandlers({
    +   78 | this.commandHandlers = new CommandHandlers({
        79 | gateway: this.gateway,
    ---------------------------------------------------------------
    
    Full list: git log --follow -- src/telegram/bot.ts | cat

📊 Total: 16 errors (3 TypeScript, 5 ESLint, 8 Biome), 11 warnings.

🔧 Development Setup

Prerequisites

• Node.js >= 18.0.0
• Git repository

Installation

1. Clone and install dependencies:

git clone https://github.com/ton-ai-core/vibecode-linter.git
cd vibecode-linter
npm install

2. Install linter dependencies (from devDependencies):

# Install all linters used by vibecode-linter
npm install -D \
  @biomejs/[email protected] \
  @eslint-community/eslint-plugin-eslint-comments@^4.5.0 \
  @eslint/js@^9.35.0 \
  @typescript-eslint/eslint-plugin@^8.44.1 \
  @typescript-eslint/parser@^8.44.1 \
  eslint@^9.36.0 \
  typescript@^5.9.2

3. Build and test:

npm run build
npm run lint

⚙️ Configuration Files

Copy these configuration files to your project root:

• ESLint: eslint.config.mts
• Linter Priority: linter.config.json
• Biome: biome.json
• Duplicate Detection: .jscpd.json

✨ Features

• Git-aware error reporting - Shows git diff context for every error
• Commit history analysis - Displays changes that led to the error
• Dependency-based ordering - Sorts errors by definition→usage relationships
• Priority-based filtering - Configurable error severity levels
• Code duplication detection - Finds duplicate code across your project
• Auto-fix support - Automatically fixes lint errors where possible

🐛 Troubleshooting

"Missing required dependencies"

Install the required linters:

npm install -D eslint @biomejs/biome typescript

"No git repository found"

Make sure you're running inside a git repository:

git init
git add .
git commit -m "Initial commit"

"ESLint couldn't find config file"

Create an eslint.config.js file in your project root (see configuration examples above).

📄 License

MIT