prodc 0.3.6__tar.gz → 0.3.7__tar.gz

{prodc-0.3.6 → prodc-0.3.7}/PKG-INFO

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

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

{prodc-0.3.6 → prodc-0.3.7}/src/prodc/adapters.py

@@ -32,6 +32,21 @@ def _steps_passed(steps: list[object]) -> bool:
     return True
 
 
+def _git_head(repo: Path) -> str | None:
+    """Short git rev of a checked-out repo, read from .git/HEAD (no git binary needed)."""
+    head = repo / ".git" / "HEAD"
+    try:
+        ref = head.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if ref.startswith("ref:"):
+        try:
+            return (repo / ".git" / ref[4:].strip()).read_text(encoding="utf-8").strip()[:7]
+        except OSError:
+            return None
+    return ref[:7]
+
+
 @dataclass(frozen=True)
 class ProofResult:
     state: ProofState
@@ -259,6 +274,30 @@ class AcceptAdapter:
         return ProofResult(ProofState.DELIVERED, True, detail)
 
 
+class External:
+    """Wraps a proof adapter that resolves against a sibling repo checked out at ``repo``.
+
+    If the sibling is absent the fact could not be read at all → UNRESOLVED, distinct
+    from a BROKEN locator (read, resolves to nothing) and not a coverage miss. On a read,
+    the sibling's git HEAD is appended to the detail so the result is traceable to the
+    exact upstream revision (reproducible across machines, not just per-checkout).
+    """
+
+    def __init__(self, inner: Adapter, repo: Path) -> None:
+        self._inner = inner
+        self._repo = repo
+
+    def resolve(self, payload: str) -> ProofResult:
+        if not self._repo.exists():
+            return ProofResult(
+                ProofState.UNRESOLVED, False, f"sibling '{self._repo.name}' not checked out"
+            )
+        res = self._inner.resolve(payload)
+        rev = _git_head(self._repo)
+        suffix = f" @ {self._repo.name}:{rev}" if rev else f" @ {self._repo.name}"
+        return ProofResult(res.state, res.declared, res.detail + suffix)
+
+
 @dataclass(frozen=True)
 class SourceResult:
     """Whether a Source.locator resolves. Verifies provenance *exists*, not that it is good."""

{prodc-0.3.6 → prodc-0.3.7}/src/prodc/cli.py

@@ -25,6 +25,7 @@ _LABEL = {
     NeedState.PENDING: "PENDING",
     NeedState.HOLE: "HOLE",
     NeedState.BROKEN: "BROKEN",
+    NeedState.UNRESOLVED: "UNRESOLVED",
 }
 
 
@@ -34,8 +35,9 @@ def _priority(r: NeedResult) -> int:
     return {
         NeedState.BROKEN: 1,
         NeedState.PENDING: 2,
-        NeedState.HOLE: 3,
-        NeedState.DELIVERED: 4,
+        NeedState.UNRESOLVED: 3,
+        NeedState.HOLE: 4,
+        NeedState.DELIVERED: 5,
     }[r.state]
 
 
@@ -87,6 +89,8 @@ def _summary_line(s: Summary) -> str:
         parts.append(f"{s.must_hole} must-HOLE")
     if s.broken:
         parts.append(f"{s.broken} BROKEN")
+    if s.unresolved:
+        parts.append(f"{s.unresolved} UNRESOLVED")
     if s.pending:
         parts.append(f"{s.pending} PENDING")
     if s.hole - s.must_hole:
