vibequal

Vibequal

A CLI tool for analyzing code quality in TypeScript and JavaScript projects. Vibequal measures architectural coupling, code complexity, and maintainability to help identify problem areas in your codebase.

Installation

npm install
npm run build
npm link  # Makes 'vibequal' available globally

Usage

vibequal <directory> [options]

Options

Option	Description
-v, --verbose	Show detailed metrics for all modules
-j, --json	Output results as JSON
-t, --tsconfig <path>	Path to tsconfig.json file
--no-complexity	Skip complexity analysis

Examples

vibequal ./src                    # Analyze src directory
vibequal ./src -v                 # Verbose output with all module details
vibequal ./src -j                 # JSON output for CI integration
vibequal ./src -t ./tsconfig.json # Specify custom tsconfig

Analyses

Coupling Metrics

Vibequal analyzes module dependencies to calculate coupling metrics based on Robert C. Martin's stability metrics.

Metric	Description
Afferent Coupling (Ca)	Number of modules that depend on this module (incoming dependencies)
Efferent Coupling (Ce)	Number of modules this module depends on (outgoing dependencies)
Instability (I)	Ratio of efferent to total coupling: Ce / (Ca + Ce). Range 0-1, where 0 = maximally stable, 1 = maximally unstable

The report highlights:

• Hub Modules: Modules with the highest afferent coupling (most depended upon)
• Most Coupled Modules: Modules with the highest total coupling (Ca + Ce)

Dependency Issues

Issue	Description
Circular Dependencies	Chains of modules that depend on each other in a cycle (A → B → C → A)
Orphan Modules	Modules with no incoming dependencies that may indicate dead code. Entry points and type definitions are filtered out automatically.

Complexity Metrics

Function-level complexity analysis using the TypeScript compiler API.

Metric	Description	Thresholds
Maintainability Index	Composite score (0-100) based on Halstead volume, cyclomatic complexity, and lines of code. Higher is better.	< 20 poor, < 50 moderate, >= 50 good
Cyclomatic Complexity	Number of linearly independent paths through the code. Counts decision points (if, for, while, case, catch, ternary, &&, ||, ??)	> 10 high, > 5 moderate
Cognitive Complexity	SonarSource's metric measuring how difficult code is to understand. Accounts for nesting depth and control flow breaks.	> 15 high, > 8 moderate
Max Nesting Depth	Deepest level of nested control structures	> 3 high, > 2 moderate
Arity	Number of function parameters	> 4 high, > 2 moderate
Fan-out	Number of unique external function/constructor calls	> 10 high, > 5 moderate

Class Cohesion

Metric	Description
LCOM4	Lack of Cohesion in Methods. Counts connected components of methods that share fields or call each other. A value > 1 suggests the class has multiple responsibilities and should be split.

Statistical Aggregation

For each complexity metric, Vibequal reports:

• Average: Mean value across all functions
• Median: Middle value (less affected by outliers)
• P95/P5: 95th percentile for complexity metrics, 5th percentile for maintainability (identifies worst cases)

Report Sections

• Summary: Total modules, dependencies, circular dependencies, and orphan modules
• Coupling Metrics: Average Ca, Ce, and Instability across the codebase
• Circular Dependencies: List of all dependency cycles
• Orphan Modules: Potential dead code (excludes entry points)
• Hub Modules: Most depended-upon modules (change with caution)
• Most Coupled Modules: Modules with highest total coupling
• Complexity & Maintainability: Statistical summary of all complexity metrics
• Refactor Candidates: Top 10 functions with lowest maintainability / highest complexity
• Low Cohesion Classes: Classes with LCOM4 > 1 that may need splitting

JSON Output

Use -j for machine-readable output suitable for CI pipelines:

vibequal ./src -j > report.json

The JSON includes all metrics, allowing integration with quality gates and trend tracking.

Claude Code Plugin

Vibequal includes a /quality slash command for Claude Code that analyzes your codebase and provides actionable insights.

Installation

• Install vibequal globally:

  npm install -g vibequal
  # or from source:
  git clone <repo>
  cd vibequal && npm install && npm run build && npm link
  

• Copy the .claude/commands/ directory to your project:

  cp -r /path/to/vibequal/.claude/commands/ your-project/.claude/commands/
  

  Or to install globally for all projects:

  cp -r /path/to/vibequal/.claude/commands/ ~/.claude/commands/
  

Usage

In Claude Code, run:

/quality

Or analyze a specific directory:

/quality src/

Claude will run the analysis and provide:

• Health overview (modules, circular deps, orphans)
• Coupling issues and hub modules
• Complexity hotspots and refactor candidates
• Actionable recommendations

Supported File Types

• TypeScript: .ts, .tsx
• JavaScript: .js, .jsx, .mjs, .cjs

Automatically excludes:

• node_modules/
• dist/, build/
• Test files (*.test.*, *.spec.*)
• Type declarations (*.d.ts)

License

ISC