prodc 0.3.72__tar.gz → 0.3.73__tar.gz

{prodc-0.3.72 → prodc-0.3.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.72
+Version: 0.3.73
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
 Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc

{prodc-0.3.72 → prodc-0.3.73}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.72"
+version = "0.3.73"
 description = "Product management as code: roles, flows, and features traced to evidence."
 readme = "README.md"
 requires-python = ">=3.12"

{prodc-0.3.72 → prodc-0.3.73}/src/prodc/agent.md

@@ -80,8 +80,9 @@ Read first, then act, then check.
 | act on a need going green (notify a tracker, etc.) | `prodc sync` — runs the `[callbacks]` commands for needs whose state changed since the last sync (`--dry-run` to preview) |
 | gate in CI | `prodc lint --strict` |
 
-Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <toml>…`
-(roll up many repos into one scoreboard), and `prodc diff <snapshot.json>` (what changed since a
+Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <path>…`
+(roll up many boards into one scoreboard + totals; a path is a prodc.toml or a dir to discover
+boards under), and `prodc diff <snapshot.json>` (what changed since a
 saved `status --json`). `prodc status` also takes `--goal <id>`, `--columns id,state,text,warrant`,
 `--wide`, `--include-drafts`, and `--stale <days>`.
 

{prodc-0.3.72 → prodc-0.3.73}/src/prodc/cli/app.py

@@ -324,8 +324,19 @@ def main(argv: list[str] | None = None) -> int:
     )
     ri.set_defaults(func=cmd_reinstate)
 
-    pf = sub.add_parser("portfolio", help="roll up many repos into one scoreboard")
-    pf.add_argument("configs", nargs="+", metavar="PRODC_TOML", help="one or more prodc.toml paths")
+    pf = sub.add_parser("portfolio", help="roll up many boards into one scoreboard")
+    pf.add_argument(
+        "configs",
+        nargs="+",
+        metavar="PATH",
+        help="prodc.toml paths and/or directories to discover boards under",
+    )
+    pf.add_argument(
+        "--max-depth",
+        type=int,
+        default=4,
+        help="how deep to descend when discovering boards under a directory (default 4)",
+    )
     pf.add_argument("--json", action="store_true", help="machine-readable output")
     pf.set_defaults(func=cmd_portfolio)
 

{prodc-0.3.72 → prodc-0.3.73}/src/prodc/cli/commands.py

@@ -56,7 +56,15 @@ from ..writer import (
     set_importance,
     withdraw,
 )
