metrics.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/complexity/metrics.py
 
"""
Purpose
-------
Calculate CRAP scores from cyclomatic complexity and statement coverage.
 
Responsibilities
----------------
- Apply the pinned CRAP formula without rounding measurements.
- Reject invalid complexity and coverage inputs.
 
Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - lifecycle
    L3 - calculation details
    L4 - deep tracing
 
Contracts
---------
- The formula is ``CC^2 * (1 - coverage)^3 + CC``.
- Complexity is a positive integer and coverage is in the inclusive range zero to one.
 
Dependencies
------------
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Pure deterministic arithmetic has no runtime lifecycle or diagnostic side effects"
# OCT-LINT: disable-file=dbg_import reason="Pure deterministic arithmetic has no diagnostic dependency"
 
from __future__ import annotations
 
 
def calculate_crap(complexity: int, coverage: float) -> float:
    """Return ``CC^2 * (1 - coverage)^3 + CC``.
 
    Complexity is a positive integer and coverage is a fraction in the
    inclusive range zero through one. Failing fast on invalid measurements
    prevents the reporting layer from presenting approximate scores.
    """
    if isinstance(complexity, bool) or not isinstance(complexity, int):
        raise TypeError("complexity must be an integer")
    if complexity < 1:
        raise ValueError("complexity must be at least 1")
    if not 0.0 <= coverage <= 1.0:
        raise ValueError("coverage must be between 0.0 and 1.0")
    uncovered = 1.0 - coverage
    return float(complexity**2 * uncovered**3 + complexity)