prodc 0.3.3__tar.gz → 0.3.5__tar.gz

{prodc-0.3.3 → prodc-0.3.5}/PKG-INFO

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

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

{prodc-0.3.3 → prodc-0.3.5}/src/prodc/adapters.py

@@ -243,3 +243,60 @@ class FilesAdapter:
         if not fp.exists():
             return ProofResult(ProofState.BROKEN, False, f"no file '{payload}'")
         return ProofResult(ProofState.DELIVERED, True, "script exists")
+
+
+@dataclass(frozen=True)
+class SourceResult:
+    """Whether a Source.locator resolves. Verifies provenance *exists*, not that it is good."""
+
+    ok: bool
+    detail: str
+
+
+class SourceAdapter(Protocol):
+    def resolve(self, payload: str) -> SourceResult: ...
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+class FrontmatterAdapter:
+    """Resolves ``file#anchor`` against markdown files (e.g. docs/issues/*.md).
+
+    Confirms a heading matching the anchor exists, so a Source citing a ticket/section
+    that is absent or renamed surfaces as a dangling (BROKEN) source — the provenance-side
+    analogue of a BROKEN proof.
+    """
+
+    def __init__(self, root: Path, paths: list[str]) -> None:
+        self._root = root
+        self._paths = paths
+        self._headings: list[tuple[str, str]] | None = None  # (file name, heading text)
+
+    def _load(self) -> list[tuple[str, str]]:
+        if self._headings is not None:
+            return self._headings
+        found: list[tuple[str, str]] = []
+        heading_re = re.compile(r"^#{1,6}\s+(.*?)\s*$")
+        for pattern in self._paths:
+            for fp in sorted(self._root.glob(pattern)):
+                for line in fp.read_text(encoding="utf-8").splitlines():
+                    m = heading_re.match(line)
+                    if m:
+                        found.append((fp.name, m.group(1)))
+        self._headings = found
+        return found
+
+    def resolve(self, payload: str) -> SourceResult:
+        file_part, _, anchor = payload.partition("#")
+        if not anchor:
+            return SourceResult(False, f"no anchor in '{payload}'")
+        want = _slug(anchor)
+        for fname, heading in self._load():
+            if file_part and fname != file_part and not fname.endswith("/" + file_part):
+                continue
+            hslug = _slug(heading)
+            if hslug == want or hslug.startswith(want + "-") or anchor.lower() in heading.lower():
+                return SourceResult(True, f"{fname}: '{heading}'")
+        return SourceResult(False, f"no heading matches '{payload}'")

{prodc-0.3.3 → prodc-0.3.5}/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)
 
 
@@ -187,7 +194,7 @@ def _cmd_status(args: argparse.Namespace) -> int:
     if loaded is None:
         return 2
     cfg, needs = loaded
-    results = resolve(needs, cfg.adapters)
+    results = resolve(needs, cfg.adapters, cfg.source_adapters)
     summary = summarize(results)
     orphan_map = orphans(needs, cfg.adapters)
 
@@ -292,7 +299,7 @@ def _cmd_show(args: argparse.Namespace) -> int:
     if loaded is None:
         return 2
     cfg, needs = loaded
-    by_id = {r.need.id: r for r in resolve(needs, cfg.adapters)}
+    by_id = {r.need.id: r for r in resolve(needs, cfg.adapters, cfg.source_adapters)}
     r = by_id.get(args.need_id)
     if r is None:
         print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
@@ -301,6 +308,66 @@ def _cmd_show(args: argparse.Namespace) -> int:
     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, cfg.source_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:
@@ -353,6 +420,11 @@ def main(argv: list[str] | None = None) -> int:
     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.3 → prodc-0.3.5}/src/prodc/config.py

@@ -7,7 +7,14 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import cast
 
-from .adapters import Adapter, FilesAdapter, GherkinAdapter, PytestAdapter
+from .adapters import (
+    Adapter,
+    FilesAdapter,
+    FrontmatterAdapter,
+    GherkinAdapter,
+    PytestAdapter,
+    SourceAdapter,
+)
 
 
 class ConfigError(Exception):
@@ -34,6 +41,7 @@ class Config:
     root: Path
     need_globs: list[str]
     adapters: dict[str, Adapter] = field(default_factory=dict[str, Adapter])
+    source_adapters: dict[str, SourceAdapter] = field(default_factory=dict[str, SourceAdapter])
 
     @classmethod
     def load(cls, path: Path) -> Config:
@@ -77,4 +85,23 @@ class Config:
                 raise ConfigError(
                     f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest|files)"
                 )
-        return cls(root=root, need_globs=need_globs, adapters=adapters)
+
+        source_adapters: dict[str, SourceAdapter] = {}
+        sources = _as_dict(raw.get("sources", {}), "[sources]")
+        for name, body in sources.items():
+            tbl = _as_dict(body, f"[sources.{name}]")
+            kind = tbl.get("kind")
+            if kind == "frontmatter":
+                source_adapters[name] = FrontmatterAdapter(
+                    root=root,
+                    paths=_as_str_list(tbl.get("paths", []), f"[sources.{name}].paths"),
+                )
+            else:
+                raise ConfigError(f"[sources.{name}]: unknown kind {kind!r} (frontmatter)")
+
+        return cls(
+            root=root,
+            need_globs=need_globs,
+            adapters=adapters,
+            source_adapters=source_adapters,
+        )

