vibelexity 0.3.0

Cognitive complexity analyzer for Python, TypeScript, and Go source files

Vibelexity

Cognitive complexity analyzer for Python, TypeScript, and Go source files.

Features

• Cognitive Complexity: Measures how difficult code is to understand, accounting for nesting depth and control flow breaks
• Halstead Metrics: Vocabulary volume, effort, time, and bug predictions
• NPath Complexity: Number of acyclic execution paths through code
• Cyclomatic Complexity: Linearly independent paths through decisions
• Maintainability Index (MI): Composite measure of code maintainability (0-100)
• Logic Density Index (LDI): Average nesting depth across code
• Circular Dependencies: Detects import cycles between modules
• Dead Code: Finds unused functions, variables, and imports
• Code Duplication: Identifies exact and parametric clones
• Call Graph: Generates DOT format call graphs

Installation

# Using uv (recommended)
uvx vibelexity <directory>

# Or for development
git clone https://github.com/ozozozd/vibelexity.git
cd vibelexity
uv sync
uv run vibelexity .

Usage

vibelexity <directory> [options]

Options

Option	Description
--json	Output results as JSON
--show-dupes	Show detailed code duplication sites
--perf	Show timing information for each metric
--show-dead	Show all dead code violations
--show-bad-patterns	Show detailed pattern violations list
--show-circulars	Show circular import cycle details
--ts-module-resolution	TypeScript module resolution mode (node, node16, nodenext, bundler)
--algorithm	Cycle detection algorithm (dfs, tarjan)
--call-graph	Generate call graph analysis (DOT format)
--show-fatties	Show detailed fat files and functions list

Examples

# Analyze current directory
vibelexity .

# Analyze specific directory
vibelexity ./src

# JSON output for CI
vibelexity . --json

# Show circular import details
vibelexity . --show-circulars

# Generate call graph
vibelexity . --call-graph > graph.dot

Metrics Explained

Complexity Metrics

Metric	Good	Concern	Critical
Cognitive Complexity	≤8	9-15	>15
Halstead Volume	<500	500-1000	>1000
Cyclomatic Complexity	≤5	6-10	>10
NPath Complexity	≤50	51-200	>200
Maintainability Index (MI)	≥70	40-69	<40
Logic Density Index (LDI)	≤20	21-40	>40

Code Health Indicators

• Circular Dependencies: Import cycles that create tight coupling
• Dead Code: Unused functions, variables, and imports
• Code Duplication: Exact and parameterized clones
• Fat Functions: Functions with high complexity or many calls
• Wide Functions: Functions with >5 parameters

Output Format

The default text output includes:

1. Project Summary: total modules, functions, and lines of code
2. Statistics: Average, median, P95, P99 for all metrics
3. Circular Dependencies: Number and statistics of import cycles
4. Pattern Violations: Code smell categories
5. Code Duplication: Duplicate lines and functions
6. Dead Code: Count of unused code
7. Fatness Metrics: Fat files and functions
8. Refactor Candidates: Top 10 functions needing refactoring

Claude Code Plugin

Use the /vibelexity slash command in Claude Code to analyze your codebase.

Installation

See vibelexity-claude-plugin for installation instructions.

Usage

In Claude Code, run:

/vibelexity

Or analyze a specific directory:

/vibelexity path/to/directory

The plugin automatically installs vibelexity if needed (prefers uvx with fallback to shell installer).

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run specific test
uv run pytest tests/test_cognitive/test_python.py::test_simple_function -v

# Check code style
uv run ruff check src/

# Format code
uv run ruff format src/

License

ISC