cargo-rail-action: condense planner summaries with reason counts and

trace previews

Author: loadingalias

scripts/render_summary.py

@@ -6,6 +6,7 @@
 import argparse
 import json
 import os
+from collections import Counter
 
 INSTALL_MAP = {
   "binary": "Binary download",
@@ -14,6 +15,10 @@
   "cached": "Already installed",
 }
 
+LIST_PREVIEW_LIMIT = 12
+TRACE_PREVIEW_LIMIT = 20
+REASON_COUNT_PREVIEW_LIMIT = 8
+
 # Map reason codes to human-readable descriptions
 REASON_DESCRIPTIONS = {
   "FILE_KIND_RUST_SRC": "Rust source file changed",
@@ -101,6 +106,45 @@ def collect_active_reason_ids(surfaces: dict) -> list[int]:
   return sorted(reason_ids)
 
 
+def preview_items(items: list[str], limit: int = LIST_PREVIEW_LIMIT) -> str:
+  """Render a stable preview for a potentially large list."""
+  if not items:
+    return "none"
+
+  preview = items[: max(limit, 1)]
+  rendered = ", ".join(preview)
+  if len(items) <= limit:
+    return rendered
+  return f"{rendered}, ... +{len(items) - limit} more"
+
+
+def summarize_reason_counts(trace: list[dict]) -> list[tuple[str, int]]:
+  """Count reason codes across the full trace."""
+  counts = Counter(item.get("code", "UNKNOWN") for item in trace)
+  return sorted(counts.items(), key=lambda item: (-item[1], item[0]))
+
+
+def render_trace_entry(item: dict) -> str:
+  """Render a single raw trace entry."""
+  rid = item.get("id")
+  code = item.get("code", "")
+  file_path = item.get("file")
+  crate_name = item.get("crate")
+  depends_on = item.get("depends_on")
+  surface = item.get("surface")
+
+  parts = [f"r{rid}", code]
+  if file_path:
+    parts.append(f"file={file_path}")
+  if crate_name:
+    parts.append(f"crate={crate_name}")
+  if depends_on:
+    parts.append(f"depends_on={depends_on}")
+  if surface:
+    parts.append(f"surface={surface}")
+  return f"- {' '.join(parts)}"
+
+
 def render(args: argparse.Namespace, plan: dict) -> str:
   files = [f.get("path", "") for f in plan.get("files", []) if f.get("path")]
   impact = plan.get("impact", {})
@@ -140,37 +184,37 @@ def render(args: argparse.Namespace, plan: dict) -> str:
   lines.append("")
 
   if direct:
-    lines.append(f"**Changed direct crates:** `{ ' '.join(direct) }`")
+    lines.append(f"**Changed direct crates ({len(direct)}):** `{preview_items(direct)}`")
   if scope_mode == "crates" and scope_crates:
-    lines.append(f"**Execution crates:** `{ ' '.join(scope_crates) }`")
+    lines.append(f"**Execution crates ({len(scope_crates)}):** `{preview_items(scope_crates)}`")
   elif scope_mode == "workspace":
     lines.append("**Execution scope:** full workspace")
   if active_custom_surfaces:
-    lines.append(f"**Active custom surfaces:** `{ ' '.join(active_custom_surfaces) }`")
+    lines.append(f"**Active custom surfaces:** `{preview_items(active_custom_surfaces)}`")
   lines.append(f"**Top reasons:** {top_reasons}")
 
   lines.append("")
-  lines.append("<details><summary>Trace details (file -> crate -> surface)</summary>")
+  lines.append(f"<details><summary>Trace summary ({len(trace)} reasons)</summary>")
   lines.append("")
 
-  for item in trace:
-    rid = item.get("id")
-    code = item.get("code", "")
-    file_path = item.get("file")
-    crate_name = item.get("crate")
-    depends_on = item.get("depends_on")
-    surface = item.get("surface")
-
-    parts = [f"r{rid}", code]
-    if file_path:
-      parts.append(f"file={file_path}")
-    if crate_name:
-      parts.append(f"crate={crate_name}")
-    if depends_on:
-      parts.append(f"depends_on={depends_on}")
-    if surface:
-      parts.append(f"surface={surface}")
-    lines.append(f"- {' '.join(parts)}")
+  reason_counts = summarize_reason_counts(trace)
+  if reason_counts:
+    lines.append("**Reason counts**")
+    for code, count in reason_counts[:REASON_COUNT_PREVIEW_LIMIT]:
+      desc = REASON_DESCRIPTIONS.get(code, code)
+      lines.append(f"- {desc}: {count}")
+    if len(reason_counts) > REASON_COUNT_PREVIEW_LIMIT:
+      lines.append(f"- ... +{len(reason_counts) - REASON_COUNT_PREVIEW_LIMIT} more reason types")
+    lines.append("")
+
+  if trace:
+    lines.append(f"**Sample trace entries ({min(len(trace), TRACE_PREVIEW_LIMIT)} of {len(trace)})**")
+    for item in trace[:TRACE_PREVIEW_LIMIT]:
+      lines.append(render_trace_entry(item))
+    if len(trace) > TRACE_PREVIEW_LIMIT:
+      lines.append(f"- ... +{len(trace) - TRACE_PREVIEW_LIMIT} more trace entries")
+  else:
+    lines.append("No trace reasons.")
 
   lines.append("")
   lines.append("</details>")

tests/golden/summary_docs_only.md

@@ -12,8 +12,12 @@
 
 **Top reasons:** Documentation changed
 
-<details><summary>Trace details (file -> crate -> surface)</summary>
+<details><summary>Trace summary (1 reasons)</summary>
 
+**Reason counts**
+- Documentation changed: 1
+
+**Sample trace entries (1 of 1)**
 - r1 FILE_KIND_DOCS file=README.md surface=docs
 
 </details>

tests/golden/summary_rust_src.md

@@ -10,12 +10,18 @@
 | **Direct crates** | 1 |
 | **Active surfaces** | build, test |
 
-**Changed direct crates:** `lib-a`
+**Changed direct crates (1):** `lib-a`
 **Execution scope:** full workspace
 **Top reasons:** Rust source file changed; Transitive dependency of changed crate
 
-<details><summary>Trace details (file -> crate -> surface)</summary>
+<details><summary>Trace summary (3 reasons)</summary>
 
+**Reason counts**
+- Rust source file changed: 1
+- File directly owns crate: 1
+- Transitive dependency of changed crate: 1
+
+**Sample trace entries (3 of 3)**
 - r1 FILE_OWNS_CRATE_DIRECT file=crates/lib-a/src/lib.rs crate=lib-a
 - r2 FILE_KIND_RUST_SRC file=crates/lib-a/src/lib.rs surface=build
 - r3 TRANSITIVE_DEPENDS_ON_DIRECT crate=lib-b depends_on=lib-a surface=build

tests/test_summary.sh

@@ -27,4 +27,47 @@ diff -u "$ROOT/tests/golden/summary_rust_src.md" "$TMP_DIR/summary_rust_src.md"
 run_summary "$ROOT/tests/fixtures/plan_docs_only.json" "$TMP_DIR/summary_docs_only.md"
 diff -u "$ROOT/tests/golden/summary_docs_only.md" "$TMP_DIR/summary_docs_only.md"
 
+python3 - <<'PY' > "$TMP_DIR/plan_large.json"
+import json
+
+trace = []
+trace.append({"id": 1, "code": "FILE_KIND_RUST_SRC", "file": "crates/lib-01/src/lib.rs", "surface": "build"})
+for idx in range(2, 24):
+  trace.append(
+    {
+      "id": idx,
+      "code": "TRANSITIVE_DEPENDS_ON_DIRECT",
+      "crate": f"lib-{idx:02d}",
+      "depends_on": "lib-01",
+      "surface": "build",
+    }
+  )
+
+plan = {
+  "files": [{"path": "crates/lib-01/src/lib.rs"}],
+  "impact": {
+    "direct_crates": [f"lib-{idx:02d}" for idx in range(1, 15)],
+    "transitive_crates": [f"dep-{idx:02d}" for idx in range(1, 5)],
+  },
+  "surfaces": {
+    "build": {"enabled": True, "reasons": list(range(1, 24))},
+    "test": {"enabled": True, "reasons": list(range(1, 24))},
+  },
+  "scope": {
+    "mode": "crates",
+    "crates": [f"pkg-{idx:02d}" for idx in range(1, 17)],
+    "surfaces": {"build": True, "test": True},
+  },
+  "trace": trace,
+}
+
+print(json.dumps(plan))
+PY
+
+run_summary "$TMP_DIR/plan_large.json" "$TMP_DIR/summary_large.md"
+grep -F "**Changed direct crates (14):** \`lib-01, lib-02, lib-03, lib-04, lib-05, lib-06, lib-07, lib-08, lib-09, lib-10, lib-11, lib-12, ... +2 more\`" "$TMP_DIR/summary_large.md"
+grep -F "**Execution crates (16):** \`pkg-01, pkg-02, pkg-03, pkg-04, pkg-05, pkg-06, pkg-07, pkg-08, pkg-09, pkg-10, pkg-11, pkg-12, ... +4 more\`" "$TMP_DIR/summary_large.md"
+grep -F "**Sample trace entries (20 of 23)**" "$TMP_DIR/summary_large.md"
+grep -F -- "- ... +3 more trace entries" "$TMP_DIR/summary_large.md"
+
 echo "summary tests passed"