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

gd_tools/coverage/cobertura_reporter.py

@@ -0,0 +1,136 @@
+"""Cobertura XML coverage reporter.
+
+Generates Cobertura XML files compatible with Jenkins and GitLab CI
+coverage parsers using the standard library ``xml.etree.ElementTree``.
+"""
+
+from pathlib import Path
+import xml.etree.ElementTree as ET
+
+from gd_tools.coverage.plan_generator import CoveragePlan, FilePlan
+from gd_tools.coverage.reporter import CoverageData, FileCoverage
+
+
+def generate_cobertura_report(
+    plan: CoveragePlan,
+    data: CoverageData,
+    output_path: Path,
+) -> Path:
+    """Generate a Cobertura XML file from plan and coverage data.
+
+    Args:
+        plan: The instrumentation plan.
+        data: The runtime coverage data.
+        output_path: Path where the XML file is written.
+
+    Returns:
+        The path to the written file.
+    """
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    coverage_by_id = {fc.file_id: fc for fc in data.files}
+
+    total_lines = 0
+    hit_lines = 0
+    total_branches = 0
+    hit_branches = 0
+
+    root = ET.Element("coverage")
+    packages_elem = ET.SubElement(root, "packages")
+    package_elem = ET.SubElement(packages_elem, "package")
+    classes_elem = ET.SubElement(package_elem, "classes")
+
+    for file_plan in plan.files:
+        file_data = coverage_by_id.get(
+            file_plan.file_id,
+            FileCoverage(file_id=file_plan.file_id, hits={}),
+        )
+        cls_lines, cls_hit, cls_br, cls_hit_br = _build_class_element(
+            file_plan, file_data, classes_elem
+        )
+        total_lines += cls_lines
+        hit_lines += cls_hit
+        total_branches += cls_br
+        hit_branches += cls_hit_br
+
+    root.set("line-rate", _format_rate(total_lines, hit_lines))
+    root.set("branch-rate", _format_rate(total_branches, hit_branches))
+    root.set("lines-covered", str(hit_lines))
+    root.set("lines-valid", str(total_lines))
+    root.set("branches-covered", str(hit_branches))
+    root.set("branches-valid", str(total_branches))
+
+    tree = ET.ElementTree(root)
+    ET.indent(tree, space="  ")
+    tree.write(output_path, encoding="utf-8", xml_declaration=True)
+    return output_path
+
+
+def _build_class_element(
+    file_plan: FilePlan,
+    file_data: FileCoverage,
+    classes_elem: ET.Element,
+) -> tuple[int, int, int, int]:
+    """Build a ``<class>`` element for a single file.
+
+    Args:
+        file_plan: The file's instrumentation plan.
+        file_data: The file's coverage data.
+        classes_elem: The parent ``<classes>`` element.
+
+    Returns:
+        A tuple of (total_lines, hit_lines, total_branches, hit_branches).
+    """
+    cls_elem = ET.SubElement(classes_elem, "class")
+    cls_elem.set("filename", file_plan.path)
+
+    lines_elem = ET.SubElement(cls_elem, "lines")
+
+    total_lines = 0
+    hit_lines = 0
+    total_branches = 0
+    hit_branches = 0
+
+    for line_plan in file_plan.lines:
+        hit_count = file_data.hits.get(str(line_plan.id), 0)
+        line_elem = ET.SubElement(lines_elem, "line")
+        line_elem.set("number", str(line_plan.line))
+        line_elem.set("hits", str(hit_count))
+
+        total_lines += 1
+        if hit_count > 0:
+            hit_lines += 1
+
+        if line_plan.type == "branch":
+            line_elem.set("branch", "true")
+            total_branches += 1
+            if hit_count > 0:
+                hit_branches += 1
+            coverage_pct = 100 if hit_count > 0 else 0
+            line_elem.set(
+                "condition-coverage",
+                f"{coverage_pct}% ({1 if hit_count > 0 else 0}/1)",
+            )
+        else:
+            line_elem.set("branch", "false")
+
+    cls_elem.set("line-rate", _format_rate(total_lines, hit_lines))
+    cls_elem.set("branch-rate", _format_rate(total_branches, hit_branches))
+
+    return total_lines, hit_lines, total_branches, hit_branches
+
+
+def _format_rate(total: int, hit: int) -> str:
+    """Format a coverage rate as a decimal string.
+
+    Args:
+        total: Total count of items.
+        hit: Count of covered items.
+
+    Returns:
+        A string like ``"0.625"`` or ``"0.0"``.
+    """
+    if total == 0:
+        return "0.0"
+    return f"{hit / total:.4f}".rstrip("0").rstrip(".")

gd_tools/coverage/html_reporter.py

