Add FailMap JSON CLI output

Author: Jasvina

projects/failmap/README.md

@@ -42,6 +42,7 @@ failmap issue-bundle-summary examples/bundle/bundle.json
 failmap trend examples/trends.json examples/baseline_clusters.json examples/candidate_clusters.json examples/release3_clusters.json
 failmap trend-summary examples/trends.json
 failmap trend-markdown examples/trends.json examples/trends.md
+failmap summarize examples/clusters.json --json
 ```
 
 ## Example output
@@ -53,6 +54,13 @@ By priority:
 - P0: 2
 By owner:
 - tooling: 2
+
+$ failmap summarize examples/clusters.json --json
+{
+  "case_count": 3,
+  "cluster_count": 2,
+  "format": "failmap-v1"
+}
 ```
 
 Example metadata emitted into each issue draft:
@@ -110,8 +118,11 @@ failmap issue-bundle-summary path/to/bundle.json
 failmap trend path/to/trends.json baseline.json candidate.json release3.json
 failmap trend-summary path/to/trends.json
 failmap trend-markdown path/to/trends.json path/to/report.md
+failmap compare-summary path/to/compare.json --json
 ```
 
+All summary-style commands support `--json`, and write commands like `cluster`, `compare`, `issue-drafts`, `issue-bundle`, and `trend` can also emit machine-readable output metadata.
+
 ## Cluster fields
 
 Each cluster contains:

projects/failmap/src/failmap/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 from pathlib import Path
 import sys
 
@@ -20,61 +21,118 @@
 from .trends import build_trend_report
 
 
+def _print_json(data: dict[str, object]) -> None:
+    print(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False))
+
+
+def _add_json_flag(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="print machine-readable JSON output")
+
+
 def _cmd_cluster(args: argparse.Namespace) -> int:
     payload = build_clusters(args.pack)
     write_json(args.output, payload)
+    if args.json:
+        response = dict(payload)
+        response["output"] = str(args.output)
+        _print_json(response)
+        return 0
     print(f"Wrote clusters to {args.output}")
     return 0
 
 
 def _cmd_summarize(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
+    if args.json:
+        _print_json(payload)
+        return 0
     print(summarize_clusters(payload))
     return 0
 
 
 def _cmd_markdown(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
     Path(args.output).write_text(markdown_report(payload), encoding="utf-8")
+    if args.json:
+        _print_json(
+            {
+                "output": str(args.output),
+                "cluster_count": int(payload.get("cluster_count", 0)),
+                "case_count": int(payload.get("case_count", 0)),
+                "format": "markdown",
+            }
+        )
+        return 0
     print(f"Wrote report to {args.output}")
     return 0
 
 
 def _cmd_compare(args: argparse.Namespace) -> int:
     payload = compare_cluster_files(args.baseline, args.candidate)
     write_json(args.output, payload)
+    if args.json:
+        response = dict(payload)
+        response["output"] = str(args.output)
+        _print_json(response)
+        return 0
     print(f"Wrote compare report to {args.output}")
     return 0
 
 
 def _cmd_compare_summary(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
+    if args.json:
+        _print_json(payload)
+        return 0
     print(summarize_compare(payload))
     return 0
 
 
 def _cmd_compare_markdown(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
     Path(args.output).write_text(markdown_compare_report(payload), encoding="utf-8")
+    if args.json:
+        _print_json(
+            {
+                "output": str(args.output),
+                "cluster_count": int(payload.get("cluster_count", 0)),
+                "summary": dict(payload.get("summary", {})),
+                "format": "markdown",
+            }
+        )
+        return 0
     print(f"Wrote compare markdown to {args.output}")
     return 0
 
 
 def _cmd_issue_drafts(args: argparse.Namespace) -> int:
     statuses = set(args.status) if args.status else None
     manifest = generate_issue_drafts(args.path, args.output_dir, include_statuses=statuses, rules_path=args.rules)
+    if args.json:
+        response = dict(manifest)
+        response["output_dir"] = str(args.output_dir)
+        _print_json(response)
+        return 0
     print(f"Wrote {manifest['draft_count']} issue drafts to {args.output_dir}")
     return 0
 
 
 def _cmd_issue_bundle(args: argparse.Namespace) -> int:
     bundle = build_issue_bundle(args.issues_path, args.output_dir)
+    if args.json:
+        response = dict(bundle)
+        response["output_dir"] = str(args.output_dir)
+        _print_json(response)
+        return 0
     print(f"Wrote issue bundle with {bundle['draft_count']} drafts to {args.output_dir}")
     return 0
 
 
 def _cmd_issue_bundle_summary(args: argparse.Namespace) -> int:
     bundle = load_issue_manifest(args.path)
+    if args.json:
+        _print_json(bundle)
+        return 0
     draft_count = int(bundle.get("draft_count", 0))
     print(f"Drafts: {draft_count}")
     print("By priority:")
@@ -89,19 +147,37 @@ def _cmd_issue_bundle_summary(args: argparse.Namespace) -> int:
 def _cmd_trend(args: argparse.Namespace) -> int:
     payload = build_trend_report(args.paths)
     write_json(args.output, payload)
+    if args.json:
+        response = dict(payload)
+        response["output"] = str(args.output)
+        _print_json(response)
+        return 0
     print(f"Wrote trend report to {args.output}")
     return 0
 
 
 def _cmd_trend_summary(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
+    if args.json:
+        _print_json(payload)
+        return 0
     print(summarize_trends(payload))
     return 0
 
 
 def _cmd_trend_markdown(args: argparse.Namespace) -> int:
     payload = load_clusters(args.path)
     Path(args.output).write_text(markdown_trend_report(payload), encoding="utf-8")
+    if args.json:
+        _print_json(
+            {
+                "output": str(args.output),
+                "snapshot_count": int(payload.get("snapshot_count", 0)),
+                "signature_count": int(payload.get("signature_count", 0)),
+                "format": "markdown",
+            }
+        )
+        return 0
     print(f"Wrote trend markdown to {args.output}")
     return 0
 
@@ -113,30 +189,36 @@ def build_parser() -> argparse.ArgumentParser:
     cluster = subparsers.add_parser("cluster", help="cluster failures from a TracePack pack")
     cluster.add_argument("pack")
     cluster.add_argument("output")
+    _add_json_flag(cluster)
     cluster.set_defaults(func=_cmd_cluster)
 
     summarize = subparsers.add_parser("summarize", help="summarize a clusters json file")
     summarize.add_argument("path")
+    _add_json_flag(summarize)
     summarize.set_defaults(func=_cmd_summarize)
 
     markdown = subparsers.add_parser("markdown", help="render a markdown report from clusters json")
     markdown.add_argument("path")
     markdown.add_argument("output")
+    _add_json_flag(markdown)
     markdown.set_defaults(func=_cmd_markdown)
 
     compare = subparsers.add_parser("compare", help="compare two cluster json files")
     compare.add_argument("baseline")
     compare.add_argument("candidate")
     compare.add_argument("output")
+    _add_json_flag(compare)
     compare.set_defaults(func=_cmd_compare)
 
     compare_summary = subparsers.add_parser("compare-summary", help="summarize a compare json file")
     compare_summary.add_argument("path")
+    _add_json_flag(compare_summary)
     compare_summary.set_defaults(func=_cmd_compare_summary)
 
     compare_markdown = subparsers.add_parser("compare-markdown", help="render markdown from a compare json file")
     compare_markdown.add_argument("path")
     compare_markdown.add_argument("output")
+    _add_json_flag(compare_markdown)
     compare_markdown.set_defaults(func=_cmd_compare_markdown)
 
     issue_drafts = subparsers.add_parser("issue-drafts", help="generate issue-ready markdown drafts from a compare json file")
@@ -149,29 +231,35 @@ def build_parser() -> argparse.ArgumentParser:
         choices=["new", "resolved", "growing", "shrinking", "unchanged"],
         help="limit generated drafts to selected statuses; can be passed multiple times",
     )
+    _add_json_flag(issue_drafts)
     issue_drafts.set_defaults(func=_cmd_issue_drafts)
 
     issue_bundle = subparsers.add_parser("issue-bundle", help="group issue drafts into a batch triage bundle")
     issue_bundle.add_argument("issues_path")
     issue_bundle.add_argument("output_dir")
+    _add_json_flag(issue_bundle)
     issue_bundle.set_defaults(func=_cmd_issue_bundle)
 
     issue_bundle_summary = subparsers.add_parser("issue-bundle-summary", help="summarize an issue bundle json file")
     issue_bundle_summary.add_argument("path")
+    _add_json_flag(issue_bundle_summary)
     issue_bundle_summary.set_defaults(func=_cmd_issue_bundle_summary)
 
     trend = subparsers.add_parser("trend", help="build a trend report from multiple cluster snapshots")
     trend.add_argument("output")
     trend.add_argument("paths", nargs="+")
+    _add_json_flag(trend)
     trend.set_defaults(func=_cmd_trend)
 
     trend_summary = subparsers.add_parser("trend-summary", help="summarize a trend json file")
     trend_summary.add_argument("path")
+    _add_json_flag(trend_summary)
     trend_summary.set_defaults(func=_cmd_trend_summary)
 
     trend_markdown = subparsers.add_parser("trend-markdown", help="render markdown from a trend json file")
     trend_markdown.add_argument("path")
     trend_markdown.add_argument("output")
+    _add_json_flag(trend_markdown)
     trend_markdown.set_defaults(func=_cmd_trend_markdown)
 
     return parser

projects/failmap/tests/test_failmap.py

@@ -3,8 +3,11 @@
 import json
 import tempfile
 import unittest
+from contextlib import redirect_stdout
+from io import StringIO
 from pathlib import Path
 
+from failmap.cli import main as cli_main
 from failmap.cluster import build_clusters
 from failmap.compare import compare_cluster_files
 from failmap.issues import build_issue_bundle, generate_issue_drafts
@@ -301,6 +304,107 @@ def test_trend_report_tracks_latest_statuses(self):
             self.assertIn("# FailMap Trend Report", markdown)
             self.assertIn("failure:model_call:planner", markdown)
 
+    def test_summarize_cli_can_emit_json(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            self._write_pack(root)
+            clusters_path = root / "clusters.json"
+            write_json(clusters_path, build_clusters(root))
+            output = StringIO()
+            with redirect_stdout(output):
+                code = cli_main(["summarize", str(clusters_path), "--json"])
+        payload = json.loads(output.getvalue())
+        self.assertEqual(code, 0)
+        self.assertEqual(payload["cluster_count"], 2)
+        self.assertEqual(payload["case_count"], 3)
+
+    def test_compare_summary_cli_can_emit_json(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            baseline_root = root / "baseline"
+            candidate_root = root / "candidate"
+            self._write_pack(baseline_root)
+            self._write_pack(candidate_root)
+            baseline_path = root / "baseline.json"
+            candidate_path = root / "candidate.json"
+            write_json(baseline_path, build_clusters(baseline_root))
+            candidate_payload = build_clusters(candidate_root)
+            candidate_payload["clusters"][0]["case_count"] = 3
+            write_json(candidate_path, candidate_payload)
+            compare_path = root / "compare.json"
+            write_json(compare_path, compare_cluster_files(baseline_path, candidate_path))
+            output = StringIO()
+            with redirect_stdout(output):
+                code = cli_main(["compare-summary", str(compare_path), "--json"])
+        payload = json.loads(output.getvalue())
+        self.assertEqual(code, 0)
+        self.assertEqual(payload["summary"]["growing"], 1)
+
+    def test_issue_bundle_summary_cli_can_emit_json(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            issues_dir = root / "issues"
+            issues_dir.mkdir(parents=True, exist_ok=True)
+            manifest = {
+                "format": "failmap-issues-v1",
+                "source_compare": "compare.json",
+                "draft_count": 1,
+                "drafts": [
+                    {
+                        "file": "001-new-tool.md",
+                        "title": "[FailMap] new: failure:tool_call:db_lookup",
+                        "status": "new",
+                        "signature": "failure:tool_call:db_lookup",
+                        "priority": "P1",
+                        "suggested_owner": "tooling",
+                        "labels": ["failmap", "status:new", "priority:P1"],
+                    }
+                ],
+            }
+            write_json(issues_dir / "manifest.json", manifest)
+            bundle_dir = root / "bundle"
+            build_issue_bundle(issues_dir, bundle_dir)
+            output = StringIO()
+            with redirect_stdout(output):
+                code = cli_main(["issue-bundle-summary", str(bundle_dir / "bundle.json"), "--json"])
+        payload = json.loads(output.getvalue())
+        self.assertEqual(code, 0)
+        self.assertEqual(payload["draft_count"], 1)
+        self.assertEqual(payload["owner_counts"]["tooling"], 1)
+
+    def test_trend_summary_cli_can_emit_json(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            release_a = root / "release-a.json"
+            release_b = root / "release-b.json"
+            write_json(
+                release_a,
+                {
+                    "format": "failmap-v1",
+                    "case_count": 1,
+                    "cluster_count": 1,
+                    "clusters": [{"signature": "failure:tool_call:web_search", "case_count": 1}],
+                },
+            )
+            write_json(
+                release_b,
+                {
+                    "format": "failmap-v1",
+                    "case_count": 2,
+                    "cluster_count": 1,
+                    "clusters": [{"signature": "failure:tool_call:web_search", "case_count": 2}],
+                },
+            )
+            trends_path = root / "trends.json"
+            write_json(trends_path, build_trend_report([release_a, release_b]))
+            output = StringIO()
+            with redirect_stdout(output):
+                code = cli_main(["trend-summary", str(trends_path), "--json"])
+        payload = json.loads(output.getvalue())
+        self.assertEqual(code, 0)
+        self.assertEqual(payload["snapshot_count"], 2)
+        self.assertEqual(payload["summary"]["growing_in_latest"], 1)
+
 
 if __name__ == "__main__":
     unittest.main()