vibe-check

Automated codebase health scanner that detects pathologies common in AI-generated code.

Install

npm install -g @lacow/vibe-check

Usage

# Scan current directory
vibe-check .

# JSON output
vibe-check . --json

# CI mode — exit code 1 if score < threshold
vibe-check . --ci --threshold 7

# Run specific rules only
vibe-check . --rules hallucinated-imports,dead-code-paths

# List all available rules
vibe-check --list-rules

# Use a custom config file
vibe-check . --config ./custom-config.json

# Suppress info-level findings
vibe-check . --quiet

# Exclude files ad-hoc
vibe-check . --ignore-pattern "generated/**"

# Generate a .vibecheck config file
vibe-check --init

Rules

| Rule | Category | Severity | Description | |------|----------|----------|-------------| | hallucinated-imports | phantom-deps | critical | Detect imports of packages not listed in package.json | | phantom-peer-deps | phantom-deps | warning | Detect imports that rely on peer dependencies instead of declared ones | | dependency-bloat | dependencies | warning | Detects large utility libraries that could be replaced with lighter alternatives | | cross-file-duplication | duplication | warning | Detects copy-pasted logic across different files | | inconsistent-error-handling | consistency | warning | Detects async functions without error handling | | inconsistent-naming | consistency | info | Detects mixed naming conventions within the same file | | orphaned-exports | dead-code | warning | Finds exported symbols that are never imported anywhere in the project | | dead-code-paths | dead-code | warning | Detects unreachable code after return, throw, or process.exit() | | unused-dependencies | dead-code | warning | Finds packages declared in dependencies but never imported in source files | | over-abstraction | architecture | info | Detects single-use abstractions common in AI-generated code | | type-assertion-overuse | type-safety | warning | Detects excessive use of type assertions that bypass type checking | | hardcoded-secrets | security | critical | Detect hardcoded secrets and sensitive credentials in source code | | todo-accumulation | maintenance | info | Detects accumulated TODO/FIXME/HACK comments | | console-remnants | maintenance | info | Detects leftover console.log statements in production code | | commented-out-code | dead-code | warning | Detects blocks of commented-out code |

Programmatic API

import { scan } from '@lacow/vibe-check';

const result = await scan({ path: './my-project' });

console.log(result.score);      // 0-10
console.log(result.findings);   // Finding[]
console.log(result.summary);    // { total, critical, warning, info }

License

MIT