prodc 0.2.0__tar.gz → 0.3.1__tar.gz

{prodc-0.2.0 → prodc-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.2.0
+Version: 0.3.1
 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.2.0 → prodc-0.3.1}/pyproject.toml

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

{prodc-0.2.0 → prodc-0.3.1}/src/prodc/adapters.py

@@ -12,7 +12,7 @@ import re
 import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Protocol, cast
+from typing import Protocol, cast, runtime_checkable
 
 from .model import ProofState
 
@@ -43,6 +43,18 @@ class Adapter(Protocol):
     def resolve(self, payload: str) -> ProofResult: ...
 
 
+@runtime_checkable
+class Enumerable(Protocol):
+    """An adapter that can list every proof unit it knows and which a payload claims.
+
+    Needed for the orphan report (proofs referenced by no need). Adapters that can't
+    enumerate their universe (e.g. pytest, which resolves by existence) don't implement it.
+    """
+
+    def inventory(self) -> list[str]: ...  # canonical ids of every proof unit
+    def covers(self, payload: str) -> list[str]: ...  # canonical ids a payload claims
+
+
 @dataclass(frozen=True)
 class _Scenario:
     file: str
@@ -119,16 +131,29 @@ class GherkinAdapter:
         self._results = out
         return out
 
-    def resolve(self, payload: str) -> ProofResult:
+    @staticmethod
+    def _id(s: _Scenario) -> str:
+        return f"{s.file}#{s.title}"
+
+    def _match(self, payload: str) -> list[_Scenario]:
+        """The scenarios a locator payload refers to (``tag:@X`` or ``file#title``)."""
         scenarios = self._load()
         if payload.startswith("tag:"):
             want = payload[4:]
-            matches = [s for s in scenarios if want in s.tags]
-        else:
-            file_part, _, title = payload.partition("#")
-            matches = [
-                s for s in scenarios if s.title == title and (not file_part or s.file == file_part)
-            ]
+            return [s for s in scenarios if want in s.tags]
+        file_part, _, title = payload.partition("#")
+        return [s for s in scenarios if s.title == title and (not file_part or s.file == file_part)]
+
+    def inventory(self) -> list[str]:
+        """Every scenario, as ``file#title`` — the universe the orphan report diffs against."""
+        return sorted({self._id(s) for s in self._load()})
+
+    def covers(self, payload: str) -> list[str]:
+        """The scenarios (as ``file#title``) a referenced payload claims."""
+        return sorted({self._id(s) for s in self._match(payload)})
+
+    def resolve(self, payload: str) -> ProofResult:
+        matches = self._match(payload)
         if not matches:
             return ProofResult(ProofState.BROKEN, False, f"no scenario matches '{payload}'")
 

{prodc-0.2.0 → prodc-0.3.1}/src/prodc/cli.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import shutil
 import sys
 from pathlib import Path
 
@@ -16,7 +17,7 @@ from . import __version__
 from .config import Config, ConfigError
 from .loader import LoaderError, load_needs
 from .model import Need, NeedResult, NeedState, SourceKind
-from .status import Summary, resolve, summarize
+from .status import Summary, orphans, resolve, summarize
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -53,6 +54,18 @@ def _warrant(need: Need) -> str:
     return strongest.value
 
 
+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
+    return "provenance: " + "  ·  ".join(f"{counts[k]} {k}" for k in counts)
+
+
 def _summary_line(s: Summary) -> str:
     """The leading gap-count line: what needs attention, and overall coverage."""
     parts: list[str] = []
@@ -75,10 +88,18 @@ def _render(results: list[NeedResult]) -> str:
     for r in results:
         groups.setdefault(r.need.who or "(unassigned)", []).append(r)
 
+    # Size the need column to the terminal; ~54 cols go to the fixed id/state/nm
+    # prefix and the warrant suffix. Falls back to 100 cols when there is no tty.
+    width = max(30, shutil.get_terminal_size(fallback=(100, 24)).columns - 54)
+
     out: list[str] = []
     # The Toulmin split: GROUNDS (does a test prove it?) vs WARRANT (user signal it
     # matters?). A need can be green on one and empty on the other — that gap is the point.
