feat(cli): add GitHub report format with snapshot-based trends summary

Author: akhundMurad

pacta/cli/_trends.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime
+
+from pacta.reporting.types import Report, TrendPoint, TrendSummary
+from pacta.snapshot.store import FsSnapshotStore
+
+
+def attach_trends(
+    report: Report,
+    *,
+    repo_root: str,
+    last: int = 5,
+) -> Report:
+    """
+    Load recent snapshots and attach a TrendSummary to the report.
+
+    Returns the report unchanged if no history is available.
+    """
+    try:
+        store = FsSnapshotStore(repo_root=repo_root)
+        objects = store.list_objects()
+    except Exception:
+        return report
+
+    if len(objects) < 2:
+        return report
+
+    # Take the most recent N entries (list_objects returns newest-first)
+    entries = objects[:last]
+    # Reverse to chronological order (oldest first)
+    entries = list(reversed(entries))
+
+    points: list[TrendPoint] = []
+    for _, snapshot in entries:
+        meta = snapshot.meta
+        node_count = float(len(snapshot.nodes))
+        edge_count = float(len(snapshot.edges))
+        violation_count = float(len(snapshot.violations))
+        density = round(edge_count / node_count, 2) if node_count > 0 else 0.0
+
+        label = _format_label(meta.created_at)
+        points.append(
+            TrendPoint(
+                label=label,
+                violations=violation_count,
+                nodes=node_count,
+                edges=edge_count,
+                density=density,
+            )
+        )
+
+    first = points[0]
+    last_pt = points[-1]
+
+    trends = TrendSummary(
+        points=tuple(points),
+        violation_change=last_pt.violations - first.violations,
+        node_change=last_pt.nodes - first.nodes,
+        edge_change=last_pt.edges - first.edges,
+        density_change=round(last_pt.density - first.density, 2),
+    )
+
+    return replace(report, trends=trends)
+
+
+def _format_label(created_at: str | None) -> str:
+    if not created_at or "T" not in created_at:
+        return created_at or "unknown"
+    try:
+        dt = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+        return dt.strftime("%b %d")
+    except ValueError:
+        return created_at.split("T")[0]

pacta/cli/check.py

@@ -1,9 +1,11 @@
 from pathlib import Path
 
 from pacta.cli._io import default_model_file, default_rules_files, ensure_repo_root
+from pacta.cli._trends import attach_trends
 from pacta.cli.exitcodes import exit_code_from_report_dict
 from pacta.core.config import EngineConfig
 from pacta.core.engine import DefaultPactaEngine
+from pacta.reporting.renderers.github import GitHubReportRenderer
 from pacta.reporting.renderers.json import JsonReportRenderer
 from pacta.reporting.renderers.text import TextReportRenderer
 from pacta.snapshot.store import FsSnapshotStore
@@ -70,7 +72,10 @@ def run(
         store.save(result.snapshot, refs=[save_ref])
 
     # Render report
-    if fmt == "json":
+    if fmt == "github":
+        report = attach_trends(result.report, repo_root=repo_root)
+        out = GitHubReportRenderer().render(report)
+    elif fmt == "json":
         out = JsonReportRenderer().render(result.report)
     else:
         out = TextReportRenderer(verbosity=verbosity).render(result.report)  # type: ignore[arg-type]

pacta/cli/main.py

@@ -14,7 +14,7 @@ def build_parser() -> argparse.ArgumentParser:
     # scan
     scan_p = sub.add_parser("scan", help="Scan repository and evaluate rules.")
     scan_p.add_argument("path", nargs="?", default=".", help="Repository root (default: .)")
-    scan_p.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+    scan_p.add_argument("--format", choices=["text", "json", "github"], default="text", help="Output format.")
     scan_p.add_argument("--rules", action="append", default=None, help="Rules file path (repeatable).")
     scan_p.add_argument("--model", default=None, help="Architecture model file (architecture.yaml).")
     scan_p.add_argument("--baseline", default=None, help="Baseline snapshot ref (e.g. baseline).")
@@ -30,7 +30,7 @@ def build_parser() -> argparse.ArgumentParser:
     check_p = sub.add_parser("check", help="Evaluate rules against a snapshot.")
     check_p.add_argument("path", nargs="?", default=".", help="Repository root (default: .)")
     check_p.add_argument("--ref", default="latest", help="Snapshot ref to check (default: latest).")
-    check_p.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+    check_p.add_argument("--format", choices=["text", "json", "github"], default="text", help="Output format.")
     check_p.add_argument("--rules", action="append", default=None, help="Rules file path (repeatable).")
     check_p.add_argument("--model", default=None, help="Architecture model file (architecture.yaml).")
     check_p.add_argument("--baseline", default=None, help="Baseline snapshot ref.")

pacta/cli/scan.py

@@ -1,6 +1,8 @@
 from pacta.cli._engine_adapter import run_engine_scan
 from pacta.cli._io import default_model_file, default_rules_files, ensure_repo_root
+from pacta.cli._trends import attach_trends
 from pacta.cli.exitcodes import exit_code_from_report_dict
+from pacta.reporting.renderers.github import GitHubReportRenderer
 from pacta.reporting.renderers.json import JsonReportRenderer
 from pacta.reporting.renderers.text import TextReportRenderer
 
@@ -32,7 +34,10 @@ def run(
         tool_version=tool_version,
     )
 
-    if fmt == "json":
+    if fmt == "github":
+        report = attach_trends(report, repo_root=repo_root)
+        out = GitHubReportRenderer().render(report)
+    elif fmt == "json":
         out = JsonReportRenderer().render(report)
     else:
         out = TextReportRenderer(verbosity=verbosity).render(report)  # type: ignore[arg-type]