python-code-quality 0.1.4__py3-none-any.whl

py_cq/localtypes.py

@@ -0,0 +1,135 @@
+"""Utility classes for representing and aggregating results from static-analysis tools.
+
+This module defines dataclasses that capture tool configuration (`ToolConfig`), raw execution output (`RawResult`), parsed metrics (`ToolResult`), and a consolidated view of all tool results (`CombinedToolResults`).  It also provides an abstract `AbstractParser` that concrete parsers should subclass to convert a `RawResult` into a `ToolResult`.  Together these components enable parsing, combining, and serialising analysis metrics for downstream reporting and analysis."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolConfig:
+    """Represents the configuration for an analysis tool, including its name, command, parser class, context path, priority, and thresholds for warnings and errors."""
+
+    name: str  # e.g., "pytest", "coverage", "pydocstyle"
+    command: str  # The command to execute (can include placeholders)
+    parser_class: Callable  # Name of the parser class to use
+    context_path: str = ""  # Path to project or file
+    priority: int = 5  # 1=critical (compilation), 5=low (style)
+    warning_threshold: float = 0.7  # Yellow warning if below this
+    error_threshold: float = 0.5  # Red error if below this
+    run_in_target_env: bool = False  # If True, run in target project's env via uv
+    extra_deps: list[str] = field(default_factory=list)  # Extra deps to inject via uv --with
+
+
+@dataclass
+class RawResult:
+    """Represents the raw output from a tool execution.
+
+    Instances store the unprocessed data returned by a tool and can be
+    converted to a plain dictionary using :meth:`to_dict`."""
+
+    tool_name: str = ""
+    command: str = ""
+    stdout: str = ""
+    stderr: str = ""
+    return_code: int = 0
+    timestamp: str = ""  # For tracking when the analysis ran
+
+    def to_dict(self):
+        """Returns a dictionary containing the tool name, command, stdout, stderr, return code, and timestamp."""
+        return {
+            "tool_name": self.tool_name,
+            "command": self.command,
+            "stdout": self.stdout,
+            "stderr": self.stderr,
+            "return_code": self.return_code,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class ToolResult:
+    """Represents a parsed metric from a tool run.
+
+    This dataclass stores information about a metric extracted from a tool
+    execution, ensuring that the `details` attribute is always a dictionary.
+    It provides a `to_dict` method for convenient serialization of the metric
+    data into a plain dictionary."""
+
+    metrics: dict[str, float] = field(default_factory=dict)
+    details: dict[str, Any] = field(
+        default_factory=dict
+    )  # Additional details about the metric
+    raw: RawResult = field(default_factory=RawResult)
+    duration_s: float = 0.0
+
+    def __post_init__(self):
+        """Ensures that the `details` and `metrics` attributes are dictionaries, initializing them to empty dictionaries if they are not."""
+        if not isinstance(self.details, dict):
+            self.details = {}
+        if not isinstance(self.metrics, dict):
+            self.metrics = {}
+
+    def to_dict(self) -> dict:
+        """Returns a dictionary containing the metrics, details, and the raw data serialized via its own `to_dict` method."""
+        return {
+            "metrics": self.metrics,
+            "details": self.details,
+            "raw": self.raw.to_dict(),
+            "duration_s": self.duration_s,
+        }
+
+
+@dataclass
+class CombinedToolResults:
+    """Aggregates results from multiple tools, stores the associated path, and calculates an overall score by averaging the mean metric values of each ``ToolResult``. If a ``ToolResult`` has no metrics, it contributes zero, and the score defaults to ``0.0`` when the list is empty."""
+
+    def __init__(self, path: str, tool_results: list[ToolResult]):
+        """Initializes a CombinedToolResults instance.
+
+        Stores the given path and list of ToolResult objects, and computes an overall
+        score by averaging the mean metric values of each ToolResult. ToolResults
+        without metrics contribute zero. If the list is empty the score defaults to
+        0.0.
+
+        Args:
+            path (str): Path associated with the results.
+            tool_results (list[ToolResult]): List of ToolResult objects."""
+        self.tool_results = tool_results
+        self.path = path
+        scored = [tr for tr in tool_results if tr.metrics]
+        self.score = sum(sum(tr.metrics.values()) / len(tr.metrics) for tr in scored) / len(scored) if scored else 0.0
+
+    score: float = 0.0
+    path: str = ""
+
+    def to_dict(self) -> dict:
+        """Returns a dictionary containing the path, overall score, and each ToolResult serialized."""
+        return {
+            "metrics": [tool_result.to_dict() for tool_result in self.tool_results],
+            "score": self.score,
+            "path": self.path,
+        }
+
+
+class AbstractParser(ABC):
+    """Base class for parsers that transform raw tool output into structured `ToolResult` objects.
+
+    Subclasses must implement `parse` to convert a `RawResult` into a `ToolResult`. An optional `provide_help` can be overridden to supply contextual guidance for a parsed result."""
+
+    @abstractmethod
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Converts raw tool output into a structured ToolResult."""
+        pass
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        """Return a single-defect description for LLM consumption.
+
+        Default implementation reports the worst metric by name and score.
+        Parsers with richer details should override this."""
+        if tr.metrics:
+            metric_name, value = next(iter(tr.metrics.items()))
+            return f"**{metric_name}** score: {value:.3f}"
+        return "No details available"

