□ Test suite passa al 100%?
□ Coverage >= 80% su codice target? (se no → scrivi test PRIMA)
□ Golden outputs catturati per edge cases critici?
□ Static analysis baseline salvata?

□ flake8 --select=F821,E999 → 0 errori?
□ pytest -x → tutti passano?
□ Comportamento invariato? (spot check 1 edge case)

→ STOP → REVERT → ANALYZE → FIX APPROACH → RETRY

⛔ QUALSIASI REGRESSIONE = FALLIMENTO TOTALE DEL REFACTORING ⛔

undefined

```python

def get_by_id(self, user_id: int) -> Optional[User]:
    # Encapsulated state, clear responsibility
    pass

def process_user(self, user_id: int):
    # Dependency injection, testable, clear
    pass

**If you find script-like code → Transformation to OOP is MANDATORY, not optional!**

1. **Read the entire codebase section** being refactored to understand context
2. **Identify readability issues** using the anti-patterns reference (see `references/anti-patterns.md`):
   - **CRITICAL**: Check for script-like/procedural code (anti-pattern #1) - global state, scattered functions, no clear structure
   - **CRITICAL**: Check for God Objects/Classes (anti-pattern #2) - classes doing too much
   - Complex nested conditionals, long functions, magic numbers, cryptic names, etc.
3. **Assess OOP architecture** (see `references/oop_principles.md`):
   - Is code organized in proper classes and modules?
   - Is there global state that should be encapsulated?
   - Are responsibilities properly separated (models, repositories, services)?
   - Are SOLID principles followed?
   - Is dependency injection used instead of hard-coded dependencies?
4. **Measure current metrics**:
   - Cyclomatic complexity per function (use `scripts/measure_complexity.py`)
   - Function length (lines of code)
   - Documentation coverage (docstrings, type hints)
   - Nesting depth
5. **Run flake8 analysis** for comprehensive code quality assessment:
   ```bash
   python scripts/analyze_with_flake8.py <target> \
       --output before_flake8.json \
       --html before_flake8.html

undefined

**Step 3: CREATE migration checklist**
```markdown

**Step 4: MIGRATE one usage at a time**
- Update ONE usage to use new structure
- Check off in migration checklist
- Run static analysis: `flake8 <file> --select=F821,E0602`
- Run tests
- Commit with message: "refactor: migrate broadcast_sse_event to SSEManagerService (1/6)"

**Step 5: VERIFY complete migration**
- Checklist shows 6/6 complete
- Re-run original grep searches - should find ZERO matches (except in new code)
- Run static analysis one final time before removal

**Step 6: REMOVE old code (ONLY after 100% migration verified)**
- Comment out old code first (safety net)
- Run static analysis: `flake8 <file> --select=F821,E0602` - MUST show zero errors
- Run full test suite - MUST pass 100%
- If both pass, permanently delete commented code
- Commit with message: "refactor: remove obsolete sse_connections global (migration complete)"

undefined

**Extract Method** - Split large functions into focused units:
```python

**Replace Complex Conditionals** - Use named boolean methods:
```python

undefined

undefined

**Match Statement** (Python 3.10+) - Switch conta UNA VOLTA:
```python

**Extract Method** - Resetta il nesting counter (pattern più potente!):
```python

**Named Boolean Conditions** - Chiarisce condizioni complesse:
```python

**Reduce Nesting** - Maximum 3 levels deep:
```python

undefined

def calculate_discount(price: float, user_tier: str) -> float:
    """Calculate discount amount based on user tier.

    Args:
        price: Original price before discount
        user_tier: User membership tier ('bronze', 'silver', 'gold')

    Returns:
        Discount amount to subtract from price

    Raises:
        ValueError: If user_tier is not recognized
    """

"""User authentication and authorization module.

This module handles user login, session management, and permission
checking. Depends on the database module for user persistence and
the crypto module for password hashing.
"""

undefined

**Type Hints** - All public APIs and complex internals:
```python
from typing import List, Optional, Dict