-from .common import RepoRow, emit_edit, exit_code, git_rev, load_or_report
+from .common import (
+    RepoRow,
+    discover_configs,
+    emit_edit,
+    exit_code,
+    git_rev,
+    load_or_report,
+    portfolio_totals,
+)
 from .render import (
     COLUMNS,
     provenance_counts,
@@ -582,12 +590,33 @@ def _repo_row(config_path: str) -> RepoRow:
 
 
 def cmd_portfolio(args: argparse.Namespace) -> int:
-    """Roll up many repos into one scoreboard — coverage, must-HOLEs, provenance per repo."""
-    rows = [_repo_row(path) for path in args.configs]
+    """Roll up many boards into one scoreboard — coverage, must-HOLEs, provenance per board.
+
+    Each argument is a ``prodc.toml`` path or a directory to discover boards under (every
+    ``prodc.toml`` beneath it, pruning VCS/vendor/build and hidden dirs, capped at ``--max-depth``).
+    Boards stay separate rows; a totals footer aggregates the clean ones. Never a merged board.
+    """
+    paths: list[str] = []
+    for arg in args.configs:
+        p = Path(arg)
+        if p.is_dir():
+            paths.extend(str(c) for c in discover_configs(p, max_depth=args.max_depth))
+        else:
+            paths.append(arg)
+    seen: set[str] = set()
+    unique: list[str] = []
+    for path in paths:
+        key = str(Path(path).resolve())
+        if key not in seen:
+            seen.add(key)
+            unique.append(path)
+    rows = [_repo_row(path) for path in unique]
+    totals = portfolio_totals(rows)
     if args.json:
-        print(json.dumps([asdict(r) for r in rows], indent=2))
+        payload = {"boards": [asdict(r) for r in rows], "totals": asdict(totals)}
+        print(json.dumps(payload, indent=2))
     else:
-        print(render_portfolio(rows))
+        print(render_portfolio(rows, totals))
     return 2 if any(r.error is not None for r in rows) else 0
 
 

{prodc-0.3.72 → prodc-0.3.73}/src/prodc/cli/common.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -100,3 +101,79 @@ class RepoRow:
     coverage: float
     provenance: dict[str, int]
     error: str | None = None
+
+
+@dataclass(frozen=True)
+class PortfolioTotals:
+    """The aggregate across every board in a portfolio — a footer, not a merged board.
+
+    Error rows are excluded (a board that would not load contributes no counts). ``coverage`` is
+    the pooled ``delivered / total``, which is not the mean of the per-board percentages.
+    """
+
+    boards: int  # how many boards loaded cleanly and are summed here
+    delivered: int
+    total: int
+    must_hole: int
+    broken: int
+    coverage: float
+
+
+def portfolio_totals(rows: list[RepoRow]) -> PortfolioTotals:
+    """Sum the clean rows into a :class:`PortfolioTotals` footer."""
+    ok = [r for r in rows if r.error is None]
+    delivered = sum(r.delivered for r in ok)
+    total = sum(r.total for r in ok)
+    return PortfolioTotals(
+        boards=len(ok),
+        delivered=delivered,
+        total=total,
+        must_hole=sum(r.must_hole for r in ok),
+        broken=sum(r.broken for r in ok),
+        coverage=round(delivered / total, 4) if total else 0.0,
+    )
+
+
+# Directory names never descended into during board discovery: VCS, virtualenvs, dependency and
+# build trees. Any name starting with "." is pruned too (handled in the walk), so a vendored or
+# example prodc.toml buried in one of these is never mistaken for a board.
+_PRUNE_DIRS = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "dist",
+        "build",
+        "target",
+        ".tox",
+        ".mypy_cache",
+        ".ruff_cache",
+        "site-packages",
+        "vendor",
+    }
+)
+
+
+def discover_configs(root: Path, *, max_depth: int = 4) -> list[Path]:
+    """Every ``prodc.toml`` under ``root``, for the portfolio roll-up — bounded so it can't run away.
+
+    A plain recursive scan is a footgun: it descends into ``.git``/``node_modules``/build trees and
+    picks up vendored or example configs. So this prunes those (and every ``.``-prefixed dir) and
+    caps the descent at ``max_depth`` directories below ``root``. Returns sorted, de-duplicated
+    paths; a board is the directory that holds the ``prodc.toml``.
+    """
+    root = root.resolve()
+    found: set[Path] = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        if "prodc.toml" in filenames:
+            found.add(Path(dirpath) / "prodc.toml")
+        depth = len(Path(dirpath).relative_to(root).parts)
+        # Prune in place so os.walk never descends into the skipped dirs, then stop at the depth cap.
+        dirnames[:] = (
+            []
+            if depth >= max_depth
+            else [d for d in dirnames if d not in _PRUNE_DIRS and not d.startswith(".")]
+        )
+    return sorted(found)

{prodc-0.3.72 → prodc-0.3.73}/src/prodc/cli/render.py

@@ -22,7 +22,7 @@ from ..model import (
     ears_shape,
 )
 from ..status import Handoff, Recurrence, Summary, rank, state_priority
-from .common import RepoRow, brief_open
+from .common import PortfolioTotals, RepoRow, brief_open
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -380,7 +380,9 @@ def render_argument(model: Model, defects: list[str]) -> str:
     return "\n".join(out)
 
 