py_cq/main.py

@@ -0,0 +1,12 @@
+"""This module provides the entry point for the application. It defines a `main` function that handles initialization, command-line argument parsing, and triggers the core application workflow. The module can be executed directly to run the application."""
+
+from py_cq.cli import app
+
+
+def main():
+    """Runs the application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

py_cq/metric_aggregator.py

@@ -0,0 +1,14 @@
+"""Utilities for consolidating static-analysis metrics.
+
+This module provides a single function, :func:`aggregate_metrics`, which takes a filesystem path and a list of
+:class:`ToolResult` objects produced by various static-analysis tools. It validates the input, merges the
+metrics from each tool into a :class:`CombinedToolResults` instance, and returns the unified representation.
+The resulting object can be consumed by reporting tools or CI pipelines to present a single view of all analysis
+results for a given file or directory."""
+
+from py_cq.localtypes import CombinedToolResults, ToolResult
+
+
+def aggregate_metrics(path: str, metrics: list[ToolResult]) -> CombinedToolResults:
+    """Returns a CombinedToolResults instance aggregating the given metrics for the specified path."""
+    return CombinedToolResults(path=path, tool_results=metrics)

py_cq/parsers/banditparser.py

@@ -0,0 +1,52 @@
+"""Parses output from bandit security linter into a standardized ToolResult.
+
+Bandit is invoked with ``-f json``, producing a JSON blob on stdout.
+The parser extracts per-file violations, applies severity weighting
+(HIGH=5, MEDIUM=2, LOW=1), and converts the weighted count into a
+logistic-variant score stored under the ``security`` metric key.
+"""
+
+import json
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import score_logistic_variant
+
+_SEVERITY_WEIGHT = {"HIGH": 5, "MEDIUM": 2, "LOW": 1}
+
+
+class BanditParser(AbstractParser):
+    """Parses raw JSON output from ``bandit -f json`` into a ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        try:
+            data = json.loads(raw_result.stdout)
+        except (json.JSONDecodeError, ValueError):
+            return ToolResult(raw=raw_result, metrics={"security": 1.0})
+
+        files: dict[str, list] = {}
+        weighted = 0
+        for issue in data.get("results", []):
+            path = issue.get("filename", "").replace("\\", "/")
+            severity = issue.get("issue_severity", "LOW")
+            files.setdefault(path, []).append({
+                "line": issue.get("line_number", 0),
+                "code": issue.get("test_id", ""),
+                "severity": severity,
+                "confidence": issue.get("issue_confidence", ""),
+                "message": issue.get("issue_text", ""),
+            })
+            weighted += _SEVERITY_WEIGHT.get(severity, 1)
+
+        score = score_logistic_variant(weighted, scale_factor=10)
+        return ToolResult(raw=raw_result, metrics={"security": score}, details=files)
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        if not tr.details:
+            return "bandit reported issues (no details available)"
+        file, issues = next(iter(tr.details.items()))
+        issue = issues[0]
+        line = issue.get("line", "?")
+        code = issue.get("code", "")
+        severity = issue.get("severity", "")
+        message = issue.get("message", "")
+        return f"`{file}:{line}` — **{code}** [{severity}]: {message}"