-    out.append(f"  {'':2} {'id':<9} {'GROUNDS':<10}{'':5} {'need':<48}  WARRANT")
+    out.append(f"  {'':2} {'id':<9} {'GROUNDS':<10}{'':5} {'need':<{width}}  WARRANT")
+    out.append(
+        "  legend: * declared (no results artifact)  ·  !! must  ·  "
+        "GROUNDS = test proof  ·  WARRANT = evidence source"
+    )
     for who in sorted(groups):
         rs = sorted(groups[who], key=_priority)
         label = next((x.need.label for x in rs if x.need.label), None)
@@ -86,20 +107,31 @@ def _render(results: list[NeedResult]) -> str:
         head = "  ·  ".join(f"{counts[s]} {_LABEL[s]}" for s in NeedState if counts[s])
         title = f"{who}" + (f" ({label})" if label else "")
         out.append(f"\n{title}    {head}")
+        out.append(f"    {_provenance_line(rs)}")
         for r in rs:
             bang = "!!" if r.need.must else "  "
             star = "*" if r.declared and r.state is NeedState.DELIVERED else " "
             nm = f"{r.delivered}/{r.total}" if r.total else ""
             out.append(
                 f"  {bang} {r.need.id:<9} {_LABEL[r.state]:<9}{star} {nm:<5} "
-                f"{r.need.text[:48]:<48}  {_warrant(r.need)}"
+                f"{r.need.text[:width]:<{width}}  {_warrant(r.need)}"
             )
             for w in r.warnings:
                 out.append(f"       ⚠ {w}")
     return "\n".join(out)
 
 
