branch-py 0.1.3

A Python CLI tool for static analysis of control flow complexity

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

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

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