prodc 0.3.75__tar.gz → 0.3.76__tar.gz

{prodc-0.3.75 → prodc-0.3.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.75
+Version: 0.3.76
 Summary: Product management as code: roles, 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.75 → prodc-0.3.76}/pyproject.toml

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

{prodc-0.3.75 → prodc-0.3.76}/src/prodc/agent.md

@@ -75,6 +75,7 @@ Read first, then act, then check.
 | attach evidence after a user said something | `prodc capture <id> --kind primary --who <person> [--role <id>] --date <ISO> --quote "…"` (`--role` records which declared role vouched for it) |
 | set or append a field | `prodc set <id> key=value` (append a list with `key+=value`, e.g. `proofs+=web:orders.feature#…`) |
 | propose / attach a proof for a HOLE | `prodc suggest <id> [--apply] [--dry-run]` |
+| relink a BROKEN proof (renamed test) | `prodc suggest --relink [<id>] [--apply] [--dry-run]` — proposes the nearest live inventory entry to replace the broken locator |
 | link a recurring want to a shared baseline | `prodc recurrence --suggest --apply --baseline-id <id> --file needs/<f>.yaml` |
 | record a human/AI review of the warrant | `prodc attest <id> --by <who> --date <ISO> [--ai]` |
 | record a human acceptance pass | `prodc accept <id> --who <person> --date <ISO>` |

{prodc-0.3.75 → prodc-0.3.76}/src/prodc/cli/app.py

@@ -433,10 +433,15 @@ def main(argv: list[str] | None = None) -> int:
     sg.add_argument(
         "--kind", default=None, metavar="ADAPTER", help="only suggest from this adapter name"
     )