py_cq/parsers/common.py

@@ -0,0 +1,87 @@
+"""Utility functions for normalising numeric values and scoring error magnitudes.
+
+This module provides two small helpers that are often used when working with
+performance metrics or error scores:
+
+* :func:`inv_normalize` - Inversely normalises a value relative to a maximum
+  reference, yielding a float in the interval [0,\u202f1].
+* :func:`score_logistic_variant` - Maps an error magnitude to a bounded score
+  using a logistic-style curve, with optional parameters controlling the scale
+  and steepness of the transition.
+
+Both functions return a float and can be used directly in downstream analytics,
+visualisation or decision-making pipelines."""
+
+
+
+def read_source_lines(file_path: str, line: int, count: int = 5) -> str:
+    """Return up to `count` source lines starting at the given 1-based line number."""
+    from pathlib import Path
+    try:
+        all_lines = Path(file_path).read_text(encoding="utf-8").splitlines()
+        start = max(0, line - 1)
+        return "\n".join(all_lines[start : start + count])
+    except OSError:
+        return ""
+
+
+def inv_normalize(value: float, max_value: float) -> float:
+    """Returns the inverse normalized value of `value` relative to `max_value`."""
+    return (max_value - min(value, max_value)) / max_value
+
+
+def score_logistic_variant(
+    errors, scale_factor: float = 30, steepness: float = 2
+) -> float:
+    """Calculate a logistic-variant score from an error value.
+
+    The score is always in the range ``[0.0, 1.0]`` and decreases monotonically
+    as the magnitude of the error increases. Negative errors are treated as
+    zero.  A special case occurs when ``scale_factor`` is ``0``: the method
+    returns ``1.0`` only when the error is exactly zero; otherwise it returns
+    ``0.0``.
+
+    The logistic function is computed as::
+
+        1 / (1 + (errors / scale_factor) ** steepness)
+
+    To avoid numerical overflow, the intermediate term is capped at
+    ``float('inf')`` when ``errors / scale_factor`` exceeds
+    ``709 / steepness`` (the largest value that can be exponentiated
+    without raising an :class:`OverflowError`).
+
+    Args:
+        errors (float): The error magnitude to score.  Negative values are
+            treated as zero.
+        scale_factor (float, optional): Scaling factor applied to the error.
+            Defaults to ``30``.  When ``0``, the special case described above
+            applies.
+        steepness (float, optional): Exponent controlling the steepness of
+            the logistic curve. Defaults to ``2``.
+
+    Returns:
+        float: A score between ``0.0`` and ``1.0`` representing the logistic
+            mapping of the input error.  The function safely handles large
+            error values by capping the intermediate calculation to infinity.
+
+    Example:
+        >>> score_logistic_variant(5, scale_factor=10, steepness=2)
+        0.9090909090909091
+        >>> score_logistic_variant(-3)
+        1.0
+        >>> score_logistic_variant(10, scale_factor=0)
+        0.0"""
+    if errors < 0:
+        errors = 0
+    if scale_factor == 0:
+        return 1.0 if errors == 0 else 0.0
+    try:
+        # Handle case where errors/scale_factor is very large, to avoid overflow
+        base = errors / scale_factor
+        if base > 709 / steepness:  # exp(709) is near max float
+            term = float("inf")
+        else:
+            term = base**steepness
+    except OverflowError:  # pragma: no cover
+        return 0.0  # Score becomes 0 if term is too large
+    return 1.0 / (1.0 + term)

py_cq/parsers/compileparser.py

