prodc 0.3.2__tar.gz → 0.3.4__tar.gz

{prodc-0.3.2 → prodc-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.2
+Version: 0.3.4
 Summary: Product management as code: personas, 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.2 → prodc-0.3.4}/pyproject.toml

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

{prodc-0.3.2 → prodc-0.3.4}/src/prodc/cli.py

@@ -11,6 +11,7 @@ import argparse
 import json
 import shutil
 import sys
+from dataclasses import asdict, dataclass
 from pathlib import Path
 
 from . import __version__
@@ -54,15 +55,21 @@ def _warrant(need: Need) -> str:
     return strongest.value
 
 
+def _provenance_counts(results: list[NeedResult]) -> dict[str, int]:
+    """How many needs carry each warrant strength (interview/artifact/internal/opinion)."""
+    counts = {"interview": 0, "artifact": 0, "internal": 0, "opinion": 0}
+    for r in results:
+        counts[_warrant(r.need).split(":", 1)[0]] += 1
+    return counts
+
+
 def _provenance_line(results: list[NeedResult]) -> str:
     """Per-persona provenance mix — makes internal-only ('0 OPINION' but unvalidated) visible.
 
     OPINION (no source) stays distinct from a weak INTERNAL source; the headline a PM
     wants is how many needs trace to a real user (interview), not just 'has any source'.
     """
-    counts = {"interview": 0, "artifact": 0, "internal": 0, "opinion": 0}
-    for r in results:
-        counts[_warrant(r.need).split(":", 1)[0]] += 1
+    counts = _provenance_counts(results)
     return "provenance: " + "  ·  ".join(f"{counts[k]} {k}" for k in counts)
 
 
@@ -168,17 +175,25 @@ def _to_json(results: list[NeedResult], summary: Summary, orphan_map: dict[str,
     return json.dumps(payload, indent=2)
 
 
-def _cmd_status(args: argparse.Namespace) -> int:
+def _load_or_report(args: argparse.Namespace) -> tuple[Config, list[Need]] | None:
+    """Load config + needs, or print the error to stderr and return None."""
     cfg_path = Path(args.config)
     if not cfg_path.exists():
         print(f"prodc: no config at {cfg_path}", file=sys.stderr)
-        return 2
+        return None
     try:
         cfg = Config.load(cfg_path)
-        needs = load_needs(cfg)
+        return cfg, load_needs(cfg)
     except (ConfigError, LoaderError) as exc:
         print(f"prodc: {exc}", file=sys.stderr)
+        return None
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    loaded = _load_or_report(args)
+    if loaded is None:
         return 2
+    cfg, needs = loaded
     results = resolve(needs, cfg.adapters)
     summary = summarize(results)
     orphan_map = orphans(needs, cfg.adapters)
@@ -217,6 +232,142 @@ def _exit_code(args: argparse.Namespace, summary: Summary, orphan_total: int) ->
     return 0
 
 
+def _render_show(r: NeedResult) -> str:
+    """One need as a citable answer — the artifact you drop into a thread."""
+    need = r.need
+    who = (need.who + (f" ({need.label})" if need.label else "")) if need.who else "(unassigned)"
+    nm = f"  {r.delivered}/{r.total}" if r.total else ""
+    lines = [
+        f"{need.id}{'  !!' if need.must else ''}  {need.text}",
+        f"  who: {who}",
+        f"  grounds: {_LABEL[r.state]}{nm}    warrant: {_warrant(need)}",
+    ]
+    if need.sources:
+        lines.append("  sources:")
+        for s in need.sources:
+            bits = [s.kind.value]
+            bits += [f"{k}={v}" for k, v in (("who", s.who), ("date", s.date),
+                                             ("locator", s.locator)) if v]
+            line = "    - " + "  ".join(bits)
+            lines.append(line + (f'  "{s.quote}"' if s.quote else ""))
+    else:
+        lines.append("  sources: (none — opinion)")
+    if need.children:
+        lines.append(f"  children: {', '.join(need.children)}")
+    if need.proofs:
+        lines.append("  proofs:")
+        lines += [f"    - {d}" for d in r.detail]
+    elif not need.children:
+        lines.append("  proofs: (none — HOLE)")
+    lines += [f"  ⚠ {w}" for w in r.warnings]
+    return "\n".join(lines)
+
+
+def _show_json(r: NeedResult) -> str:
+    need = r.need
+    return json.dumps(
+        {
+            "id": need.id,
+            "text": need.text,
+            "who": need.who,
+            "label": need.label,
+            "must": need.must,
+            "state": r.state.value,
+            "grounds": r.state.value,
+            "warrant": _warrant(need),
+            "delivered": r.delivered,
+            "total": r.total,
+            "declared": r.declared,
+            "opinion": need.is_opinion,
+            "only_internal": need.only_internal,
+            "sources": [
+                {"kind": s.kind.value, "who": s.who, "date": s.date,
+                 "quote": s.quote, "locator": s.locator}
+                for s in need.sources
+            ],
+            "proofs": list(need.proofs),
+            "children": list(need.children),
+            "detail": r.detail,
+            "warnings": r.warnings,
+        },
+        indent=2,
+    )
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    loaded = _load_or_report(args)
+    if loaded is None:
+        return 2
+    cfg, needs = loaded
+    by_id = {r.need.id: r for r in resolve(needs, cfg.adapters)}
+    r = by_id.get(args.need_id)
+    if r is None:
+        print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
+        return 2
+    print(_show_json(r) if args.json else _render_show(r))
+    return 0
+
+
+@dataclass(frozen=True)
+class _RepoRow:
+    """One repo's line in the portfolio roll-up."""
+
+    repo: str
+    delivered: int
+    total: int
+    must_hole: int
+    broken: int
+    coverage: float
+    provenance: dict[str, int]
+    error: str | None = None
+
+
+def _repo_row(config_path: str) -> _RepoRow:
+    p = Path(config_path)
+    name = p.parent.name or str(p)
+    try:
+        cfg = Config.load(p)
+        needs = load_needs(cfg)
+    except (ConfigError, LoaderError, OSError) as exc:
+        return _RepoRow(name, 0, 0, 0, 0, 0.0, {}, error=str(exc))
+    results = resolve(needs, cfg.adapters)
+    s = summarize(results)
+    return _RepoRow(
+        repo=cfg.root.name,
+        delivered=s.delivered,
+        total=s.total,
+        must_hole=s.must_hole,
+        broken=s.broken,
+        coverage=round(s.coverage, 4),
+        provenance=_provenance_counts(results),
+    )
+
+
+def _render_portfolio(rows: list[_RepoRow]) -> str:
+    out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov intv/art/int/op"]
+    for row in rows:
+        if row.error is not None:
+            out.append(f"  {row.repo:<18} error: {row.error}")
+            continue
+        p = row.provenance
+        prov = f"{p['interview']}/{p['artifact']}/{p['internal']}/{p['opinion']}"
+        cov = f"{round(row.coverage * 100)}%"
+        out.append(
+            f"  {row.repo:<18} {cov:>4}  {row.must_hole:>9}  {row.broken:>6}   {prov}"
+        )
+    return "\n".join(out)
+
+
+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]
+    if args.json:
+        print(json.dumps([asdict(r) for r in rows], indent=2))
+    else:
+        print(_render_portfolio(rows))
+    return 2 if any(r.error is not None for r in rows) else 0
+
+
 def _git_rev(root: Path) -> str | None:
     head = root / ".git" / "HEAD"
     try:
@@ -263,6 +414,17 @@ def main(argv: list[str] | None = None) -> int:
     )
     st.set_defaults(func=_cmd_status)
 