+    sg.add_argument(
+        "--relink",
+        action="store_true",
+        help="BROKEN-need mode: propose a live inventory entry to replace each broken locator (#54)",
+    )
     sg.add_argument(
         "--apply",
         action="store_true",
-        help="write the best suggestion per need as a proof (#54); honours --min-score",
+        help="write the best suggestion per need as a proof (relink: replace the broken one) (#54)",
     )
     sg.add_argument(
         "--dry-run",

{prodc-0.3.75 → prodc-0.3.76}/src/prodc/cli/commands.py

@@ -33,11 +33,13 @@ from ..report import render_markdown
 from ..report_html import render_html
 from ..status import (
     ProofSuggestion,
+    RelinkSuggestion,
     applicable_needs,
     argument_defects,
     evidence_age_days,
     proof_suggestions,
     recurrence,
+    relink_suggestions,
     resolve,
     summarize,
 )
@@ -53,6 +55,7 @@ from ..writer import (
     delete_need,
     link_variant_group,
     reinstate,
+    relink_proof,
     set_field,
     set_importance,
     withdraw,
@@ -954,7 +957,7 @@ def cmd_agent(args: argparse.Namespace) -> int:
 
 
 def cmd_suggest(args: argparse.Namespace) -> int:
-    """Propose candidate proof locators for HOLE needs from the adapters' inventories (#54)."""
+    """Propose candidate proof locators for HOLE needs (or relink BROKEN ones) from the inventories (#54)."""
     loaded = load_or_report(args)
     if loaded is None:
         return 2
@@ -966,6 +969,8 @@ def cmd_suggest(args: argparse.Namespace) -> int:
         if not results:
             print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
             return 2
+    if args.relink:
+        return _cmd_relink(cfg, results, args)
     suggestions = proof_suggestions(
         results, cfg.adapters, min_score=args.min_score, top=args.top, kind=args.kind
     )
@@ -1044,6 +1049,88 @@ def _apply_suggestions(
     return 0
 
 
+def _cmd_relink(cfg: Config, results: list[NeedResult], args: argparse.Namespace) -> int:
+    """Propose (or --apply) a live inventory entry to replace each BROKEN proof locator (#54)."""
+    suggestions = relink_suggestions(
+        results, cfg.adapters, min_score=args.min_score, top=args.top, kind=args.kind
+    )
+    if args.apply:
+        return _apply_relinks(cfg, suggestions, args)
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "need": s.need.id,
+                        "adapter": s.adapter,
+                        "broken": s.broken,
+                        "locator": s.locator,
+                        "score": round(s.score, 4),
+                    }
+                    for s in suggestions
+                ],
+                indent=2,
+            )
+        )
+    else:
+        last = None
+        for s in suggestions:
+            if s.need.id != last:
+                print(f"{s.need.id}: {s.need.text}")
+                last = s.need.id
+            print(f"    {s.score:.2f}  {s.broken} → {s.locator}")
+        print(f"suggest --relink: {len(suggestions)} candidate(s) at min-score {args.min_score:.2f}")
+    return 0
+
+
+def _apply_relinks(
+    cfg: Config, suggestions: list[RelinkSuggestion], args: argparse.Namespace
+) -> int:
+    """Apply the best relink per broken locator, printing each need's diff (#54 relink).
+
+    Keyed by ``(need, broken locator)`` so a need with two broken proofs relinks both to their own
+    best candidate. Each is one reload-gated single-file edit (:func:`relink_proof`), applied in a
+    stable order; a rejected write aborts with a non-zero exit (earlier writes stand).
+    """
+    best: dict[tuple[str, str], RelinkSuggestion] = {}
+    for s in suggestions:
+        best.setdefault((s.need.id, s.broken), s)
+    applied: list[tuple[RelinkSuggestion, Edit]] = []
+    for key in sorted(best):
+        s = best[key]
+        try:
+            edit = relink_proof(cfg, s.need.id, s.broken, s.locator, dry_run=args.dry_run)
+        except WriteError as exc:
+            print(f"prodc: {exc}", file=sys.stderr)
+            return 2
+        applied.append((s, edit))
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "need": s.need.id,
+                        "broken": s.broken,
+                        "locator": s.locator,
+                        "score": round(s.score, 4),
+                        "file": edit.path.name,
+                        "dry_run": args.dry_run,
+                        "diff": edit.diff,
+                    }
+                    for s, edit in applied
+                ],
+                indent=2,
+            )
+        )
+    else:
+        verb = "would relink" if args.dry_run else "relinked"
+        for s, edit in applied:
+            print(f"{verb} {s.broken} → {s.locator} on {s.need.id} ({s.score:.2f}) in {edit.path.name}")
+            print(edit.diff, end="")
+        print(f"suggest --relink --apply: {verb} {len(applied)} locator(s)")
+    return 0
+
+
 def cmd_recurrence(args: argparse.Namespace) -> int:
     """Show baselines shared across clients; `--suggest` proposes unlinked variant groups (#56)."""
     loaded = load_or_report(args)

{prodc-0.3.75 → prodc-0.3.76}/src/prodc/status.py