@@ -0,0 +1,134 @@
+"""This module defines the :class:`CompileParser`, a concrete subclass of
+:class:`AbstractParser`.  The parser translates raw compiler output into a
+structured :class:`ToolResult`, extracting diagnostics, computing a
+compile score, and providing concise help messages for any failures."""
+
+import logging
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import read_source_lines, score_logistic_variant
+
+log = logging.getLogger("cq")
+
+
+class CompileParser(AbstractParser):
+    """Parses raw compiler output into a structured ToolResult.
+
+    The `CompileParser` implements the `AbstractParser` interface, converting
+    `RawResult` objects into `ToolResult` instances that include diagnostics,
+    metrics, and a mapping of failed files. It also supplies a human-readable
+    help string summarizing any compilation errors for a given `ToolResult`."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parses compiler output into a structured ``ToolResult``.
+
+        The method scans the ``stdout`` of a ``RawResult`` object for compilation
+        events and error messages. For each file that emits an error, it extracts
+        the line number, source snippet, error type, and help text, normalizes the
+        file path, and stores this information in a dictionary keyed by file path.
+        It then computes a failure ratio (failed files ÷ total compilations) and
+        derives a compile score via ``score_logistic_variant``.  The original
+        ``stdout`` is cleaned of ``Listing`` lines and back-slash path separators
+        are replaced with forward slashes.  A ``ToolResult`` containing the raw
+        result, a compile metric, and, if any, a mapping of failed files is
+        returned.
+
+        Args:
+            raw_result (RawResult): Raw compiler output, typically containing a
+                ``stdout`` attribute.
+
+        Returns:
+            ToolResult: A structured result containing diagnostics, a compile
+                metric, and a mapping of failed files (if any).
+
+        Example:
+            >>> parser = CompileParser()
+            >>> raw = RawResult(stdout=(
+            ...     'Compiling a.c\\\\n'
+            ...     '***   File "a.c" line 10, column 5:\\\\n'
+            ...     '    error: unknown type name \\\\'foo\\\\'\\\\n'
+            ...     '\\\\n'))
+            >>> result = parser.parse(raw)
+            >>> result.metrics['compile']
+            0.5
+            >>> result.details['failed_files']['a.c']['type']
+            'error'"""
+
+        compilations = 0
+        failed_files: dict[str, dict] = {}
+        current_error = None
+        # Process stdout first for successful compilations
+        if raw_result.stdout:
+            for line in raw_result.stdout.splitlines():
+                if line.startswith("Compiling "):
+                    compilations += 1
+                elif line.startswith("***   File "):
+                    # This indicates a compilation error
+                    file_path = line.split('"')[1]
+                    current_error = {"file": file_path, "error": line}
+                elif current_error and line.strip():
+                    # Append additional error context
+                    current_error["error"] += "\n" + line
+                elif line.startswith("Listing "):
+                    # Skip directory listings
+                    continue
+                elif current_error and (not line.strip()):
+                    # Empty line ends the error block
+                    # Parse error details from the error block
+                    error_lines = current_error["error"].splitlines()
+                    log.debug("Compile error lines: %s", error_lines)
+                    error_info = {}
+                    # Extract line number if present
+                    if "line " in error_lines[0]:
+                        error_info["line"] = int(
+                            error_lines[0].split("line ")[1].split(",")[0]
+                        )
+                    # Get source code context if available
+                    if len(error_lines) > 1:
+                        error_info["src"] = error_lines[1].strip()
+                    if len(error_lines) > 3:
+                        if "Error:" in error_lines[3]:
+                            error_parts = error_lines[3].split(":")
+                            error_info["type"] = (
+                                error_parts[0].strip().split()[-1]
+                            )  # Gets "SyntaxError"
+                            error_info["help"] = ",".join(
+                                error_parts[1:]
+                            ).strip()  # Gets help message
+                    else:
+                        error_info["type"] = "Unknown"
+                        error_info["help"] = "\n".join(error_lines[2:]).strip()
+                    file_path = current_error["file"].replace("\\", "/")
+                    failed_files[file_path] = error_info
+                    current_error = None
+        failure_ratio = len(failed_files) / compilations if compilations > 0 else 0.0
+        score = score_logistic_variant(failure_ratio, scale_factor=0.25)
+        raw_result.stdout = "\n".join(
+            [
+                line.replace("\\\\", "/")
+                for line in raw_result.stdout.splitlines()
+                if not line.startswith("Listing")
+            ]
+        )
+        tr = ToolResult(raw=raw_result, metrics={"compile": score})
+        if failed_files:
+            tr.details["failed_files"] = failed_files
+        return tr
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        """Return the first compilation failure as a defect description."""
+        failed = tr.details.get("failed_files", {})
+        if not failed:
+            return "Compilation failed (no details available)"
+        file, info = next(iter(failed.items()))
+        line = info.get("line", "?")
+        typ = info.get("type", "Error")
+        help_msg = info.get("help", "")
+        if isinstance(line, int):
+            context_start = max(1, line - 3)
+            raw_lines = read_source_lines(file, context_start, count=8).splitlines()
+            src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else info.get("src", "")
+        else:
+            src = info.get("src", "")
+        code_block = f"\n```python\n{src}\n```" if src else ""
+        return f"`{file}:{line}` — **{typ}**: {help_msg}{code_block}"