{prodc-0.3.3 → prodc-0.3.5}/src/prodc/status.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from .adapters import Adapter, Enumerable, ProofResult
+from .adapters import Adapter, Enumerable, ProofResult, SourceAdapter
 from .model import (
     SOLUTION_VERBS,
     Need,
@@ -36,10 +36,36 @@ def _resolve_proof(locator: str, adapters: dict[str, Adapter]) -> ProofResult:
     return adapter.resolve(payload)
 
 
+def _source_warnings(need: Need, source_adapters: dict[str, SourceAdapter]) -> list[str]:
+    """Flag a Source.locator that names a configured source adapter but does not resolve.
+
+    This is a dangling (BROKEN) *source* — distinct from OPINION (no source at all). A
+    free-text locator with no matching adapter is left unchecked, not flagged.
+    """
+    out: list[str] = []
+    for s in need.sources:
+        if not s.locator:
+            continue
+        name, sep, payload = s.locator.partition(":")
+        adapter = source_adapters.get(name)
+        if not sep or adapter is None:
+            continue
+        res = adapter.resolve(payload)
+        if not res.ok:
+            out.append(f"BROKEN source '{s.locator}' ({res.detail})")
+    return out
+
+
 class Resolver:
-    def __init__(self, needs: list[Need], adapters: dict[str, Adapter]) -> None:
+    def __init__(
+        self,
+        needs: list[Need],
+        adapters: dict[str, Adapter],
+        source_adapters: dict[str, SourceAdapter] | None = None,
+    ) -> None:
         self._by_id = {n.id: n for n in needs}
         self._adapters = adapters
+        self._source_adapters = source_adapters or {}
         self._cache: dict[str, NeedResult] = {}
         self._visiting: set[str] = set()
 
@@ -55,7 +81,11 @@ class Resolver:
         self._visiting.add(need_id)
         result = self._compute(need)
         self._visiting.discard(need_id)
-        result.warnings = _text_warnings(need) + result.warnings
+        result.warnings = (
+            _text_warnings(need)
+            + _source_warnings(need, self._source_adapters)
+            + result.warnings
+        )
         self._cache[need_id] = result
         return result
 
@@ -105,9 +135,13 @@ class Resolver:
         return NeedResult(need, state, delivered, total, declared, detail, warnings)
 
 
-def resolve(needs: list[Need], adapters: dict[str, Adapter]) -> list[NeedResult]:
+def resolve(
+    needs: list[Need],
+    adapters: dict[str, Adapter],
+    source_adapters: dict[str, SourceAdapter] | None = None,
+) -> list[NeedResult]:
     """Resolve every need to a :class:`NeedResult`."""
-    return Resolver(needs, adapters).resolve_all()
+    return Resolver(needs, adapters, source_adapters).resolve_all()
 
 
 @dataclass(frozen=True)

{prodc-0.3.3 → prodc-0.3.5}/tests/test_adapters.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from prodc.adapters import FilesAdapter, PytestAdapter
+from prodc.adapters import FilesAdapter, FrontmatterAdapter, PytestAdapter
 from prodc.model import ProofState
 
 
@@ -52,3 +52,23 @@ def test_files_adapter_existence_is_declared(tmp_path: Path) -> None:
 
 def test_files_adapter_missing_is_broken(tmp_path: Path) -> None:
     assert FilesAdapter(root=tmp_path).resolve("gone.py").state is ProofState.BROKEN
+
+
+def _frontmatter(tmp_path: Path) -> FrontmatterAdapter:
+    (tmp_path / "issues").mkdir()
+    (tmp_path / "issues" / "reg.md").write_text(
+        "# A-1 Partida doble\n\nbody\n\n## A-6 Factura electrónica\n", encoding="utf-8"
+    )
+    return FrontmatterAdapter(root=tmp_path, paths=["issues/*.md"])
+
+
+def test_frontmatter_resolves_existing_heading(tmp_path: Path) -> None:
+    a = _frontmatter(tmp_path)
+    assert a.resolve("reg.md#A-1").ok
+    assert a.resolve("reg.md#A-6").ok  # matches "## A-6 Factura electrónica"
+
+
+def test_frontmatter_dangling_anchor_or_no_anchor(tmp_path: Path) -> None:
+    a = _frontmatter(tmp_path)
+    assert not a.resolve("reg.md#A-9").ok  # no such heading
+    assert not a.resolve("reg.md#").ok  # no anchor at all

{prodc-0.3.3 → prodc-0.3.5}/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")
@@ -150,3 +150,30 @@ def test_show_unknown_need_exits_2(tmp_path: Path, capsys: pytest.CaptureFixture
     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

{prodc-0.3.3 → prodc-0.3.5}/tests/test_status.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 
-from prodc.adapters import ProofResult
-from prodc.model import Need, NeedState, ProofState
+from prodc.adapters import FrontmatterAdapter, ProofResult, SourceAdapter
+from prodc.model import Need, NeedState, ProofState, Source, SourceKind
 from prodc.status import resolve
 
 
@@ -62,3 +63,20 @@ def test_solution_verb_warns() -> None:
     need = Need(id="A-1", text="implement a dashboard", proofs=())
     (r,) = resolve([need], {})
     assert any("solution in disguise" in w for w in r.warnings)
+
+
+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")
+    sources: dict[str, SourceAdapter] = {
+        "issues": FrontmatterAdapter(root=tmp_path, paths=["issues/*.md"])
+    }
+    good = Need(id="N-1", text="t",
+                sources=(Source(kind=SourceKind.ARTIFACT, locator="issues:reg.md#A-1"),))
+    bad = Need(id="N-2", text="t",
+               sources=(Source(kind=SourceKind.ARTIFACT, locator="issues:reg.md#NOPE"),))
+    results = {r.need.id: r for r in resolve([good, bad], {}, sources)}
+    assert not any("BROKEN source" in w for w in results["N-1"].warnings)
+    assert any("BROKEN source" in w for w in results["N-2"].warnings)
+    # both are sourced, so neither is an opinion — BROKEN-source is a distinct signal
+    assert not results["N-2"].need.is_opinion