+    sh = sub.add_parser("show", help="show one need as a citable answer")
+    sh.add_argument("need_id", help="the need id to show, e.g. N-1")
+    sh.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    sh.add_argument("--json", action="store_true", help="machine-readable output")
+    sh.set_defaults(func=_cmd_show)
+
+    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.add_argument("--json", action="store_true", help="machine-readable output")
+    pf.set_defaults(func=_cmd_portfolio)
+
     args = parser.parse_args(argv)
     return int(args.func(args))
 

{prodc-0.3.2 → prodc-0.3.4}/tests/test_cli.py

@@ -54,8 +54,8 @@ Feature: orders
 
 
 def _project(tmp_path: Path) -> Path:
-    (tmp_path / "needs").mkdir()
-    (tmp_path / "features").mkdir()
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "features").mkdir(parents=True, exist_ok=True)
     (tmp_path / "prodc.toml").write_text(_TOML, encoding="utf-8")
     (tmp_path / "needs" / "a.yaml").write_text(_NEEDS, encoding="utf-8")
     (tmp_path / "features" / "orders.feature").write_text(_FEATURE, encoding="utf-8")
@@ -126,3 +126,54 @@ def test_orphans_in_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) ->
     payload = json.loads(capsys.readouterr().out)
     assert payload["summary"]["orphans"] == 1
     assert payload["orphans"]["web"] == ["orders.feature#Unclaimed extra"]
+
+
+def test_show_single_need(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    code = main(["show", "D-1", "--config", str(_project(tmp_path))])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "D-1" in out and "a delivered need" in out
+    assert "grounds: DELIVERED" in out and "interview:John" in out
+    assert "I need this" in out  # the source quote
+
+
+def test_show_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    import json
+
+    main(["show", "D-1", "--config", str(_project(tmp_path)), "--json"])
+    p = json.loads(capsys.readouterr().out)
+    assert p["id"] == "D-1" and p["warrant"] == "interview:John"
+    assert p["sources"][0]["kind"] == "interview" and p["sources"][0]["who"] == "John"
+
+
+def test_show_unknown_need_exits_2(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    code = main(["show", "NOPE", "--config", str(_project(tmp_path))])
+    capsys.readouterr()
+    assert code == 2
+
+
+def test_portfolio_rolls_up_many_repos(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    a = _project(tmp_path / "alpha")
+    b = _project(tmp_path / "beta")
+    code = main(["portfolio", str(a), str(b)])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "alpha" in out and "beta" in out
+    assert "33%" in out  # each repo is 1/3 delivered
+
+
+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"]["interview"] == 1
+
+
+def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    code = main(["portfolio", str(tmp_path / "nope.toml")])
+    capsys.readouterr()
+    assert code == 2