cctx-cli 1.13.0__tar.gz → 1.14.0__tar.gz

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- version list -->
 
+## v1.14.0 (2026-06-20)
+
+### Features
+
+- Savings framing + health grade behind --health flag (#101)
+  ([#122](https://github.com/jacquardlabs/cctx/pull/122),
+  [`ee4bc28`](https://github.com/jacquardlabs/cctx/commit/ee4bc2833d7260275e95666ba45a5952aa174aee))
+
+
 ## v1.13.0 (2026-06-20)
 
 ### Documentation

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.13.0
+Version: 1.14.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "1.13.0"
+__version__ = "1.14.0"

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/cctx/cli.py

@@ -346,6 +346,13 @@ def ls(project: Path | None) -> None:
     help="Print one verdict line only when findings exist; nothing if clean. "
          "Designed for SessionEnd hook use (cctx init).",
 )
+@click.option(
+    "--health",
+    "health",
+    is_flag=True,
+    default=False,
+    help="Show health grade (A–F) and per-finding savings estimate.",
+)
 def autopsy(
     target: Path | None,
     since: str | None,
@@ -358,6 +365,7 @@ def autopsy(
     turn_num: int | None,
     json_out: bool,
     quiet: bool,
+    health: bool,
 ) -> None:
     """Diagnose a session or project directory.
 
@@ -488,7 +496,7 @@ def autopsy(
             from cctx.renderers.github import write_github_summary
             write_github_summary(diagnosis)
         else:
-            render_diagnosis(diagnosis, session_path=target)
+            render_diagnosis(diagnosis, session_path=target, show_health=health)
         if fail_on_findings and diagnosis.findings:
             raise SystemExit(1)
 

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/cctx/renderers/terminal.py

@@ -45,11 +45,35 @@ def _wide_console() -> Console:
     return Console(width=200)
 
 
+def compute_health_grade(diagnosis: Diagnosis) -> str:
+    """A–F grade based on waste fraction and finding severity."""
+    if not diagnosis.findings:
+        return "A"
+
+    has_high = any(f.severity == Severity.HIGH for f in diagnosis.findings)
+    waste_frac = (
+        diagnosis.waste_cost_usd / diagnosis.total_cost_usd
+        if diagnosis.total_cost_usd > 0
+        else 0.0
+    )
+
+    if has_high and waste_frac > 0.50:
+        return "F"
+    if has_high or waste_frac > 0.25:
+        return "D"
+    if waste_frac > 0.10:
+        return "C"
+    if diagnosis.findings:
+        return "B"
+    return "A"
+
+
 def render_diagnosis(
     diagnosis: Diagnosis,
     *,
     session_path: Path | None = None,
     console: Console | None = None,
+    show_health: bool = False,
 ) -> None:
     con = console or _default_console()
 
@@ -77,6 +101,15 @@ def render_diagnosis(
         "~85–95% of actual billing; system framing not observable in JSONL", style="dim"
     ))
 
+    if show_health:
+        grade = compute_health_grade(diagnosis)
+        waste_frac = (
+            diagnosis.waste_cost_usd / diagnosis.total_cost_usd * 100
+            if diagnosis.total_cost_usd > 0
+            else 0.0
+        )
+        con.print(f"Health grade: {grade}  (waste {waste_frac:.0f}% of session cost)")
+
     if diagnosis.subagent_costs:
         show_depth = any(a.depth > 1 for a in diagnosis.subagent_costs)
         tbl = Table(show_header=True, header_style="bold", box=None, padding=(0, 1))
@@ -107,6 +140,8 @@ def render_diagnosis(
         badge = Text(f" {label} ", style=style)
         conf_note = f"({finding.confidence.value} confidence)"
         con.print(badge, conf_note, "—", finding.summary)
+        if show_health and finding.cost_usd is not None:
+            con.print(f"  → savings if fixed: ~${finding.cost_usd:.2f}")
 
     # Patches
     if diagnosis.patches:

{cctx_cli-1.13.0 → cctx_cli-1.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.13.0"
+version = "1.14.0"
 description = "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md"
 readme = "README.md"
 requires-python = ">=3.10"

cctx_cli-1.14.0/tests/test_savings_framing.py

@@ -0,0 +1,202 @@
+"""Tests for health grade and savings framing (issue #101).
+
+Tests cover:
+- compute_health_grade() grade logic for all A–F outcomes
+- render_diagnosis() with show_health=True smoke test
+"""
+from __future__ import annotations
+
+import io
+from datetime import datetime, timezone
+
+import pytest
+
+from cctx.models import Confidence, Diagnosis, Finding, FindingKind, Severity
+from cctx.renderers.terminal import compute_health_grade, render_diagnosis
+
+_TS = datetime(2026, 6, 1, tzinfo=timezone.utc)
+
+
+def _diagnosis(
+    findings: list[Finding],
+    total_cost: float = 1.0,
+    waste_cost: float = 0.0,
+) -> Diagnosis:
+    return Diagnosis(
+        session_id="test-session",
+        findings=findings,
+        inflection_turn=None,
+        patches=[],
+        total_cost_usd=total_cost,
+        waste_cost_usd=waste_cost,
+        analysed_at=_TS,
+        subagent_costs=[],
+    )
+
+
+def _finding(severity: Severity = Severity.MEDIUM, cost: float | None = None) -> Finding:
+    return Finding(
+        kind=FindingKind.RETRY_LOOP,
+        severity=severity,
+        confidence=Confidence.HIGH,
+        first_turn=1,
+        last_turn=5,
+        evidence={},
+        cost_usd=cost,
+        summary="test finding",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Grade logic
+# ---------------------------------------------------------------------------
+
+
+def test_grade_no_findings_is_a():
+    diag = _diagnosis(findings=[], total_cost=1.0, waste_cost=0.0)
+    assert compute_health_grade(diag) == "A"
+
+
+def test_grade_findings_low_waste_is_b():
+    """Findings present, waste < 10% → B."""
+    diag = _diagnosis(
+        findings=[_finding()],
+        total_cost=1.0,
+        waste_cost=0.05,  # 5%
+    )
+    assert compute_health_grade(diag) == "B"
+
+
+def test_grade_findings_moderate_waste_is_c():
+    """Findings present, waste 15% (>10%, ≤25%) → C."""
+    diag = _diagnosis(
+        findings=[_finding()],
+        total_cost=1.0,
+        waste_cost=0.15,  # 15%
+    )
+    assert compute_health_grade(diag) == "C"
+
+
+def test_grade_findings_high_waste_is_d():
+    """Findings present, waste 30% (>25%) → D."""
+    diag = _diagnosis(
+        findings=[_finding()],
+        total_cost=1.0,
+        waste_cost=0.30,  # 30%
+    )
+    assert compute_health_grade(diag) == "D"
+
+
+def test_grade_high_severity_low_waste_is_d():
+    """HIGH severity finding with waste < 25% → D (severity alone triggers D)."""
+    diag = _diagnosis(
+        findings=[_finding(severity=Severity.HIGH)],
+        total_cost=1.0,
+        waste_cost=0.10,  # 10% — not above 25%, but HIGH severity still triggers D
+    )
+    assert compute_health_grade(diag) == "D"
+
+
+def test_grade_high_severity_high_waste_is_f():
+    """HIGH severity finding + waste > 50% → F."""
+    diag = _diagnosis(
+        findings=[_finding(severity=Severity.HIGH)],
+        total_cost=1.0,
+        waste_cost=0.60,  # 60%
+    )
+    assert compute_health_grade(diag) == "F"
+
+
+def test_grade_zero_cost_session_with_findings_is_b():
+    """Zero-cost session (total=0, waste=0) with findings → waste_frac=0 → B."""
+    diag = _diagnosis(
+        findings=[_finding()],
+        total_cost=0.0,
+        waste_cost=0.0,
+    )
+    assert compute_health_grade(diag) == "B"
+
+
+# ---------------------------------------------------------------------------
+# render_diagnosis smoke test with show_health=True
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def make_diagnosis():
+    """Factory fixture: returns a callable that produces a Diagnosis."""
+    def _make(
+        findings: list[Finding] | None = None,
+        total_cost: float = 1.0,
+        waste_cost: float = 0.20,
+    ) -> Diagnosis:
+        if findings is None:
+            findings = [_finding(severity=Severity.MEDIUM, cost=0.20)]
+        return _diagnosis(findings, total_cost=total_cost, waste_cost=waste_cost)
+    return _make
+
+
+def test_render_diagnosis_with_health_does_not_raise(make_diagnosis):
+    from rich.console import Console
+
+    buf = io.StringIO()
+    con = Console(file=buf, width=120, highlight=False, markup=False)
+    render_diagnosis(make_diagnosis(), show_health=True, console=con)
+    output = buf.getvalue()
+    assert "Health grade:" in output
+
+
+def test_render_diagnosis_health_grade_visible(make_diagnosis):
+    from rich.console import Console
+
+    buf = io.StringIO()
+    con = Console(file=buf, width=120, highlight=False, markup=False)
+    # waste_cost=0.20 on total_cost=1.0 → 20% waste → grade C
+    render_diagnosis(make_diagnosis(waste_cost=0.20), show_health=True, console=con)
+    output = buf.getvalue()
+    assert "Health grade: C" in output
+
+
+def test_render_diagnosis_savings_line_shown(make_diagnosis):
+    """When show_health=True and finding has cost_usd, savings line appears."""
+    from rich.console import Console
+
+    buf = io.StringIO()
+    con = Console(file=buf, width=120, highlight=False, markup=False)
+    findings = [_finding(cost=0.42)]
+    render_diagnosis(
+        _diagnosis(findings, total_cost=1.0, waste_cost=0.42),
+        show_health=True,
+        console=con,
+    )
+    output = buf.getvalue()
+    assert "savings if fixed" in output
+    assert "0.42" in output
+
+
+def test_render_diagnosis_no_savings_when_cost_is_none(make_diagnosis):
+    """When finding.cost_usd is None, no savings line appears."""
+    from rich.console import Console
+
+    buf = io.StringIO()
+    con = Console(file=buf, width=120, highlight=False, markup=False)
+    findings = [_finding(cost=None)]
+    render_diagnosis(
+        _diagnosis(findings, total_cost=1.0, waste_cost=0.0),
+        show_health=True,
+        console=con,
+    )
+    output = buf.getvalue()
+    assert "savings if fixed" not in output
+
+
+def test_render_diagnosis_health_hidden_by_default(make_diagnosis):
+    """Without show_health=True, no health grade or savings appear."""
+    from rich.console import Console
+
+    buf = io.StringIO()
+    con = Console(file=buf, width=120, highlight=False, markup=False)
+    render_diagnosis(make_diagnosis(), show_health=False, console=con)
+    output = buf.getvalue()
+    assert "Health grade:" not in output
+    assert "savings if fixed" not in output