@@ -0,0 +1,95 @@
+"""HTML coverage reporter using Jinja2 templates.
+
+Generates an ``index.html`` summary page and one per-file HTML page
+with line-level coverage highlighting (green/red/yellow).
+"""
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+from gd_tools.coverage.plan_generator import CoveragePlan
+from gd_tools.coverage.reporter import (
+    CoverageData,
+    FileCoverage,
+    compute_file_summary,
+    compute_summary,
+)
+
+_TEMPLATES_DIR = Path(__file__).parent / "templates"
+_env = Environment(
+    loader=FileSystemLoader(str(_TEMPLATES_DIR)), autoescape=True
+)
+
+
+def generate_html_report(
+    plan: CoveragePlan,
+    data: CoverageData,
+    output_dir: Path,
+) -> Path:
+    """Generate an HTML coverage report with index and per-file pages.
+
+    Creates ``index.html`` with a summary table and one ``file_<id>.html``
+    per source file showing line-by-line coverage status with CSS
+    highlighting (covered=green, uncovered=red, partial=yellow).
+
+    Args:
+        plan: The instrumentation plan defining tracked lines.
+        data: The runtime coverage data with hit counts.
+        output_dir: Directory where HTML files are written.
+
+    Returns:
+        Path to the generated ``index.html``.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    summary = compute_summary(plan, data)
+
+    coverage_by_id = {fc.file_id: fc for fc in data.files}
+    file_summaries = []
+    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))
+
+    index_template = _env.get_template("index.html")
+    index_content = index_template.render(
+        summary=summary, file_summaries=file_summaries
+    )
+    index_path = output_dir / "index.html"
+    index_path.write_text(index_content, encoding="utf-8")
+
+    file_template = _env.get_template("file.html")
+    for file_plan, fs in zip(plan.files, file_summaries):
+        file_data = coverage_by_id.get(
+            file_plan.file_id,
+            FileCoverage(file_id=file_plan.file_id, hits={}),
+        )
+        lines = []
+        for line_plan in file_plan.lines:
+            hit_count = file_data.hits.get(str(line_plan.id), 0)
+            if hit_count > 0 and line_plan.type == "branch":
+                css_class = "partial"
+            elif hit_count > 0:
+                css_class = "covered"
+            else:
+                css_class = "uncovered"
+            lines.append(
+                {
+                    "number": line_plan.line,
+                    "hits": hit_count,
+                    # TODO: Source code display deferred — requires reading
+                    # .gd files from disk. Spec FR-4.3 partially met: line
+                    # numbers shown, source content not yet populated.
+                    "source": "",
+                    "css_class": css_class,
+                }
+            )
+        file_content = file_template.render(file_summary=fs, lines=lines)
+        file_path = output_dir / f"file_{file_plan.file_id}.html"
+        file_path.write_text(file_content, encoding="utf-8")
+
+    return index_path

gd_tools/coverage/lcov_reporter.py

@@ -0,0 +1,90 @@
+"""LCOV format coverage reporter.
+
+Generates LCOV ``.info`` files compatible with codecov.io, coveralls,
+and ``genhtml``.
+"""
+
+from pathlib import Path
+
+from gd_tools.coverage.plan_generator import CoveragePlan, FilePlan
+from gd_tools.coverage.reporter import CoverageData, FileCoverage
+
+_TEST_NAME = "gd-tools"
+
+
+def generate_lcov_report(
+    plan: CoveragePlan,
+    data: CoverageData,
+    output_path: Path,
+) -> Path:
+    """Generate an LCOV ``.info`` file from plan and coverage data.
+
+    Args:
+        plan: The instrumentation plan.
+        data: The runtime coverage data.
+        output_path: Path where the ``.info`` file is written.
+
+    Returns:
+        The path to the written file.
+    """
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    coverage_by_id = {fc.file_id: fc for fc in data.files}
+
+    lines: list[str] = [f"TN:{_TEST_NAME}"]
+
+    for file_plan in plan.files:
+        file_data = coverage_by_id.get(
+            file_plan.file_id,
+            FileCoverage(file_id=file_plan.file_id, hits={}),
+        )
+        lines.extend(_generate_file_records(file_plan, file_data))
+
+    output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return output_path
+
+
+def _generate_file_records(
+    file_plan: FilePlan,
+    file_data: FileCoverage,
+) -> list[str]:
+    """Generate LCOV records for a single file.
+
+    Args:
+        file_plan: The file's instrumentation plan.
+        file_data: The file's coverage data.
+
+    Returns:
+        A list of LCOV record strings for this file section.
+    """
+    records: list[str] = [f"SF:{file_plan.path}"]
+
+    total_lines = 0
+    hit_lines = 0
+    total_branches = 0
+    hit_branches = 0
+    brda_records: list[str] = []
+
+    for line_plan in file_plan.lines:
+        hit_count = file_data.hits.get(str(line_plan.id), 0)
+        records.append(f"DA:{line_plan.line},{hit_count}")
+
+        total_lines += 1
+        if hit_count > 0:
+            hit_lines += 1
+
+        if line_plan.type == "branch":
+            total_branches += 1
+            if hit_count > 0:
+                hit_branches += 1
+            brda_records.append(f"BRDA:{line_plan.line},0,0,{hit_count}")
+
+    records.extend(brda_records)
+    records.append(f"BRF:{total_branches}")
+    records.append(f"BRH:{hit_branches}")
+    records.append(f"LF:{total_lines}")
+    records.append(f"LH:{hit_lines}")
+    records.append("end_of_record")
+
+    return records

gd_tools/coverage/orchestrator.py

@@ -0,0 +1,282 @@
+"""Coverage orchestrator module.
+
+Coordinates the full coverage flow by wiring together the plan generator,
+test runner, and reporter modules.  This is the orchestration layer mandated
+by NFR-1 — CLI commands delegate to these functions rather than embedding
+business logic directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from gd_tools.config import GdToolsConfig, find_project_root
+from gd_tools.coverage import plan_generator, reporter
+from gd_tools.coverage.reporter import (
+    CoverageData,
+    CoverageSummary,
+    ReportResult,
+)
+from gd_tools.errors import CoverageThresholdError, TestFailureError
+from gd_tools.test_runner import TestResult, run_tests
+
+
+def run_coverage_test(
+    config: GdToolsConfig,
+    suite: str | None = None,
+    test_name: str | None = None,
+    junit_xml: str | None = None,
+    no_exit_code: bool = False,
+    min_percent: int | None = None,
+    timeout: int | None = None,
+) -> TestResult:
+    """Run tests with coverage instrumentation and generate reports.
+
+    Orchestrates the full coverage flow:
+
+    1. Generate an instrumentation plan.
+    2. Write the plan to ``<output_dir>/plan.json``.
+    3. Run tests with coverage enabled.
+    4. Read the coverage data produced by the runtime hooks.
+    5. Generate reports in the configured format.
+
+    Error precedence (NFR-2): ``TestFailureError`` is re-raised before
+    ``CoverageThresholdError`` when both occur.
+
+    Args:
+        config: Project configuration.
+        suite: Optional test suite filter.
+        test_name: Optional specific test to run.
+        junit_xml: Optional JUnit XML output path.
+        no_exit_code: If True, test failures do not raise
+            :class:`TestFailureError`.
+        min_percent: Minimum coverage percentage (0-100). If set and
+            coverage is below this, raises
+            :class:`CoverageThresholdError`.
+        timeout: Optional test timeout in seconds.
+
+    Returns:
+        The :class:`TestResult` from running tests.
+
+    Raises:
+        TestFailureError: If tests fail (unless ``no_exit_code`` is True).
+        CoverageThresholdError: If coverage is below ``min_percent``.
+    """
+    project_root = find_project_root()
+    output_dir = project_root / config.coverage.output_dir
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate and write instrumentation plan.
+    plan = plan_generator.generate_plan(
+        str(project_root),
+        None,
+        config.coverage.exclude,
+        config.coverage.test_dirs,
+    )
+    plan_generator.write_plan_json(plan, str(output_dir / "plan.json"))
+
+    # Run tests with coverage enabled.
+    test_error: TestFailureError | None = None
+    result: TestResult | None = None
+    try:
+        result = run_tests(
+            config,
+            coverage=True,
+            min_percent=min_percent,
+            suite=suite,
+            test_name=test_name,
+            junit_xml=junit_xml,
+            no_exit_code=no_exit_code,
+            timeout=timeout,
+        )
+    except TestFailureError as exc:
+        test_error = exc
+
+    # Read coverage data and generate reports (even if tests failed).
+    data = reporter.read_coverage_json(output_dir / "coverage.json")
+    plan = plan_generator.read_plan_json(str(output_dir / "plan.json"))
+
+    min_threshold = min_percent / 100 if min_percent is not None else None
+    try:
+        reporter.generate_report(
+            plan,
+            data,
+            output_dir,
+            config.coverage.format,
+            min_threshold=min_threshold,
+        )
+    except CoverageThresholdError:
+        if test_error is not None:
+            raise test_error
+        raise
+
+    if test_error is not None:
+        raise test_error
+
+    assert result is not None  # test_error is None implies run_tests succeeded
+    return result
+
+
+def generate_coverage_report(
+    config: GdToolsConfig,
+    report_format: str | None = None,
+    output_dir: str | None = None,
+) -> ReportResult:
+    """Regenerate reports from existing coverage data without re-running tests.
+
+    Reads existing ``plan.json`` and ``coverage.json`` from the output
+    directory and regenerates reports in the specified format.
+
+    Args:
+        config: Project configuration.
+        report_format: Report format override (e.g., ``"html"``, ``"lcov"``,
+            ``"cobertura"``, ``"text"``).  If ``None``, uses
+            ``config.coverage.format``.
+        output_dir: Output directory override.  If ``None``, uses
+            ``config.coverage.output_dir``.
+
+    Returns:
+        The :class:`ReportResult` from report generation.
+
+    Raises:
+        CoveragePlanError: If ``plan.json`` or ``coverage.json`` is
+            missing or invalid.
+    """
+    project_root = find_project_root()
+
+    # Resolve effective output_dir: flag > config > default.
+    effective_output_dir = (
+        output_dir if output_dir is not None else config.coverage.output_dir
+    )
+    output_path = project_root / effective_output_dir
+
+    # Resolve effective format: flag > config > default.
+    effective_format = (
+        report_format if report_format is not None else config.coverage.format
+    )
+
+    # Read existing plan and coverage data.
+    plan = plan_generator.read_plan_json(str(output_path / "plan.json"))
+    data = reporter.read_coverage_json(output_path / "coverage.json")
+
+    # Generate report.
+    return reporter.generate_report(plan, data, output_path, effective_format)
+
+
+def merge_coverage_files(
+    files: list[Path],
+    output: Path | None = None,
+    config: GdToolsConfig | None = None,
+) -> CoverageData:
+    """Merge multiple coverage data files into one.
+
+    Delegates to :func:`reporter.merge_coverage_data` to sum hit
+    counts, then writes the merged result as JSON.
+
+    Args:
+        files: List of paths to coverage data JSON files.
+        output: Path for the merged output file. If ``None``,
+            defaults to ``<output_dir>/coverage.json`` (resolved via
+            ``find_project_root`` and ``config.coverage.output_dir``
+            when ``config`` is provided, or ``.gd-tools/coverage/
+            coverage.json`` relative to the current working directory
+            otherwise).
+        config: Optional project configuration for resolving the
+            default output path.
+
+    Returns:
+        The merged :class:`CoverageData`.
+    """
+    if output is None:
+        if config is not None:
+            project_root = find_project_root()
+            output = project_root / config.coverage.output_dir / "coverage.json"
+        else:
+            output = Path.cwd() / ".gd-tools" / "coverage" / "coverage.json"
+
+    merged = reporter.merge_coverage_data(files)
+
+    reporter.write_coverage_json(merged, output)
+
+    console = Console()
+    console.print(
+        f"Merged {len(files)} file(s) → {len(merged.files)} file(s) "
+        f"in output. Written to: {output}"
+    )
+
+    return merged
+
+
+def show_coverage_summary(
+    config: GdToolsConfig,
+    min_percent: int | None = None,
+) -> CoverageSummary:
+    """Display a terminal summary table of coverage results.
+
+    Reads existing ``plan.json`` and ``coverage.json``, computes a
+    summary, prints a Rich table, and optionally enforces a minimum
+    threshold.
+
+    Args:
+        config: Project configuration.
+        min_percent: Minimum coverage percentage (0-100). If set and
+            coverage is below this, raises
+            :class:`CoverageThresholdError`.
+
+    Returns:
+        The :class:`CoverageSummary`.
+
+    Raises:
+        CoverageThresholdError: If ``min_percent`` is set and line
+            coverage is below the threshold.
+        CoveragePlanError: If ``plan.json`` or ``coverage.json`` is
+            missing or invalid.
+    """
+    project_root = find_project_root()
+    output_dir = project_root / config.coverage.output_dir
+
+    # Read plan and coverage data.
+    plan = plan_generator.read_plan_json(str(output_dir / "plan.json"))
+    data = reporter.read_coverage_json(output_dir / "coverage.json")
+
+    # Compute summary.
+    summary = reporter.compute_summary(plan, data)
+
+    # Print Rich terminal table.
+    console = Console()
+    table = Table(title="Coverage Summary")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Found", justify="right")
+    table.add_column("Hit", justify="right")
+    table.add_column("Rate", justify="right", style="green")
+
+    table.add_row(
+        "Lines",
+        str(summary.total_lines),
+        str(summary.covered_lines),
+        f"{summary.line_rate * 100:.1f}%",
+    )
+    table.add_row(
+        "Branches",
+        str(summary.total_branches),
+        str(summary.covered_branches),
+        f"{summary.branch_rate * 100:.1f}%",
+    )
+
+    console.print(table)
+
+    # Threshold check.
+    if min_percent is not None and summary.line_rate * 100 < min_percent:
+        raise CoverageThresholdError(
+            f"[Error] Line coverage {summary.line_rate * 100:.1f}% is "
+            f"below minimum threshold {min_percent}%\n"
+            f"  Cause: Only {summary.covered_lines} of "
+            f"{summary.total_lines} lines were executed.\n"
+            f"  Fix: Add tests to cover uncovered lines or lower the "
+            "--min threshold."
+        )
+
+    return summary