py_cq/parsers/complexityparser.py

@@ -0,0 +1,86 @@
+"""Provides a `ComplexityParser` that converts raw complexity-analysis output into structured `ToolResult` objects for downstream use."""
+
+import json
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import score_logistic_variant
+
+
+class ComplexityParser(AbstractParser):
+    """Parse raw output from a complexity analysis tool into structured results.
+
+    This parser accepts a :class:`~tools.core.RawResult` containing the raw
+    ``stdout`` of a static-analysis or profiling tool.  It validates the
+    JSON payload, extracts per-file and per-function metrics, and returns a
+    :class:`~tools.core.ToolResult` that holds the parsed data, a
+    per-item details dictionary, and overall summary metrics such as the
+    overall simplicity score.
+
+    Example
+    -------
+    >>> parser = ComplexityParser()
+    >>> raw = RawResult(stdout='{"main.py":[{"name":"foo","complexity":12,"rank":"B"}]}',
+    ...                 return_code=0)
+    >>> result = parser.parse(raw)
+    >>> result.metrics['simplicity']
+    0.4"""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parse raw tool output into a structured :class:`~tools.core.ToolResult`.
+
+        The method accepts a :class:`~tools.core.RawResult` that contains the raw
+        ``stdout`` from a complexity analysis tool.  The ``stdout`` is expected to
+        be a JSON string mapping file names to lists of function descriptors.
+        Each descriptor should at least contain a ``name`` and a ``complexity``
+        value, and may optionally include a ``rank``.  The parser converts each
+        function into a *simplicity* score using the logistic variant
+        (`score_logistic_variant`).  The overall simplicity score is the mean of
+        all function scores.  The resulting :class:`~tools.core.ToolResult`
+        holds the original raw result, a ``details`` dictionary keyed by file
+        and function names (with simplicity and rank), and a ``metrics``
+        dictionary that contains the overall simplicity value.  The tool's
+        return code is also recorded in ``details['return_code']``.
+
+        Args:
+            raw_result (RawResult):
+                The raw result from a complexity analysis tool.  It must expose a
+                ``stdout`` attribute containing a JSON string that maps file
+                names to lists of function descriptors, and a ``return_code``
+                attribute.
+
+        Returns:
+            ToolResult: A structured result that includes the original raw result,
+            per-file/function details with simplicity scores and ranks, and a
+            metrics dictionary that holds the overall simplicity score.
+
+        Raises:
+            json.JSONDecodeError: If ``raw_result.stdout`` cannot be parsed as
+                JSON.
+
+        Example:
+            >>> raw = RawResult(stdout='{"main.py": [{"name": "foo", "complexity": 12, "rank": "B"}]}', return_code=0)
+            >>> parser = ComplexityParser()
+            >>> result = parser.parse(raw)
+            >>> result.metrics["simplicity"]
+            0.4"""
+        tr = ToolResult(raw=raw_result)
+        data = json.loads(raw_result.stdout)
+        score = 0
+        num_items = 0
+        max_complexity = 30
+        for file, functions in data.items():
+            file_name = file.replace("\\", "/")
+            if file_name not in tr.details:
+                tr.details[file_name] = {}
+            for function in functions:
+                num_items += 1
+                function_score = score_logistic_variant(
+                    function.get("complexity", max_complexity), max_complexity
+                )
+                score += function_score
+                tr.details[file_name][function["name"]] = {
+                    "simplicity": function_score,
+                    "rank": function.get("rank", "F"),
+                }
+        tr.metrics["simplicity"] = score / num_items if num_items > 0 else 0.0
+        return tr

py_cq/parsers/coverageparser.py

@@ -0,0 +1,88 @@
+"""Parses raw coverage tool output into a standardized `ToolResult` for consistent analysis across different coverage utilities.
+The module defines `CoverageParser`, a concrete implementation of `AbstractParser`, which extracts overall and per-file coverage metrics from a `RawResult` object and normalises the data format for downstream processing."""
+
+import logging
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+
+log = logging.getLogger("cq")
+
+
+class CoverageParser(AbstractParser):
+    """Parses raw coverage output into structured ToolResult instances.
+    Extends AbstractParser, extracting overall coverage percentages, per-file coverage values, normalising file paths, and preserving the tool's return code."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parse raw coverage output into a :class:`ToolResult`.
+
+        Given a :class:`RawResult` containing the stdout of a coverage tool, the
+        method extracts every line that ends with a percent sign.  Each such line
+        is expected to follow the format::
+
+            <file> <total_lines> <covered_lines> <coverage>%
+
+        The coverage percentage is converted to a fraction (e.g. 90\u202f% → 0.9) and
+        stored in ``metrics['coverage']`` for the overall ``TOTAL`` line, while
+        the per-file values are placed in ``details`` with the file path
+        normalised to use forward slashes.  The tool's return code is added to
+        ``details`` under the key ``'return_code'``.
+
+        Args:
+            raw_result (RawResult): The raw output from a coverage tool.
+
+        Returns:
+            ToolResult: A structured result containing the overall coverage
+            metric, per-file coverage percentages, and the tool's return code.
+
+        Example:
+            >>> parser = CoverageParser()
+            >>> raw = RawResult(
+            ...     stdout='src/main.py 100 90 90%\\\\nTOTAL 200 180 90%',
+            ...     return_code=0)
+            >>> result = parser.parse(raw)
+            >>> result.metrics['coverage']
+            0.9
+            >>> result.details['src/main.py']
+            0.9"""
+        tr = ToolResult(raw=raw_result)
+        lines = raw_result.stdout.splitlines()
+        coverage_lines = [line for line in lines if line.endswith("%")]
+        details = {}
+        for line in coverage_lines:
+            parts = line.split()
+            if len(parts) >= 2:
+                file_name = parts[0]
+                try:
+                    coverage_percentage = float(parts[-1].rstrip('%')) / 100.0
+                except ValueError:
+                    log.warning("Error parsing coverage percentage from line: %s", line)
+                    continue
+                if file_name == "TOTAL":
+                    tr.metrics["coverage"] = coverage_percentage
+                else:
+                    try:
+                        missing = int(parts[2]) if len(parts) >= 4 else None
+                    except (ValueError, IndexError):
+                        missing = None
+                    details[file_name.replace("\\", "/")] = {
+                        "coverage": coverage_percentage,
+                        "missing": missing,
+                    }
+        tr.details = details
+        return tr
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        """Return the files with lowest coverage as a defect description."""
+        score = tr.metrics.get("coverage", 0)
+        uncovered = sorted(
+            [(f, d) for f, d in tr.details.items() if isinstance(d, dict) and d.get("missing")],
+            key=lambda x: x[1]["coverage"],
+        )[:5]
+        if not uncovered:
+            return f"**coverage** score: {score:.3f}"
+        lines = [f"**coverage** score: {score:.3f} — files with lowest coverage:"]
+        for path, data in uncovered:
+            pct = data["coverage"]
+            miss = data["missing"]
+            lines.append(f"- `{path}`: {pct:.0%} ({miss} uncovered statements)")
+        return "\n".join(lines)