Branch

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

# 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

# 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

Documentation

See the docs/ folder for detailed technical specifications:

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

CLI Commands

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

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 file for details.