-def _to_json(results: list[NeedResult], summary: Summary) -> str:
+def _render_orphans(orphan_map: dict[str, list[str]]) -> str:
+    """The reverse report: proof units that no need references."""
+    total = sum(len(v) for v in orphan_map.values())
+    out = [f"\norphan proofs (claimed by no need): {total}"]
+    for name in sorted(orphan_map):
+        for sid in orphan_map[name]:
+            out.append(f"     {name}:{sid}")
+    return "\n".join(out)
+
+
+def _to_json(results: list[NeedResult], summary: Summary, orphan_map: dict[str, list[str]]) -> str:
     payload = {
         "summary": {
             "total": summary.total,
@@ -110,7 +142,9 @@ def _to_json(results: list[NeedResult], summary: Summary) -> str:
             "broken": summary.broken,
             "opinion": summary.opinion,
             "coverage": round(summary.coverage, 4),
+            "orphans": sum(len(v) for v in orphan_map.values()),
         },
+        "orphans": orphan_map,
         "needs": [
             {
                 "id": r.need.id,
@@ -147,23 +181,27 @@ def _cmd_status(args: argparse.Namespace) -> int:
         return 2
     results = resolve(needs, cfg.adapters)
     summary = summarize(results)
+    orphan_map = orphans(needs, cfg.adapters)
 
     if args.json:
-        print(_to_json(results, summary))
+        print(_to_json(results, summary, orphan_map))
     else:
         commit = _git_rev(cfg.root)
         print(f"prodc status — {cfg.root.name}{f' @ {commit}' if commit else ''}")
         print(_summary_line(summary))
         print(_render(results))
+        if orphan_map:
+            print(_render_orphans(orphan_map))
 
-    return _exit_code(args, summary)
+    return _exit_code(args, summary, sum(len(v) for v in orphan_map.values()))
 
 
-def _exit_code(args: argparse.Namespace, summary: Summary) -> int:
+def _exit_code(args: argparse.Namespace, summary: Summary, orphan_total: int) -> int:
     """Gate: 0 unless a threshold is crossed; HOLE never fails.
 
     Default fails on any BROKEN; ``--max-dangling N`` tolerates N; ``--min-coverage F``
-    fails when delivered/total < F; ``--strict`` fails on any opinion.
+    fails when delivered/total < F; ``--max-orphans N`` fails above N unclaimed proofs;
+    ``--strict`` fails on any opinion.
     """
     if args.max_dangling is not None:
         if summary.broken > args.max_dangling:
@@ -172,6 +210,8 @@ def _exit_code(args: argparse.Namespace, summary: Summary) -> int:
         return 1
     if args.min_coverage is not None and summary.coverage < args.min_coverage:
         return 1
+    if args.max_orphans is not None and orphan_total > args.max_orphans:
+        return 1
     if args.strict and summary.opinion:
         return 1
     return 0
@@ -214,6 +254,13 @@ def main(argv: list[str] | None = None) -> int:
         metavar="N",
         help="gate: tolerate up to N broken locators instead of failing on any",
     )
+    st.add_argument(
+        "--max-orphans",
+        type=int,
+        default=None,
+        metavar="N",
+        help="gate: exit 1 if more than N proof scenarios are claimed by no need",
+    )
     st.set_defaults(func=_cmd_status)
 
     args = parser.parse_args(argv)

{prodc-0.2.0 → prodc-0.3.1}/src/prodc/status.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from .adapters import Adapter, ProofResult
+from .adapters import Adapter, Enumerable, ProofResult
 from .model import (
     SOLUTION_VERBS,
     Need,
@@ -140,3 +140,31 @@ def summarize(results: list[NeedResult]) -> Summary:
         broken=by_state[NeedState.BROKEN],
         opinion=sum(1 for r in results if r.need.is_opinion),
     )
+
+
+def orphans(needs: list[Need], adapters: dict[str, Adapter]) -> dict[str, list[str]]:
+    """Proof units claimed by no need, per enumerable adapter — the reverse of the board.
+
+    The board walks need → proof; this walks proof → need, surfacing scenarios that
+    exist in the suite but no need references ("does every feature tie to a need?").
+    Only adapters that can enumerate their universe (:class:`~prodc.adapters.Enumerable`,
+    e.g. gherkin) participate.
+    """
+    referenced: dict[str, set[str]] = {}
+    for need in needs:
+        for locator in need.proofs:
+            name, sep, payload = locator.partition(":")
+            if sep:
+                referenced.setdefault(name, set()).add(payload)
+
+    out: dict[str, list[str]] = {}
+    for name, adapter in adapters.items():
+        if not isinstance(adapter, Enumerable):
+            continue
+        claimed: set[str] = set()
+        for payload in referenced.get(name, set()):
+            claimed.update(adapter.covers(payload))
+        unclaimed = sorted(set(adapter.inventory()) - claimed)
+        if unclaimed:
+            out[name] = unclaimed
+    return out

{prodc-0.2.0 → prodc-0.3.1}/tests/test_cli.py

@@ -46,6 +46,10 @@ Feature: orders
   Scenario: Done
     Given a thing
     Then it works
+
+  Scenario: Unclaimed extra
+    Given another thing
+    Then no need references me
 """
 
 
@@ -66,6 +70,9 @@ def test_board_shows_summary_and_warrant(tmp_path: Path, capsys: pytest.CaptureF
     assert "WARRANT" in out  # the warrant column header (#3)
     assert "interview:John" in out  # strongest warrant for D-1
     assert "opinion" in out  # O-1's warrant
+    assert "legend:" in out  # glyph legend (#10)
+    # provenance mix (#11): 1 interview, 1 artifact, 0 internal, 1 opinion
+    assert "provenance:" in out and "1 interview" in out and "1 artifact" in out
 
 
 def test_json_has_summary_and_grounds_warrant(
@@ -91,3 +98,31 @@ def test_strict_fails_on_opinion(tmp_path: Path, capsys: pytest.CaptureFixture[s
     code = main(["status", "--config", str(_project(tmp_path)), "--strict"])
     capsys.readouterr()
     assert code == 1  # O-1 has no source
+
+
+def test_orphan_report_lists_unclaimed_scenarios(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    code = main(["status", "--config", str(_project(tmp_path))])
+    out = capsys.readouterr().out
+    assert code == 0  # orphans alone don't fail without a gate
+    assert "orphan proofs (claimed by no need): 1" in out
+    assert "web:orders.feature#Unclaimed extra" in out
+    assert "web:orders.feature#Done" not in out.split("orphan proofs")[1]  # Done is claimed
+
+
+def test_max_orphans_gate(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    p = str(_project(tmp_path))
+    assert main(["status", "--config", p, "--max-orphans", "0"]) == 1  # 1 orphan > 0
+    capsys.readouterr()
+    assert main(["status", "--config", p, "--max-orphans", "1"]) == 0  # 1 orphan <= 1
+    capsys.readouterr()
+
+
+def test_orphans_in_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    import json
+
+    main(["status", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["summary"]["orphans"] == 1
+    assert payload["orphans"]["web"] == ["orders.feature#Unclaimed extra"]