-def render_portfolio(rows: list[RepoRow]) -> str:
+def render_portfolio(rows: list[RepoRow], totals: PortfolioTotals | None = None) -> str:
+    if not rows:
+        return "  no boards found"
     out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov prim/sec/asm/op"]
     for row in rows:
         if row.error is not None:
@@ -390,4 +392,12 @@ def render_portfolio(rows: list[RepoRow]) -> str:
         prov = f"{p['primary']}/{p['secondary']}/{p['assumption']}/{p['opinion']}"
         cov = f"{round(row.coverage * 100)}%"
         out.append(f"  {row.repo:<18} {cov:>4}  {row.must_hole:>9}  {row.broken:>6}   {prov}")
+    if totals is not None:
+        cov = f"{round(totals.coverage * 100)}%"
+        label = f"TOTAL ({totals.boards} boards)"
+        out.append(f"  {'─' * 48}")
+        out.append(
+            f"  {label:<18} {cov:>4}  {totals.must_hole:>9}  {totals.broken:>6}   "
+            f"{totals.delivered}/{totals.total} delivered"
+        )
     return "\n".join(out)

{prodc-0.3.72 → prodc-0.3.73}/tests/test_cli.py

@@ -162,15 +162,18 @@ def test_portfolio_rolls_up_many_repos(tmp_path: Path, capsys: pytest.CaptureFix
     assert code == 0
     assert "alpha" in out and "beta" in out
     assert "33%" in out  # each repo is 1/3 delivered
+    assert "TOTAL (2 boards)" in out and "2/6 delivered" in out  # the aggregate footer
 
 
 def test_portfolio_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
     import json
 
     main(["portfolio", str(_project(tmp_path / "alpha")), "--json"])
-    rows = json.loads(capsys.readouterr().out)
-    assert rows[0]["repo"] == "alpha" and rows[0]["total"] == 3
-    assert rows[0]["provenance"]["primary"] == 1
+    payload = json.loads(capsys.readouterr().out)
+    boards = payload["boards"]
+    assert boards[0]["repo"] == "alpha" and boards[0]["total"] == 3
+    assert boards[0]["provenance"]["primary"] == 1
+    assert payload["totals"]["boards"] == 1 and payload["totals"]["total"] == 3
 
 
 def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
@@ -179,6 +182,47 @@ def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixt
     assert code == 2
 
 
+def test_portfolio_discovers_boards_under_a_directory(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    # a projects/ folder with two boards, one nested a level deeper
+    root = tmp_path / "projects"
+    _project(root / "crm")
+    _project(root / "lingua" / "app")
+    code = main(["portfolio", str(root)])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "crm" in out and "app" in out  # both discovered, each its own row
+    assert "TOTAL (2 boards)" in out
+
+
+def test_portfolio_discovery_prunes_vcs_and_vendor_dirs(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json
+
+    root = tmp_path / "projects"
+    _project(root / "real")
+    # boards buried in dirs that must never be descended into
+    _project(root / ".git" / "hooks-board")
+    _project(root / "node_modules" / "dep")
+    _project(root / "real" / ".venv" / "pkg")
+    main(["portfolio", str(root), "--json"])
+    names = {b["repo"] for b in json.loads(capsys.readouterr().out)["boards"]}
+    assert names == {"real"}  # the pruned boards are invisible to discovery
+
+
+def test_portfolio_discovery_respects_max_depth(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    import json
+
+    root = tmp_path / "projects"
+    _project(root / "a" / "b" / "c" / "deep")  # 4 dirs below root
+    main(["portfolio", str(root), "--max-depth", "2", "--json"])
+    assert json.loads(capsys.readouterr().out)["boards"] == []  # too deep to find
+
+
 def test_diff_no_changes(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
     toml = str(_project(tmp_path))
     main(["status", "--config", toml, "--json"])