feat(s54): --report/--json CLI mode in run.py over value_report

src/portfolio_optimiser/run.py

@@ -59,6 +59,11 @@ from portfolio_optimiser.verdicts import (
     capture_verdict,
     load_verdicts_from_dir,
 )
+from portfolio_optimiser.value_report import (
+    build_value_report,
+    dump_report_json,
+    format_report_text,
+)
 from portfolio_optimiser.workflow import _MAKER_CHECKER_ROLES, fresh_workflow
 
 
@@ -675,8 +680,72 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="offline drill: build contracts/clients/budget, STOP before the first model call",
     )
+    parser.add_argument(
+        "--report",
+        action="store_true",
+        help="S5.4 read-only value report: roll up the --ledger's realized savings (per-project + "
+        "portfolio totals, flagged cross-dimension overlaps, per-entry provenance) to stdout. "
+        "Mode-exclusive: only --ledger/--json are permitted alongside it; makes NO model calls",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="value report output form (requires --report): emit the roll-up as deterministic JSON "
+        "instead of the human table",
+    )
     args = parser.parse_args(argv)
 
+    # S5.4: read-only value-report dispatch — placed FIRST (right after parse_args, BEFORE the
+    # mode-exclusivity block below) so it returns before any model/portfolio path can start and no
+    # later branch can shadow it (the bare `--ledger`-outside-portfolio refusal at the elif below is
+    # left UNCHANGED — a bare --ledger with no --report still flows there and refuses as before).
+    if args.json and not args.report:
+        # A stray --json is never silently ignored (honors S5.3's "refused, never ignored" partition).
+        print("run refused: --json requires --report", file=sys.stderr)
+        return 1
+    if args.report:
+        # Mode-exclusivity as an ALLOWLIST (not a short blocklist): report mode permits ONLY --ledger
+        # and --json; ANY other distinguishable mode/config flag is refused — else --report --goals
+        # would silently drop --goals, whereas bare --goals is refused below (adding --report must not
+        # suppress an existing refusal). --decision/--rationale are excluded: their non-None argparse
+        # defaults are indistinguishable from an explicit value (exactly as the block below excludes
+        # them); they are inert in report mode.
+        report_forbidden = {
+            "--portfolio": args.portfolio,
+            "--live-dry-run": args.live_dry_run,
+            "PROJECT_ID": args.project_id is not None,
+            "--goals": args.goals is not None,
+            "--docs-dir": args.docs_dir is not None,
+            "--bundle-dir": args.bundle_dir is not None,
+            "--verdict-dir": args.verdict_dir is not None,
+            "--outbox-dir": args.outbox_dir is not None,
+            "--run-id": args.run_id is not None,
+            "--dimension-config": args.dimension_config is not None,
+        }
+        if any(report_forbidden.values()):
+            print(
+                "run report refused: mode-exclusive (only --ledger/--json permitted with --report)",
+                file=sys.stderr,
+            )
+            return 1
+        if not args.ledger:
+            # Guards SavingsLedger.load(None) -> Path(None) TypeError (NOT in the load except tuple).
+            print("run report refused: --report requires --ledger <file>", file=sys.stderr)
+            return 1
+        try:
+            # `report_ledger`, not `ledger`: the portfolio branch below binds `ledger` as
+            # `SavingsLedger | None`, so reusing that name here (type `SavingsLedger`) collides on
+            # mypy's function-scoped declared type.
+            report_ledger = SavingsLedger.load(args.ledger)
+        except (FileNotFoundError, ValidationError, ValueError) as exc:
+            # A load failure must never masquerade as a real zero-savings result (SC5): stderr + rc 1,
+            # no table. Only a successfully-loaded (possibly empty) ledger prints.
+            print(f"run report refused: {exc}", file=sys.stderr)
+            return 1
+        rep = build_value_report(report_ledger)  # NB: `rep`, not `report` (`report` is bound below)
+        print(dump_report_json(rep) if args.json else format_report_text(rep))
+        return 0
+
     # Step 4: mode-exclusivity validation (structured refusal, NOT argparse.error — keeps the rc 1
     # refusal contract). The two CLI modes are a documented partition: single-project-only flags are
     # refused in portfolio mode, and --goals/--ledger are refused outside it — never silently ignored.

tests/test_run_cli.py

@@ -9,6 +9,7 @@ content so the dry-run reaches its offline return.
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
 
 import pytest
@@ -266,3 +267,126 @@ def test_verdict_dir_ingested_at_main_level_offline(tmp_path, capsys) -> None:
     )
     assert rc == 0
     assert "LIVE-DRY-RUN OK" in capsys.readouterr().out
