report.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/mutation/report.py
 
"""
Purpose
-------
Render mutation results for humans without editorialising the numbers.
 
Responsibilities
----------------
- Render the enumeration-only listing used by ``--list``.
- Render totals, the kill rate, and one description per surviving mutant.
- Name the mutants that timed out, which no test run judged either way.
 
Diagnostics
-----------
Domain: OCT-MUTATION
Levels:
    L2 - lifecycle
    L3 - rendering details
    L4 - deep tracing
 
Contracts
---------
- Output is ASCII only, so a cp1252 console cannot turn a report into a crash.
- v1 is report-only: the rendered text states no verdict and no threshold.
- A survivor is described by its id, its source line, and its before/after form.
 
Dependencies
------------
- oct.mutation.engine (mutant records)
- oct.mutation.runner (run results)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Pure string rendering with no runtime lifecycle"
# OCT-LINT: disable-file=dbg_import reason="Pure string rendering has no diagnostic dependency"
 
from __future__ import annotations
 
from typing import Sequence
 
from oct.mutation.engine import Mutant
from oct.mutation.runner import STATUS_TIMEOUT, MutantOutcome, RunReport
 
 
def render_list(mutants: Sequence[Mutant], target: str) -> str:
    """Render the enumeration produced by ``--list``, which runs nothing."""
    lines = [f"{len(mutants)} mutant(s) in {target}; nothing was run."]
    lines.extend(
        f"  {mutant.mutant_id}  line {mutant.lineno}: "
        f"{mutant.before} -> {mutant.after}"
        for mutant in mutants
    )
    return "\n".join(lines)
 
 
def render_human(report: RunReport) -> str:
    """Render totals, the kill rate, survivors, and any unjudged timeouts."""
    lines = [
        f"Mutation report for {report.target}",
        f"  tests:    {report.tests}",
        f"  timeout:  {report.timeout_seconds}s per mutant",
        f"  mutants:  {report.total}"
        f"   killed {report.killed}"
        f"   survived {report.survived}"
        f"   timeout {report.timed_out}",
        f"  kill rate: {_format_rate(report.kill_rate)}"
        "  (report-only: v1 applies no threshold and gates nothing)",
        "",
    ]
    lines.extend(_render_survivors(report.survivors))
    timeouts = [item for item in report.outcomes if item.status == STATUS_TIMEOUT]
    if timeouts:
        lines.append("")
        lines.extend(_render_timeouts(timeouts))
    return "\n".join(lines)
 
 
def _render_survivors(survivors: Sequence[MutantOutcome]) -> list[str]:
    """Render one description per surviving mutant, or say there were none."""
    if not survivors:
        return ["Survivors: none."]
    lines = [f"Survivors ({len(survivors)}) - the tests did not notice these:"]
    for outcome in survivors:
        mutant = outcome.mutant
        lines.append(f"  {mutant.mutant_id}")
        lines.append(f"    line {mutant.lineno}: {mutant.line_text}")
        lines.append(f"    -  {mutant.before}")
        lines.append(f"    +  {mutant.after}")
    return lines
 
 
def _render_timeouts(timeouts: Sequence[MutantOutcome]) -> list[str]:
    """Render the mutants that exceeded the timeout and were never judged."""
    lines = [
        f"Timed out ({len(timeouts)}) - neither killed nor survived; "
        "raise --timeout to judge these:"
    ]
    lines.extend(
        f"  {outcome.mutant.mutant_id}  line {outcome.mutant.lineno}: "
        f"{outcome.mutant.before} -> {outcome.mutant.after}"
        for outcome in timeouts
    )
    return lines
 
 
def _format_rate(rate: float | None) -> str:
    """Render the kill rate as a percentage, or ``n/a`` when nothing ran."""
    if rate is None:
        return "n/a"
    return f"{rate * 100:.1f}%"