def process_users(
    users: List[User],
    filters: Optional[Dict[str, Any]] = None
) -> List[ProcessedUser]:
    ...

undefined

**Group Related Functionality:**
```python

**Separate Concerns:**
```python

**Consistent Abstraction Levels:**
```python

undefined

undefined

def get_by_id(self, user_id: int) -> Optional[User]:
    # Encapsulated state
    pass

**Group Related Functions into Classes:**
```python

**Create Domain Models:**
```python

def is_valid(self) -> bool:
    return '@' in self.email and self.status == UserStatus.ACTIVE

**Apply Dependency Injection:**
```python

def process_user(self, user_id: int):
    user = self._user_repo.get_by_id(user_id)
    self._db_repo.save_user(user)

**Organize into Layered Architecture:**

**Key OOP Principles to Apply:**
- **Single Responsibility** (SRP): One class, one responsibility
- **Open/Closed** (OCP): Open for extension, closed for modification
- **Liskov Substitution** (LSP): Subtypes must be substitutable
- **Interface Segregation** (ISP): Many specific interfaces over one general
- **Dependency Inversion** (DIP): Depend on abstractions, not concretions

See `references/oop_principles.md` for comprehensive guide with examples.

undefined

**Prevention Protocol:**
1. **BEFORE removing any code element**, run comprehensive searches:
   ```bash
   # Search for variable name
   grep -r "sse_connections" --include="*.py"

   # Search for related patterns
   grep -r "_sse_lock\|sse_global_connections\|sse_event_buffer" --include="*.py"

   # Search for common access patterns
   grep -r "sse_connections\[.*\]\|sse_connections\..*" --include="*.py"

undefined

undefined

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = [
    "E", "W",     # pycodestyle
    "F",          # Pyflakes
    "C90",        # McCabe cyclomatic complexity
    "B",          # flake8-bugbear
    "SIM",        # flake8-simplify
    "N",          # pep8-naming
    "UP",         # pyupgrade
    "I",          # isort
]

[tool.ruff.lint.mccabe]
max-complexity = 10  # Cyclomatic complexity

[tool.complexipy]
paths = ["src"]
max-complexity-allowed = 15    # SonarQube default
exclude = ["tests", "migrations"]

undefined

undefined

from complexipy import file_complexity, code_complexity

undefined

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/rohaquinlop/complexipy-pre-commit
    rev: v3.0.0
    hooks:
      - id: complexipy
        args: [--max-complexity-allowed, "15"]

- name: Ruff
  uses: astral-sh/ruff-action@v1

- name: Cognitive Complexity
  uses: rohaquinlop/complexipy-action@v2
  with:
    paths: src/
    max_complexity_allowed: 15

undefined

**Integrazione CI per trend check:**
```bash

undefined

undefined

**Strategia "Changed Files Only":**
```bash

undefined

python scripts/measure_complexity.py <file_path>

python scripts/check_documentation.py <file_path>

python scripts/compare_metrics.py <before_file> <after_file>

python scripts/benchmark_changes.py <before_file> <after_file> <test_module>

python scripts/analyze_with_flake8.py <file_or_directory> \
    --output report.json \
    --html report.html

pip install flake8 flake8-bugbear flake8-simplify \
    flake8-cognitive-complexity pep8-naming flake8-docstrings

pip install flake8 flake8-bugbear flake8-simplify \
    flake8-cognitive-complexity pep8-naming flake8-docstrings \
    flake8-comprehensions flake8-expression-complexity \
    flake8-functions flake8-variables-names tryceratops \
    flake8-builtins flake8-eradicate flake8-unused-arguments \
    flake8-annotations pydoclint flake8-spellcheck

python scripts/compare_flake8_reports.py before.json after.json \
    --html comparison.html

undefined

undefined