Class OptionCountSummary

explainshell/extraction/report.py:59–123

Distribution of per-page option counts across successful extractions.

class OptionCountSummary(BaseModel):
    """Distribution of per-page option counts across successful extractions."""

    n: int
    total: int
    mean: float
    median: float
    p90: float
    max: int
    # Stable bucket order. Values are file counts.
    buckets: dict[str, int]

    @classmethod
    def empty(cls) -> OptionCountSummary:
        """Zero-everything summary, used when the histogram is unavailable.

        Old reports written before option-count tracking existed migrate
        to this shape rather than ``null`` so analysis tools can rely on
        the field always being a populated struct.
        """
        return cls(
            n=0,
            total=0,
            mean=0.0,
            median=0.0,
            p90=0.0,
            max=0,
            buckets={"0": 0, "1-5": 0, "6-15": 0, "16-50": 0, "50+": 0},
        )

    @classmethod
    def from_counts(cls, counts: list[int]) -> OptionCountSummary:
        """Build a summary from a list of per-file option counts.

        Empty input yields :meth:`empty` rather than ``None`` — the field
        is always present in the report.
        """
        if not counts:
            return cls.empty()
        buckets = {"0": 0, "1-5": 0, "6-15": 0, "16-50": 0, "50+": 0}
        for c in counts:
            if c == 0:
                buckets["0"] += 1
            elif c <= 5:
                buckets["1-5"] += 1
            elif c <= 15:
                buckets["6-15"] += 1
            elif c <= 50:
                buckets["16-50"] += 1
            else:
                buckets["50+"] += 1
        # statistics.quantiles requires n >= 2 data points.
        if len(counts) >= 2:
            p90 = statistics.quantiles(counts, n=10)[8]
        else:
            p90 = float(counts[0])
        return cls(
            n=len(counts),