Metadata-Version: 2.4
Name: branch-py
Version: 0.1.3
Summary: A Python CLI tool for static analysis of control flow complexity
Project-URL: Homepage, https://branch.nesalia.com
Project-URL: Repository, https://github.com/nesalia-inc/branch
Requires-Python: >=3.14
Requires-Dist: pytest>=8.0.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="public/banner.jpg" alt="Branch Logo" width="100%">
</p>

<h1 align="center">Branch</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/branch">
    <img src="https://img.shields.io/pypi/v/branch" alt="PyPI Version">
  </a>
  <a href="https://github.com/nesalia-inc/branch/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/nesalia-inc/branch/test?label=tests" alt="Tests">
  </a>
  <a href="https://github.com/nesalia-inc/branch/actions">
    <img src="https://img.shields.io/badge/coverage-97%25-brightgreen" alt="Coverage">
  </a>
  <a href="https://github.com/nesalia-inc/branch/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/nesalia-inc/branch" alt="License">
  </a>
</p>

> A Python CLI tool for static analysis of control flow complexity. Quantifies test surface area through N-Path complexity calculation, models short-circuit evaluation of boolean expressions, and provides mathematically-proven refactoring recommendations.

## Requirements

- Python 3.14+
- typer
- pytest

## Installation

```bash
# Using uv (recommended)
uv add branch

# Or using pip
pip install branch

# From source
git clone https://github.com/nesalia-inc/branch.git
cd branch
uv build
uv add -e .
```

## Quick Start

```bash
# Analyze a Python file
branch analyze your_code.py

# With detailed explanation
branch analyze your_code.py --explain

# JSON output for CI
branch analyze your_code.py --json

# Filter by minimum improvement threshold
branch analyze your_code.py --explain --min-gain 50
```

## Example Output

```
$ branch analyze examples/patterns/c1_duplicate_outcomes.py --explain

[C1] Duplicate Outcomes [MECHANICAL]
  Both branches return identical value

  Impact: N-Path 2 -> 1 (50.0% reduction)
         Depth 1 -> 0

Impact Summary:
  Functions analyzed: 4
  Critical issues: 0
  Warning issues: 0
  Pattern suggestions: 3
```

## Features

- **N-Path Complexity** - Mathematical path counting through boolean short-circuit evaluation
- **Virtual Refactoring Engine** - Proof-based transformation suggestions
- **Pattern Detection** - Automated detection of refactoring opportunities:
  - C1: Duplicate Outcomes (`if a: return X else: return X` → `return X`)
  - A2: Arrow Code (deep nesting → early returns)
  - D1: If/Elif Chain → Dispatch Map
- **Two-Phase Analysis** - Fast AST scan with selective deep CFG analysis
- **Structured CFG** - Preserves elif nesting, handles short-circuit correctly
- **Health Score** - Combined metric: `H = (NP * W1) + (SD * W2)`

## Architecture

```
Source Code → AST → CFG → IR → Analysis → Transformations → Output
```

### Two-Phase Analysis

1. **Phase 1: Fast AST Scan** (O(n)) - Estimates complexity, triggers Phase 2 only if thresholds exceeded
2. **Phase 2: Full CFG Analysis** - Structured CFG, exact N-Path calculation, virtual refactoring

### Key Metrics

| Metric | Description |
|--------|-------------|
| **N-Path (NP)** | Total execution paths (maps to test cases needed) |
| **Structural Depth (SD)** | Nesting depth (maps to cognitive complexity) |

## Documentation

See the `docs/` folder for detailed technical specifications:

- [docs/2_architecture/ARCHITECTURE.md](docs/2_architecture/ARCHITECTURE.md) - Full architecture specification
- [docs/4_n_path_calculation/N-PATH-CALCULATION.md](docs/4_n_path_calculation/N-PATH-CALCULATION.md) - Path counting formulas
- [docs/7_virtual_refactoring/VIRTUAL_REFACTORING_ENGINE.md](docs/7_virtual_refactoring/VIRTUAL_REFACTORING_ENGINE.md) - Virtual refactoring engine
- [docs/5_atomic_patterns/ATOMIC_REFACTORING_PATTERNS.md](docs/5_atomic_patterns/ATOMIC_REFACTORING_PATTERNS.md) - Pattern catalog

## CLI Commands

```bash
branch analyze <file.py>        # Analyze a Python file
branch analyze <file.py> --explain  # Detailed output with transformation proofs
branch analyze <file.py> --json    # JSON output for CI integration
branch analyze <file.py> --min-gain <N>  # Filter by min improvement %
branch ping                     # Check installation
```

## Pattern Confidence Tags

| Tag | Meaning |
|-----|---------|
| `MECHANICAL` | Exact match, always safe to apply |
| `PROBABILISTIC` | Pattern match may not apply in all cases |
| `HEURISTIC` | Suggestion based on heuristics |

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Author

- **Nesalia Inc.**

## Support

For bug reports or feature requests, please open an issue on GitHub.

## License

MIT License - see the [LICENSE](LICENSE) file for details.
