prodc 0.2.0__tar.gz → 0.3.0__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.2.0"
+version = "0.3.0"
 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.0}/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.0}/src/prodc/cli.py

@@ -16,7 +16,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",
@@ -99,7 +99,17 @@ def _render(results: list[NeedResult]) -> str:
     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 +120,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 +159,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 +188,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 +232,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.0}/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.0}/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
 """
 
 
@@ -91,3 +95,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"]