@@ -154,6 +158,7 @@ def _to_json(results: list[NeedResult], summary: Summary, orphan_map: dict[str,
             "hole": summary.hole,
             "must_hole": summary.must_hole,
             "broken": summary.broken,
+            "unresolved": summary.unresolved,
             "opinion": summary.opinion,
             "coverage": round(summary.coverage, 4),
             "orphans": sum(len(v) for v in orphan_map.values()),

{prodc-0.3.6 → prodc-0.3.7}/src/prodc/config.py

@@ -10,6 +10,7 @@ from typing import cast
 from .adapters import (
     AcceptAdapter,
     Adapter,
+    External,
     FilesAdapter,
     FrontmatterAdapter,
     GherkinAdapter,
@@ -61,9 +62,13 @@ class Config:
             kind = tbl.get("kind")
             results = tbl.get("results")
             results_s = results if isinstance(results, str) else None
+            # `repo` points the adapter at a sibling repo checked out beside this one;
+            # its paths then resolve under that repo and reads are wrapped by External.
+            repo_field = tbl.get("repo")
+            proof_root = root / repo_field if isinstance(repo_field, str) else root
             if kind == "gherkin":
-                adapters[name] = GherkinAdapter(
-                    root=root,
+                inner: Adapter = GherkinAdapter(
+                    root=proof_root,
                     paths=_as_str_list(tbl.get("paths", []), f"[proofs.{name}].paths"),
                     delivered_tags=_as_str_list(
                         tbl.get("delivered", []), f"[proofs.{name}].delivered"
@@ -75,19 +80,22 @@ class Config:
                 )
             elif kind == "pytest":
                 sub = tbl.get("root", ".")
-                adapters[name] = PytestAdapter(
-                    root=root / (sub if isinstance(sub, str) else "."),
+                inner = PytestAdapter(
+                    root=proof_root / (sub if isinstance(sub, str) else "."),
                     results=results_s,
                 )
             elif kind == "files":
                 sub = tbl.get("root", ".")
-                adapters[name] = FilesAdapter(root=root / (sub if isinstance(sub, str) else "."))
+                inner = FilesAdapter(root=proof_root / (sub if isinstance(sub, str) else "."))
             elif kind == "accept":
-                adapters[name] = AcceptAdapter()
+                inner = AcceptAdapter()
             else:
                 raise ConfigError(
                     f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest|files|accept)"
                 )
+            adapters[name] = (
+                External(inner, root / repo_field) if isinstance(repo_field, str) else inner
+            )
 
         source_adapters: dict[str, SourceAdapter] = {}
         sources = _as_dict(raw.get("sources", {}), "[sources]")

{prodc-0.3.6 → prodc-0.3.7}/src/prodc/model.py

@@ -27,6 +27,7 @@ class ProofState(StrEnum):
     DELIVERED = "delivered"  # the test exists and (if a results artifact is present) passes
     PENDING = "pending"  # declared/planned, not yet green
     BROKEN = "broken"  # the locator does not resolve to anything
+    UNRESOLVED = "unresolved"  # the source could not be read at all (e.g. sibling repo absent)
 
 
 class NeedState(StrEnum):
@@ -36,6 +37,7 @@ class NeedState(StrEnum):
     PENDING = "pending"
     HOLE = "hole"  # no proof at all — an honest gap, never a build failure
     BROKEN = "broken"  # a proof locator points at nothing
+    UNRESOLVED = "unresolved"  # a proof's source could not be read (e.g. sibling repo absent)
 
 
 @dataclass(frozen=True)

{prodc-0.3.6 → prodc-0.3.7}/src/prodc/status.py

@@ -104,6 +104,8 @@ class Resolver:
         declared = any(r.declared for r in results if r.state is ProofState.DELIVERED)
         if any(r.state is ProofState.BROKEN for r in results):
             state = NeedState.BROKEN
+        elif any(r.state is ProofState.UNRESOLVED for r in results):
+            state = NeedState.UNRESOLVED  # a source couldn't be read — can't judge yet
         elif delivered == len(results):
             state = NeedState.DELIVERED
         else:
@@ -125,6 +127,8 @@ class Resolver:
         total = len(child_states)
         if any(s is NeedState.BROKEN for s in child_states):
             state = NeedState.BROKEN
+        elif any(s is NeedState.UNRESOLVED for s in child_states):
+            state = NeedState.UNRESOLVED
         elif total and delivered == total:
             state = NeedState.DELIVERED
         elif not child_states or all(s is NeedState.HOLE for s in child_states):
@@ -154,12 +158,19 @@ class Summary:
     hole: int
     must_hole: int  # a HOLE on a must-have — the top of the board
     broken: int  # a dangling proof locator
+    unresolved: int  # a proof whose source could not be read (e.g. sibling repo absent)
     opinion: int  # a need with no source of any kind
 
     @property
     def coverage(self) -> float:
-        """Fraction of needs that are DELIVERED (0.0 when there are no needs)."""
-        return self.delivered / self.total if self.total else 0.0
+        """Fraction DELIVERED, of needs that could be read.
+
+        UNRESOLVED needs (a source that couldn't be read) are excluded from the
+        denominator — they neither help nor hurt coverage, so a `--min-coverage` gate
+        isn't failed by an absent sibling the way a BROKEN locator fails it.
+        """
+        judged = self.total - self.unresolved
+        return self.delivered / judged if judged else 0.0
 
 
 def summarize(results: list[NeedResult]) -> Summary:
@@ -172,6 +183,7 @@ def summarize(results: list[NeedResult]) -> Summary:
         hole=by_state[NeedState.HOLE],
         must_hole=sum(1 for r in results if r.need.must and r.state is NeedState.HOLE),
         broken=by_state[NeedState.BROKEN],
+        unresolved=by_state[NeedState.UNRESOLVED],
         opinion=sum(1 for r in results if r.need.is_opinion),
     )
 

{prodc-0.3.6 → prodc-0.3.7}/tests/test_adapters.py

@@ -4,7 +4,13 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from prodc.adapters import AcceptAdapter, FilesAdapter, FrontmatterAdapter, PytestAdapter
+from prodc.adapters import (
+    AcceptAdapter,
+    External,
+    FilesAdapter,
+    FrontmatterAdapter,
+    PytestAdapter,
+)
 from prodc.model import ProofState
 
 
@@ -78,3 +84,20 @@ def test_accept_adapter_is_declared_delivered() -> None:
     r = AcceptAdapter().resolve("jane@2026-09-20")
     assert r.state is ProofState.DELIVERED and r.declared  # a human sign-off, not a test
     assert "accepted by jane" in r.detail and "2026-09-20" in r.detail
+
+
+def test_external_unresolved_when_sibling_absent(tmp_path: Path) -> None:
+    ext = External(FilesAdapter(root=tmp_path / "sib"), tmp_path / "sib")  # not checked out
+    r = ext.resolve("verify.py")
+    assert r.state is ProofState.UNRESOLVED and not r.declared
+
+
+def test_external_reads_sibling_and_records_rev(tmp_path: Path) -> None:
+    sib = tmp_path / "sib"
+    sib.mkdir()
+    (sib / "verify.py").write_text("# model\n", encoding="utf-8")
+    (sib / ".git").mkdir()
+    (sib / ".git" / "HEAD").write_text("abc1234def5678\n", encoding="utf-8")  # detached HEAD
+    r = External(FilesAdapter(root=sib), sib).resolve("verify.py")
+    assert r.state is ProofState.DELIVERED
+    assert "@ sib:abc1234" in r.detail  # traceable to the sibling's exact revision

{prodc-0.3.6 → prodc-0.3.7}/tests/test_status.py

@@ -65,6 +65,21 @@ def test_solution_verb_warns() -> None:
     assert any("solution in disguise" in w for w in r.warnings)
 
 
+def test_unresolved_proof_is_excluded_from_coverage() -> None:
+    from prodc.status import summarize
+
+    delivered = StubAdapter(ProofResult(ProofState.DELIVERED, declared=True, detail="ok"))
+    unresolved = StubAdapter(ProofResult(ProofState.UNRESOLVED, declared=False, detail="absent"))
+    need_ok = Need(id="D", text="t", proofs=("web:x",))
+    need_un = Need(id="U", text="t", proofs=("ext:x",))
+    results = resolve([need_ok, need_un], {"web": delivered, "ext": unresolved})
+    by_id = {r.need.id: r for r in results}
+    assert by_id["U"].state is NeedState.UNRESOLVED
+    s = summarize(results)
+    assert s.unresolved == 1 and s.delivered == 1
+    assert s.coverage == 1.0  # 1 delivered / (2 total - 1 unresolved); the absent one is excluded
+
+
 def test_dangling_source_warns_distinct_from_opinion(tmp_path: Path) -> None:
     (tmp_path / "issues").mkdir()
     (tmp_path / "issues" / "reg.md").write_text("# A-1 ok\n", encoding="utf-8")