@@ -445,6 +445,62 @@ def proof_suggestions(
     return out
 
 
+@dataclass(frozen=True)
+class RelinkSuggestion:
+    """A candidate replacement for a BROKEN proof locator — a renamed test, relinkable (#54)."""
+
+    need: Need
+    adapter: str  # the adapter the broken locator (and the replacement) resolve through
+    broken: str  # the locator currently on the need that no longer resolves
+    locator: str  # the proposed replacement, "<adapter>:<inventory id>"
+    score: float
+
+
+def relink_suggestions(
+    results: list[NeedResult],
+    adapters: dict[str, Adapter],
+    *,
+    min_score: float,
+    top: int,
+    kind: str | None = None,
+) -> list[RelinkSuggestion]:
+    """Propose the nearest live inventory entry for each BROKEN proof locator (#54 relink).
+
+    A relink is for a locator whose adapter still exists but whose id no longer resolves — a test
+    that was renamed. So it only proposes within the *same* adapter (the kind is stable, the id
+    drifted), scoring each inventory entry by the similarity of its matchable part to the broken
+    id's matchable part, falling back to the need text. A locator whose adapter is absent entirely
+    cannot be relinked (there is no inventory to match against) and is skipped. Read-only.
+    """
+    out: list[RelinkSuggestion] = []
+    for r in results:
+        if r.state is not NeedState.BROKEN or r.need.children:
+            continue
+        for proof in r.need.proofs:
+            if _resolve_proof(proof, adapters).state is not ProofState.BROKEN:
+                continue
+            name, _, payload = proof.partition(":")
+            if kind is not None and name != kind:
+                continue
+            ad = adapters.get(name)
+            if not isinstance(ad, Inventoried):
+                continue  # adapter gone, or can't enumerate — nothing to relink against
+            scored: list[RelinkSuggestion] = []
+            for inv in ad.inventory():
+                candidate = f"{name}:{inv}"
+                if candidate in r.need.proofs:
+                    continue  # already on the need
+                score = max(
+                    similarity(_matchable(payload), _matchable(inv)),
+                    similarity(r.need.text, _matchable(inv)),
+                )
+                if score >= min_score:
+                    scored.append(RelinkSuggestion(r.need, name, proof, candidate, score))
+            scored.sort(key=lambda s: (-s.score, s.locator))
+            out.extend(scored[:top])
+    return out
+
+
 _STATE_RANK = {
     NeedState.BROKEN: 1,
     NeedState.PENDING: 2,

{prodc-0.3.75 → prodc-0.3.76}/src/prodc/writer.py

@@ -603,6 +603,46 @@ def add_proof(
     return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
 
 
+def relink_proof(
+    config: Config,
+    need_id: str,
+    old_locator: str,
+    new_locator: str,
+    *,
+    expect_sha: str | None = None,
+    dry_run: bool,
+) -> Edit:
+    """Replace one (broken) proof locator with a proposed one, in place — the relink of #54.
+
+    The write path for ``suggest --relink --apply``: a renamed test keeps its adapter kind but
+    gets a new id, so this swaps ``old_locator`` for ``new_locator`` on the need and de-duplicates
+    (if the replacement already sits on the need, the broken one is simply dropped). Errors if the
+    old locator is not actually on the need. One reload-gated single-file splice, like
+    :func:`add_proof`.
+    """
+    path, _ = _locate(config, need_id)
+    doc, old_text = _read_doc(path)
+    if expect_sha is not None and _sha256(old_text) != expect_sha:
+        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
+    for raw in _need_list(doc, path):
+        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
+            need = cast("dict[str, object]", raw)
+            current = need.get("proofs", [])
+            if not isinstance(current, list):
+                raise WriteError(f"{path.name}: 'proofs' is not a list")
+            proofs = list(cast("list[object]", current))
+            if old_locator not in proofs:
+                raise WriteError(f"{old_locator!r} is not a proof on {need_id!r}")
+            swapped = [new_locator if p == old_locator else p for p in proofs]
+            deduped: list[object] = []
+            for p in swapped:
+                if p not in deduped:
+                    deduped.append(p)
+            need["proofs"] = deduped
+            break
+    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+
+
 def add_need(
     config: Config,
     need_id: str,

prodc-0.3.76/tests/test_relink.py

@@ -0,0 +1,103 @@
+"""BROKEN relink (#54): propose a live inventory entry to replace a renamed-test locator."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.cli import main
+from prodc.config import Config
+from prodc.loader import load
+
+_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+[proofs.web]
+kind = "gherkin"
+paths = ["features/*.feature"]
+delivered = ["@implemented"]
+"""
+
+# The scenario the need points at was renamed: "...order" -> "...an order".
+_FEATURE = """
+Feature: orders
+  @implemented
+  Scenario: Owner cancels an order
+    Given a thing
+    Then it works
+"""
+
+_NEEDS = """
+needs:
+  - id: N-1
+    text: the owner can cancel an order
+    proofs: ["web:orders.feature#Owner cancels order"]
+  - id: H-1
+    text: an unrelated hole
+"""
+
+
+def _project(tmp_path: Path) -> Path:
+    (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")
+    return tmp_path / "prodc.toml"
+
+
+def test_relink_proposes_renamed_scenario(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    main(["suggest", "--relink", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    assert len(payload) == 1
+    s = payload[0]
+    assert s["need"] == "N-1"
+    assert s["broken"] == "web:orders.feature#Owner cancels order"
+    assert s["locator"] == "web:orders.feature#Owner cancels an order"
+
+
+def test_relink_only_targets_broken_not_hole(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    main(["suggest", "--relink", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    assert {s["need"] for s in payload} == {"N-1"}  # H-1 is a HOLE, not a relink target
+
+
+def test_relink_apply_swaps_locator_and_delivers(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    cfg = _project(tmp_path)
+    code = main(["suggest", "--relink", "--apply", "--config", str(cfg)])
+    assert code == 0
+    capsys.readouterr()
+    need = {n.id: n for n in load(Config.load(cfg)).needs}["N-1"]
+    assert need.proofs == ("web:orders.feature#Owner cancels an order",)
+
+
+def test_relink_apply_dry_run_writes_nothing(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    cfg = _project(tmp_path)
+    before = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
+    code = main(["suggest", "--relink", "--apply", "--dry-run", "--config", str(cfg)])
+    assert code == 0
+    capsys.readouterr()
+    assert (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8") == before
+
+
+def test_relink_skips_when_adapter_absent(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    # A locator whose adapter does not exist is BROKEN but has no inventory to relink against.
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text("[prodc]\nneeds = [\"needs/*.yaml\"]\n", encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(
+        "needs:\n  - id: N-1\n    text: t\n    proofs: ['ghost:1']\n", encoding="utf-8"
+    )
+    main(["suggest", "--relink", "--config", str(tmp_path / "prodc.toml"), "--json"])
+    assert json.loads(capsys.readouterr().out) == []

{prodc-0.3.75 → prodc-0.3.76}/tests/test_writer.py

@@ -15,6 +15,7 @@ from prodc.writer import (
     add_role,
     capture_source,
     delete_need,
+    relink_proof,
     set_field,
 )
 
@@ -303,6 +304,27 @@ def test_delete_need_dry_run_leaves_file(tmp_path: Path) -> None:
     assert "N-1" in edit.diff and edit.diff.startswith("---")
 
 
+def test_relink_proof_swaps_locator(tmp_path: Path) -> None:
+    cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: t\n    proofs: ['web:a#Old']\n")
+    relink_proof(cfg, "N-1", "web:a#Old", "web:a#New", dry_run=False)
+    assert load(cfg).needs[0].proofs == ("web:a#New",)
+
+
+def test_relink_proof_rejects_absent_old(tmp_path: Path) -> None:
+    cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: t\n    proofs: ['web:a#Old']\n")
+    with pytest.raises(WriteError, match="is not a proof on 'N-1'"):
+        relink_proof(cfg, "N-1", "web:a#Missing", "web:a#New", dry_run=False)
+
+
+def test_relink_proof_dedupes_when_new_already_present(tmp_path: Path) -> None:
+    cfg = _proj(
+        tmp_path,
+        "needs:\n  - id: N-1\n    text: t\n    proofs: ['web:a#Old', 'web:a#New']\n",
+    )
+    relink_proof(cfg, "N-1", "web:a#Old", "web:a#New", dry_run=False)
+    assert load(cfg).needs[0].proofs == ("web:a#New",)  # broken dropped, no duplicate
+
+
 def test_add_draft_stamps_draft_added(tmp_path: Path) -> None:
     cfg = _proj(tmp_path, "needs: []\n")
     add_need(