prodc 0.3.4__tar.gz → 0.3.5__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.4"
+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.4 → 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.4 → prodc-0.3.5}/src/prodc/cli.py

@@ -194,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)
 
@@ -299,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)
@@ -330,7 +330,7 @@ def _repo_row(config_path: str) -> _RepoRow:
         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)
+    results = resolve(needs, cfg.adapters, cfg.source_adapters)
     s = summarize(results)
     return _RepoRow(
         repo=cfg.root.name,

{prodc-0.3.4 → 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.4 → 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.4 → 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.4 → 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