+
+
+# --- S5.4: --report / --json read-only value-report mode ------------------------------------------
+
+
+def _report_ledger(tmp_path: Path) -> Path:
+    """A saved ledger with >=2 projects and one cross-dimension overlap (``c-a`` under both
+    ``energi`` and ``asfalt`` in FV42 -> counted once, flagged), for the value-report arms.
+    portfolio_total = 1234567 (overlap once) + 500000 = 1734567 øre."""
+    led = SavingsLedger()
+    led.add_realized(
+        LedgerEntry(
+            project_id="FV42-GSV-E1",
+            dimension="energi",
+            candidate_identity="c-a",
+            amount_ore=1234567,
+            verdict_id="v1",
+            provenance="p1",
+        )
+    )
+    led.add_realized(
+        LedgerEntry(
+            project_id="FV42-GSV-E1",
+            dimension="asfalt",
+            candidate_identity="c-a",
+            amount_ore=1234567,
+            verdict_id="v2",
+            provenance="p2",  # cross-dimension overlap on (FV42-GSV-E1, c-a)
+        )
+    )
+    led.add_realized(
+        LedgerEntry(
+            project_id="RV13-RAS-TP",
+            dimension="energi",
+            candidate_identity="c-b",
+            amount_ore=500000,
+            verdict_id="v3",
+            provenance="p3",
+        )
+    )
+    p = tmp_path / "ledger.json"
+    led.save(str(p))
+    return p
+
+
+def test_report_prints_table_rc0(tmp_path, capsys) -> None:
+    """SC3: ``--report --ledger <f>`` -> rc 0; stdout carries a per-project row + the portfolio-total
+    NOK string. Dispatched FIRST, so no PROJECT_ID/--docs-dir is needed (no single-project refusal)."""
+    rc = run.main(["--report", "--ledger", str(_report_ledger(tmp_path))])
+    out = capsys.readouterr().out
+    assert rc == 0
+    assert "FV42-GSV-E1" in out  # a per-project row
+    assert "17\xa0345,67\xa0kr" in out  # portfolio total 1734567 øre
+
+
+def test_report_json_rc0_parses_rollup(tmp_path, capsys) -> None:
+    """SC4: ``--report ... --json`` -> rc 0 and ``json.loads(stdout)`` yields the roll-up
+    (int portfolio total, per_project dict, overlaps as JSON lists, provenance list)."""
+    rc = run.main(["--report", "--ledger", str(_report_ledger(tmp_path)), "--json"])
+    out = capsys.readouterr().out
+    assert rc == 0
+    payload = json.loads(out)
+    assert payload["portfolio_total_ore"] == 1734567
+    assert payload["per_project"]["FV42-GSV-E1"] == 1234567
+    assert isinstance(payload["overlaps"], list)
+    assert ["FV42-GSV-E1", "c-a"] in payload["overlaps"]  # tuple serialized as a JSON array
+    assert isinstance(payload["provenance"], list)
+    assert len(payload["provenance"]) == 3  # one ProvenanceLine per ledger entry
+
+
+def test_report_missing_ledger_file_rc1(capsys) -> None:
+    """SC5: ``--report --ledger /nonexistent`` -> rc 1, stderr non-empty, NO table on stdout (a load
+    failure must never masquerade as a real zero-savings result)."""
+    rc = run.main(["--report", "--ledger", "/nonexistent-ledger.json"])
+    cap = capsys.readouterr()
+    assert rc == 1
+    assert cap.err.strip()
+    assert cap.out == ""
+
+
+def test_report_malformed_ledger_rc1(tmp_path, capsys) -> None:
+    """SC5: a malformed-row ledger file -> rc 1 (``ValidationError`` surfaced as a refusal)."""
+    bad = tmp_path / "bad.json"
+    bad.write_text('[{"project_id": "P1"}]', encoding="utf-8")  # missing required fields
+    rc = run.main(["--report", "--ledger", str(bad)])
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()
+
+
+def test_report_without_ledger_rc1_no_traceback(capsys) -> None:
+    """Major-#1 guard: ``--report`` with no ``--ledger`` -> rc 1 with a 'requires --ledger' message
+    and no traceback (guards ``SavingsLedger.load(None)`` -> ``Path(None)`` TypeError)."""
+    rc = run.main(["--report"])
+    err = capsys.readouterr().err
+    assert rc == 1
+    assert "requires --ledger" in err
+    assert "Traceback" not in err
+
+
+def test_report_with_portfolio_refuses(tmp_path, capsys) -> None:
+    """Major-#3 partition: ``--report`` + ``--portfolio`` -> rc 1 (mode-exclusive)."""
+    rc = run.main(["--report", "--portfolio", "--ledger", str(_report_ledger(tmp_path))])
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()
+
+
+def test_report_with_goals_refuses(tmp_path, capsys) -> None:
+    """Major-#3 / P2-2 allowlist: ``--report`` + ``--goals`` (a config flag) -> rc 1. The allowlist
+    rejects config flags too, not just the two mode flags — else ``--goals`` would be silently
+    dropped, whereas bare ``--goals`` is refused (adding ``--report`` must not suppress a refusal)."""
+    goals = tmp_path / "goals.json"
+    goals.write_text('{"portfolio": {"absolute_ore": 1, "mode": "hard"}}', encoding="utf-8")
+    rc = run.main(["--report", "--goals", str(goals), "--ledger", str(_report_ledger(tmp_path))])
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()
+
+
+def test_json_without_report_refuses(tmp_path, capsys) -> None:
+    """Major-#3 partition: ``--json`` without ``--report`` -> rc 1 (a stray --json is never silently
+    ignored)."""
+    rc = run.main(["--json", "--ledger", str(_report_ledger(tmp_path))])
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()