gd-tools-cli 0.1.0__py3-none-any.whl

gd_tools/coverage/reporter.py

@@ -0,0 +1,518 @@
+"""Coverage reporter module.
+
+Reads instrumentation plan JSON (from the plan generator) and coverage
+data JSON (from the GDScript runtime hooks), cross-references them by
+``file_id`` to compute line and branch coverage metrics, and dispatches
+to format-specific reporters (HTML, LCOV, Cobertura, terminal).
+
+This module is the final reporting layer of the hybrid coverage system
+(Architecture C: Python plan gen -> GDScript runtime instrumentation ->
+Python reporting).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gd_tools.coverage.plan_generator import CoveragePlan, FilePlan
+from gd_tools.errors import CoveragePlanError, CoverageThresholdError
+
+# --- Data structures (FR-1, FR-2, FR-3) ---
+
+
+@dataclass
+class FileCoverage:
+    """Coverage data for a single file from the runtime tracker.
+
+    Attributes:
+        file_id: Sequential identifier matching the plan's ``file_id``.
+        hits: Mapping of line ID (string key) to hit count.
+    """
+
+    file_id: int
+    hits: dict[str, int]
+
+
+@dataclass
+class CoverageData:
+    """Top-level container for runtime coverage data.
+
+    Attributes:
+        version: Schema version (currently 1).
+        generated_at: ISO timestamp from the runtime tracker, or None.
+        files: List of per-file coverage data.
+    """
+
+    version: int
+    generated_at: str | None = None
+    files: list[FileCoverage] = field(default_factory=list)
+
+
+@dataclass
+class CoverageSummary:
+    """Overall coverage summary across all files.
+
+    Attributes:
+        line_rate: Fraction of executable lines covered (0.0-1.0).
+        branch_rate: Fraction of branch points covered (0.0-1.0).
+        covered_lines: Count of lines with hit count > 0.
+        total_lines: Total executable lines in the plan.
+        covered_branches: Count of branches with hit count > 0.
+        total_branches: Total branch points in the plan.
+    """
+
+    line_rate: float
+    branch_rate: float
+    covered_lines: int
+    total_lines: int
+    covered_branches: int
+    total_branches: int
+
+
+@dataclass
+class FileSummary:
+    """Per-file coverage summary.
+
+    Attributes:
+        file_id: Sequential identifier from the plan.
+        path: Godot resource path (``res://``) from the plan.
+        line_rate: Fraction of executable lines covered (0.0-1.0).
+        branch_rate: Fraction of branch points covered (0.0-1.0).
+        covered_lines: Count of lines with hit count > 0.
+        total_lines: Total executable lines in this file's plan.
+        covered_branches: Count of branches with hit count > 0.
+        total_branches: Total branch points in this file's plan.
+        uncovered_lines: Line numbers with zero hits.
+    """
+
+    file_id: int
+    path: str
+    line_rate: float
+    branch_rate: float
+    covered_lines: int
+    total_lines: int
+    covered_branches: int
+    total_branches: int
+    uncovered_lines: list[int]
+
+
+@dataclass
+class ReportResult:
+    """Result of a report generation operation.
+
+    Attributes:
+        output_path: Path to the generated report file or directory.
+        format: Report format (``"html"``, ``"lcov"``, ``"cobertura"``,
+            ``"text"``).
+        summary: Overall coverage summary.
+        file_summaries: Per-file coverage breakdowns.
+        threshold_met: Whether coverage met the minimum threshold.
+    """
+
+    output_path: Path
+    format: str
+    summary: CoverageSummary
+    file_summaries: list[FileSummary]
+    threshold_met: bool
+
+
+# --- JSON I/O (FR-1) ---
+
+
+def read_coverage_json(path: Path) -> CoverageData:
+    """Read a coverage data JSON file produced by the runtime tracker.
+
+    The expected format matches Track 11's runtime output: each file
+    entry has ``file_id`` (int) and ``hits`` (dict with string keys).
+    A ``path`` field is NOT required in the coverage data — path
+    resolution happens at report-generation time via the plan.
+
+    Args:
+        path: Path to the coverage data JSON file.
+
+    Returns:
+        The deserialized :class:`CoverageData`.
+
+    Raises:
+        CoveragePlanError: If the file is missing, contains invalid
+            JSON, or has a version mismatch.
+    """
+    cov_path = Path(path)
+    if not cov_path.exists():
+        raise CoveragePlanError(
+            f"[Error] Coverage data file not found: {path}\n"
+            f"  Cause: The file does not exist at the specified path.\n"
+            f"  Fix: Ensure the coverage data file was generated by "
+            "'gd-tools coverage run' and the path is correct."
+        )
+
+    try:
+        data = json.loads(cov_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise CoveragePlanError(
+            f"[Error] Invalid JSON in coverage data file\n"
+            f"  Cause: {exc}\n"
+            f"  Fix: Ensure the file is valid JSON generated by "
+            "'gd-tools coverage run'."
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise CoveragePlanError(
+            "[Error] Coverage data must be a JSON object\n"
+            "  Cause: The top-level JSON value is not an object.\n"
+            "  Fix: Ensure the file contains a JSON object with "
+            "'version' and 'files' fields."
+        )
+
+    version = data.get("version")
+    if version != 1:
+        raise CoveragePlanError(
+            f"[Error] Unsupported coverage data version: {version}\n"
+            f"  Cause: Expected version 1, got {version}.\n"
+            f"  Fix: Regenerate the coverage data with the current "
+            "version of gd-tools."
+        )
+
+    if "files" not in data:
+        raise CoveragePlanError(
+            "[Error] Missing required field: files\n"
+            "  Cause: The coverage data JSON does not contain a "
+            "'files' field.\n"
+            "  Fix: Ensure the coverage data was generated by "
+            "'gd-tools coverage run'."
+        )
+
+    files_data = data["files"]
+    if not isinstance(files_data, list):
+        raise CoveragePlanError(
+            "[Error] Coverage data 'files' field must be a list\n"
+            "  Cause: The 'files' field is not a JSON array.\n"
+            "  Fix: Ensure the coverage data was generated by "
+            "'gd-tools coverage run'."
+        )
+
+    files: list[FileCoverage] = []
+    for fdata in files_data:
+        if not isinstance(fdata, dict):
+            raise CoveragePlanError(
+                "[Error] Invalid coverage file entry\n"
+                "  Cause: An entry in the 'files' array is not a "
+                "JSON object.\n"
+                "  Fix: Ensure the coverage data was generated by "
+                "'gd-tools coverage run'."
+            )
+        if "file_id" not in fdata:
+            raise CoveragePlanError(
+                "[Error] Missing required field: file_id\n"
+                "  Cause: A coverage file entry does not contain a "
+                "'file_id' field.\n"
+                "  Fix: Ensure the coverage data was generated by "
+                "'gd-tools coverage run'."
+            )
+        if "hits" not in fdata:
+            raise CoveragePlanError(
+                "[Error] Missing required field: hits\n"
+                "  Cause: A coverage file entry does not contain a "
+                "'hits' field.\n"
+                "  Fix: Ensure the coverage data was generated by "
+                "'gd-tools coverage run'."
+            )
+        hits_data = fdata["hits"]
+        if not isinstance(hits_data, dict):
+            raise CoveragePlanError(
+                "[Error] Coverage 'hits' field must be a dict\n"
+                "  Cause: The 'hits' field is not a JSON object.\n"
+                "  Fix: Ensure the coverage data was generated by "
+                "'gd-tools coverage run'."
+            )
+
+        # Ensure all hit counts are ints (JSON may produce them as such,
+        # but we normalize for safety)
+        hits = {str(k): int(v) for k, v in hits_data.items()}
+
+        files.append(FileCoverage(file_id=fdata["file_id"], hits=hits))
+
+    return CoverageData(
+        version=data["version"],
+        generated_at=data.get("generated_at"),
+        files=files,
+    )
+
+
+def merge_coverage_data(files: list[Path]) -> CoverageData:
+    """Merge multiple coverage data files (for parallel CI shards).
+
+    Sums hit counts per ``file_id``/``line_id`` across all input files.
+    Files that appear in only one shard are included as-is.
+
+    Args:
+        files: List of paths to coverage data JSON files.
+
+    Returns:
+        A merged :class:`CoverageData` with summed hit counts.
+    """
+    if not files:
+        return CoverageData(version=1)
+
+    merged_files: dict[int, dict[str, int]] = {}
+    generated_at: str | None = None
+
+    for fpath in files:
+        data = read_coverage_json(fpath)
+        if generated_at is None:
+            generated_at = data.generated_at
+
+        for fc in data.files:
+            if fc.file_id not in merged_files:
+                merged_files[fc.file_id] = {}
+            for line_id, count in fc.hits.items():
+                merged_files[fc.file_id][line_id] = (
+                    merged_files[fc.file_id].get(line_id, 0) + count
+                )
+
+    result_files = [
+        FileCoverage(file_id=fid, hits=hits)
+        for fid, hits in merged_files.items()
+    ]
+
+    return CoverageData(
+        version=1,
+        generated_at=generated_at,
+        files=result_files,
+    )
+
+
+def write_coverage_json(data: CoverageData, path: Path) -> None:
+    """Write coverage data to a JSON file.
+
+    Serializes a :class:`CoverageData` object to the same JSON format
+    produced by the runtime tracker, ensuring round-trip compatibility
+    with :func:`read_coverage_json`.
+
+    Args:
+        data: The coverage data to serialize.
+        path: Path to the output JSON file.
+    """
+    cov_path = Path(path)
+    cov_path.parent.mkdir(parents=True, exist_ok=True)
+
+    data_dict = {
+        "version": data.version,
+        "generated_at": data.generated_at,
+        "files": [
+            {"file_id": fc.file_id, "hits": fc.hits} for fc in data.files
+        ],
+    }
+    cov_path.write_text(json.dumps(data_dict, indent=2), encoding="utf-8")
+
+
+# --- Coverage computation (FR-2) ---
+
+
+def compute_file_summary(
+    file_plan: FilePlan, file_data: FileCoverage
+) -> FileSummary:
+    """Compute per-file coverage metrics.
+
+    Cross-references a file's instrumentation plan with its runtime
+    coverage data to produce coverage rates and uncovered line list.
+
+    Args:
+        file_plan: The file's instrumentation plan.
+        file_data: The file's runtime coverage data.
+
+    Returns:
+        A :class:`FileSummary` with coverage metrics.
+    """
+    covered_lines = 0
+    total_lines = 0
+    covered_branches = 0
+    total_branches = 0
+    uncovered_lines: list[int] = []
+
+    for line in file_plan.lines:
+        total_lines += 1
+        hit_count = file_data.hits.get(str(line.id), 0)
+
+        if hit_count > 0:
+            covered_lines += 1
+        else:
+            uncovered_lines.append(line.line)
+
+        if line.type == "branch":
+            total_branches += 1
+            if hit_count > 0:
+                covered_branches += 1
+
+    line_rate = covered_lines / total_lines if total_lines > 0 else 0.0
+    branch_rate = (
+        covered_branches / total_branches if total_branches > 0 else 0.0
+    )
+
+    return FileSummary(
+        file_id=file_plan.file_id,
+        path=file_plan.path,
+        line_rate=line_rate,
+        branch_rate=branch_rate,
+        covered_lines=covered_lines,
+        total_lines=total_lines,
+        covered_branches=covered_branches,
+        total_branches=total_branches,
+        uncovered_lines=uncovered_lines,
+    )
+
+
+def compute_summary(plan: CoveragePlan, data: CoverageData) -> CoverageSummary:
+    """Compute overall coverage metrics across all files.
+
+    Aggregates per-file coverage into an overall summary. Files in the
+    plan but missing from coverage data are treated as 0 hits.
+
+    Args:
+        plan: The full instrumentation plan.
+        data: The runtime coverage data.
+
+    Returns:
+        A :class:`CoverageSummary` with aggregated coverage metrics.
+    """
+    coverage_by_id = {fc.file_id: fc for fc in data.files}
+
+    total_covered_lines = 0
+    total_lines = 0
+    total_covered_branches = 0
+    total_branches = 0
+
+    for file_plan in plan.files:
+        file_data = coverage_by_id.get(
+            file_plan.file_id,
+            FileCoverage(file_id=file_plan.file_id, hits={}),
+        )
+        fs = compute_file_summary(file_plan, file_data)
+        total_covered_lines += fs.covered_lines
+        total_lines += fs.total_lines
+        total_covered_branches += fs.covered_branches
+        total_branches += fs.total_branches
+
+    line_rate = total_covered_lines / total_lines if total_lines > 0 else 0.0
+    branch_rate = (
+        total_covered_branches / total_branches if total_branches > 0 else 0.0
+    )
+
+    return CoverageSummary(
+        line_rate=line_rate,
+        branch_rate=branch_rate,
+        covered_lines=total_covered_lines,
+        total_lines=total_lines,
+        covered_branches=total_covered_branches,
+        total_branches=total_branches,
+    )
+
+
+# --- Report dispatch and threshold (FR-3) ---
+
+_SUPPORTED_FORMATS = {"html", "lcov", "cobertura", "terminal"}
+
+
+def generate_report(
+    plan: CoveragePlan,
+    data: CoverageData,
+    output_dir: Path,
+    format: str = "html",
+    min_threshold: float | None = None,
+) -> ReportResult:
+    """Generate a coverage report in the specified format.
+
+    Dispatches to a format-specific reporter after computing coverage
+    metrics.  If ``min_threshold`` is set and the overall line coverage
+    rate falls below it, :class:`CoverageThresholdError` is raised
+    after the report file has been written.
+
+    Args:
+        plan: The instrumentation plan.
+        data: The runtime coverage data.
+        output_dir: Directory where the report file is written.
+        format: Report format — one of ``"html"``, ``"lcov"``,
+            ``"cobertura"``, ``"terminal"``.
+        min_threshold: Minimum line coverage rate (0.0-1.0).  If
+            ``None``, no threshold check is performed.
+
+    Returns:
+        A :class:`ReportResult` with the report path, summary, and
+        file-level breakdowns.
+
+    Raises:
+        CoveragePlanError: If ``format`` is not a supported format.
+        CoverageThresholdError: If ``min_threshold`` is set and
+            ``line_rate < min_threshold``.
+    """
+    if format not in _SUPPORTED_FORMATS:
+        raise CoveragePlanError(
+            f"[Error] Unsupported report format: '{format}'\n"
+            f"  Cause: The format '{format}' is not supported.\n"
+            f"  Fix: Use one of: "
+            f"{', '.join(sorted(_SUPPORTED_FORMATS))}"
+        )
+
+    summary = compute_summary(plan, data)
+
+    coverage_by_id = {fc.file_id: fc for fc in data.files}
+    file_summaries: list[FileSummary] = []
+    for file_plan in plan.files:
+        file_data = coverage_by_id.get(
+            file_plan.file_id,
+            FileCoverage(file_id=file_plan.file_id, hits={}),
+        )
+        file_summaries.append(compute_file_summary(file_plan, file_data))
+
+    threshold_met = True
+    if min_threshold is not None:
+        threshold_met = summary.line_rate >= min_threshold
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if format == "terminal":
+        from gd_tools.coverage.terminal_reporter import (
+            generate_terminal_report,
+        )
+
+        output_path = output_dir / "coverage_report.txt"
+        report_text = generate_terminal_report(plan, data)
+        output_path.write_text(report_text, encoding="utf-8")
+    elif format == "lcov":
+        from gd_tools.coverage.lcov_reporter import generate_lcov_report
+
+        output_path = output_dir / "coverage.info"
+        generate_lcov_report(plan, data, output_path)
+    elif format == "cobertura":
+        from gd_tools.coverage.cobertura_reporter import (
+            generate_cobertura_report,
+        )
+
+        output_path = output_dir / "cobertura.xml"
+        generate_cobertura_report(plan, data, output_path)
+    else:  # html (format already validated above)
+        from gd_tools.coverage.html_reporter import generate_html_report
+
+        output_path = generate_html_report(plan, data, output_dir)
+
+    result = ReportResult(
+        output_path=output_path,
+        format=format,
+        summary=summary,
+        file_summaries=file_summaries,
+        threshold_met=threshold_met,
+    )
+
+    if not threshold_met:
+        raise CoverageThresholdError(
+            f"[Error] Coverage threshold not met\n"
+            f"  Cause: Line coverage {summary.line_rate:.2%} is "
+            f"below minimum {min_threshold:.2%}.\n"
+            f"  Fix: Increase test coverage or lower the minimum "
+            "threshold."
+        )
+
+    return result

gd_tools/coverage/templates/file.html

@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{ file_summary.path }} - Coverage</title>
+  <style>
+    body { font-family: sans-serif; margin: 2em; color: #333; }
+    h1 { margin-bottom: 0.5em; }
+    .file-info { margin-bottom: 1em; color: #666; }
+    .summary-bar {
+      display: flex; gap: 2em; margin-bottom: 2em;
+      padding: 1em; background: #f5f5f5; border-radius: 4px;
+    }
+    .summary-item { text-align: center; }
+    .summary-item .value { font-size: 1.5em; font-weight: bold; }
+    .summary-item .label { font-size: 0.9em; color: #666; }
+    .rate-good { color: #2e7d32; }
+    .rate-medium { color: #f57f17; }
+    .rate-low { color: #c62828; }
+    .source-listing {
+      font-family: monospace; font-size: 0.9em;
+      border: 1px solid #ddd; border-radius: 4px; overflow: hidden;
+    }
+    .source-line {
+      display: flex; padding: 0.2em 0;
+      border-bottom: 1px solid #eee;
+    }
+    .source-line:last-child { border-bottom: none; }
+    .line-number {
+      min-width: 3em; text-align: right;
+      padding: 0 1em; color: #999; user-select: none;
+      border-right: 1px solid #ddd;
+    }
+    .line-content { padding: 0 1em; flex-grow: 1; }
+    .line-hits {
+      min-width: 5em; text-align: right;
+      padding: 0 1em; color: #666; font-size: 0.85em;
+    }
+    .covered { background-color: #c8e6c9; }
+    .uncovered { background-color: #ffcdd2; }
+    .partial { background-color: #fff9c4; }
+    .not-tracked { color: #ccc; }
+    a { color: #1565c0; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">&larr; Back to summary</a></p>
+  <h1>{{ file_summary.path }}</h1>
+  <div class="file-info">File ID: {{ file_summary.file_id }}</div>
+  <div class="summary-bar">
+    <div class="summary-item">
+      <div class="value rate-{{ 'good' if file_summary.line_rate >= 0.8 else ('medium' if file_summary.line_rate >= 0.5 else 'low') }}">{{ (file_summary.line_rate * 100) | round(1) }}%</div>
+      <div class="label">Line Coverage ({{ file_summary.covered_lines }}/{{ file_summary.total_lines }})</div>
+    </div>
+    <div class="summary-item">
+      <div class="value rate-{{ 'good' if file_summary.branch_rate >= 0.8 else ('medium' if file_summary.branch_rate >= 0.5 else 'low') }}">{{ (file_summary.branch_rate * 100) | round(1) }}%</div>
+      <div class="label">Branch Coverage ({{ file_summary.covered_branches }}/{{ file_summary.total_branches }})</div>
+    </div>
+  </div>
+  <div class="source-listing">
+    {% for line in lines %}
+    <div class="source-line {{ line.css_class }}">
+      <span class="line-number">{{ line.number }}</span>
+      <span class="line-content">{{ line.source }}</span>
+      <span class="line-hits">{{ line.hits }}x</span>
+    </div>
+    {% endfor %}
+  </div>
+</body>
+</html>

gd_tools/coverage/templates/index.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Coverage Report</title>
+  <style>
+    body { font-family: sans-serif; margin: 2em; color: #333; }
+    h1 { margin-bottom: 0.5em; }
+    .summary-bar {
+      display: flex; gap: 2em; margin-bottom: 2em;
+      padding: 1em; background: #f5f5f5; border-radius: 4px;
+    }
+    .summary-item { text-align: center; }
+    .summary-item .value { font-size: 1.8em; font-weight: bold; }
+    .summary-item .label { font-size: 0.9em; color: #666; }
+    .rate-good { color: #2e7d32; }
+    .rate-medium { color: #f57f17; }
+    .rate-low { color: #c62828; }
+    table { border-collapse: collapse; width: 100%; }
+    th, td { border: 1px solid #ddd; padding: 0.5em 1em; text-align: left; }
+    th { background: #f0f0f0; cursor: pointer; user-select: none; }
+    th:hover { background: #e0e0e0; }
+    th.sorted-asc::after { content: " \\25B2"; }
+    th.sorted-desc::after { content: " \\25BC"; }
+    tr:nth-child(even) { background: #f9f9f9; }
+    td.rate { font-family: monospace; }
+    a { color: #1565c0; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <h1>Coverage Report</h1>
+  <div class="summary-bar">
+    <div class="summary-item">
+      <div class="value rate-{{ 'good' if summary.line_rate >= 0.8 else ('medium' if summary.line_rate >= 0.5 else 'low') }}">{{ (summary.line_rate * 100) | round(1) }}%</div>
+      <div class="label">Line Coverage ({{ summary.covered_lines }}/{{ summary.total_lines }})</div>
+    </div>
+    <div class="summary-item">
+      <div class="value rate-{{ 'good' if summary.branch_rate >= 0.8 else ('medium' if summary.branch_rate >= 0.5 else 'low') }}">{{ (summary.branch_rate * 100) | round(1) }}%</div>
+      <div class="label">Branch Coverage ({{ summary.covered_branches }}/{{ summary.total_branches }})</div>
+    </div>
+  </div>
+  <table id="file-table">
+    <thead>
+      <tr>
+        <th data-sort="file" onclick="sortTable(0)">File</th>
+        <th data-sort="lines" onclick="sortTable(1)">Lines (found/hit)</th>
+        <th data-sort="line-pct" onclick="sortTable(2)">Line %</th>
+        <th data-sort="branches" onclick="sortTable(3)">Branches (found/hit)</th>
+        <th data-sort="branch-pct" onclick="sortTable(4)">Branch %</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for fs in file_summaries %}
+      <tr>
+        <td><a href="file_{{ fs.file_id }}.html">{{ fs.path }}</a></td>
+        <td>{{ fs.total_lines }}/{{ fs.covered_lines }}</td>
+        <td class="rate">{{ (fs.line_rate * 100) | round(1) }}%</td>
+        <td>{{ fs.total_branches }}/{{ fs.covered_branches }}</td>
+        <td class="rate">{{ (fs.branch_rate * 100) | round(1) }}%</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  <script>
+    function sortTable(colIndex) {
+      var table = document.getElementById("file-table");
+      var tbody = table.querySelector("tbody");
+      var rows = Array.from(tbody.querySelectorAll("tr"));
+      var ths = table.querySelectorAll("th");
+      var th = ths[colIndex];
+      var ascending = !th.classList.contains("sorted-asc");
+      ths.forEach(function(t) { t.classList.remove("sorted-asc", "sorted-desc"); });
+      th.classList.add(ascending ? "sorted-asc" : "sorted-desc");
+      rows.sort(function(a, b) {
+        var av = a.cells[colIndex].textContent.trim();
+        var bv = b.cells[colIndex].textContent.trim();
+        var an = parseFloat(av);
+        var bn = parseFloat(bv);
+        if (!isNaN(an) && !isNaN(bn)) {
+          return ascending ? an - bn : bn - an;
+        }
+        return ascending ? av.localeCompare(bv) : bv.localeCompare(av);
+      });
+      rows.forEach(function(r) { tbody.appendChild(r); });
+    }
+  </script>
+</body>
+</html>