vibelexity 0.3.0
Cognitive complexity analyzer for Python, TypeScript, and Go source files
Requires Python: >=3.11

# 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

```bash
# 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

```bash
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

```bash
# 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](https://github.com/ozozozd/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

```bash
# 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