prodc 0.3.61__tar.gz → 0.3.63__tar.gz

{prodc-0.3.61 → prodc-0.3.63}/PKG-INFO

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

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

{prodc-0.3.61 → prodc-0.3.63}/src/prodc/agent.md

@@ -76,6 +76,7 @@ Read first, then act, then check.
 | 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>` |
 | hand a human a readable status file | `prodc report -o status.md` (markdown; `--format html` for an interactive viewer; `--client ID` to scope) |
+| act on a need going green (notify a tracker, etc.) | `prodc sync` — runs the `[callbacks]` commands for needs whose state changed since the last sync (`--dry-run` to preview) |
 | gate in CI | `prodc lint --strict` |
 
 Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <toml>…`

prodc-0.3.63/src/prodc/board.py

@@ -0,0 +1,218 @@
+"""Gather the resolved board once, for every renderer to consume.
+
+`prodc status`, `prodc report` (markdown), and `prodc report --format html` each need the
+same thing: resolve every need, roll it up, and compute the per-goal / per-release / per-role
+coverage, the handoffs, the recurrence, and the orphan proofs. They used to do that gather
+three separate times, which is how the three outputs could silently drift. :func:`gather` does
+it once and returns a :class:`ResolvedBoard`; the renderers format that struct. :func:`warrant`
+and :func:`need_payload` are the one user-signal string and the one Need-to-dict serialiser the
+board and the HTML viewer share, so a need looks the same wherever it is rendered.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import Literal
+
+from .config import Config
+from .model import (
+    Goal,
+    Model,
+    Need,
+    NeedResult,
+    Release,
+    Role,
+    SourceKind,
+    ears_shape,
+)
+from .status import (
+    Handoff,
+    Recurrence,
+    Summary,
+    evidence_age_days,
+    flow_orphan_warnings,
+    goal_report,
+    handoffs,
+    last_observed,
+    orphans,
+    recurrence,
+    release_report,
+    resolve,
+    role_report,
+    shared_proof_warnings,
+    summarize,
+)
+
+
+def warrant(need: Need) -> str:
+    """The warrant column: the strongest source kind, or 'opinion' when there is no source at all.
+
+    A `primary` source names its person (`primary:who`); `secondary`/`assumption` show the kind. A
+    need with any source is shown by that kind even if it is an opinion (only an assumption) — the
+    opinion roll-up lives in the gap counts, this column shows the literal evidence tier.
+    """
+    strongest = need.strongest_kind  # the one source-strength ranking lives on the model
+    if strongest is None:
+        return "opinion"
+    if strongest is SourceKind.PRIMARY:
+        who = next((s.who for s in need.sources if s.kind is SourceKind.PRIMARY and s.who), None)
+        return f"primary:{who}" if who else "primary"
+    return strongest.value
+
+
+def annotate_board_warnings(results: list[NeedResult], needs: list[Need]) -> None:
+    """Append the cross-need hygiene warnings (shared proofs #45, seam coverage #44)."""
+    shared = shared_proof_warnings(results)
+    flow_orphans = flow_orphan_warnings(needs)
+    for r in results:
+        if r.need.id in shared:
+            r.warnings.append(shared[r.need.id])
+        if r.need.id in flow_orphans:
+            r.warnings.append("belongs to no flow — seam not covered (#44)")
+
+
+def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -> dict[str, object]:
+    """One need serialised to a plain dict — the single Need-to-JSON used by the board and viewer.
+
+    ``flavor="board"`` is the status/`show` payload (the full record); ``flavor="html"`` is the
+    report viewer's flatter row. They carry different fields in a different order, so the two
+    shapes live here together, byte-for-byte as they were, rather than as copies in two modules.
+    """
+    need = r.need
+    if flavor == "html":
+        strongest = need.strongest_kind
+        return {
+            "id": need.id,
+            "text": need.text,
+            "description": need.description,
+            "state": r.state.value,
+            "must": need.must,
+            "who": need.who or "(unassigned)",
+            "label": need.label,
+            "client": need.client,
+            "opinion": need.is_opinion,
+            "warrant": strongest.value if strongest is not None else "opinion",
+            "importance": need.importance,
+            "goal": need.goal,
+            "release": need.release,
+            "claim": need.claim,
+            "proofs": list(need.proofs),
+            "detail": list(r.detail),
+            "warnings": list(r.warnings),
+            "attestation": (
+                {
+                    "who": need.attestation.who,
+                    "date": need.attestation.date,
+                    "kind": need.attestation.kind.value,
+                    "verdict": need.attestation.verdict,
+                }
+                if need.attestation
+                else None
+            ),
+            "sources": [
+                {
+                    "kind": s.kind.value,
+                    "who": s.who,
+                    "date": s.date,
+                    "quote": s.quote,
+                    "locator": s.locator,
+                }
+                for s in need.sources
+            ],
+        }
+    return {
+        "id": need.id,
+        "who": need.who,
+        "role": need.role,
+        "text": need.text,
+        "description": need.description,
+        "must": need.must,
+        "state": r.state.value,
+        "grounds": r.state.value,
+        "warrant": warrant(need),
+        "shape": ears_shape(need.text).value,
+        "client": need.client,
+        "variant_of": need.variant_of,
+        "goal": need.goal,
+        "release": need.release,
+        "product": need.product,
+        "draft": need.draft,
+        "importance": need.importance,
+        "importance_set_at": need.importance_set_at,
+        "claim": need.claim,
+        "attestation": (
+            {
+                "who": need.attestation.who,
+                "date": need.attestation.date,
+                "kind": need.attestation.kind.value,
+                "verdict": need.attestation.verdict,
+                "comment": need.attestation.comment,
+            }
+            if need.attestation
+            else None
+        ),
+        "delivered": r.delivered,
+        "total": r.total,
+        "declared": r.declared,
+        "opinion": need.is_opinion,
+        "only_assumption": need.only_assumption,
+        "evidence_age": evidence_age_days(need, date.today()),
+        "last_observed_at": last_observed(need),
+        "detail": r.detail,
+        "warnings": r.warnings,
+    }
+
+
+@dataclass(frozen=True)
+class ResolvedBoard:
+    """The board resolved once: the results and every roll-up the renderers read off it."""
+
+    results: list[NeedResult]
+    summary: Summary
+    goal_cov: list[tuple[Goal, Summary]]
+    ungoaled: list[NeedResult]
+    rel_cov: list[tuple[Release, Summary]]
+    role_cov: list[tuple[Role, Summary]]
+    unroled: list[NeedResult]
+    handoffs: list[Handoff]
+    recurrence: list[Recurrence]
+    orphans: dict[str, list[str]]
+
+
+def gather(
+    cfg: Config,
+    model: Model,
+    *,
+    needs: list[Need] | None = None,
+    annotate_warnings: bool = False,
+) -> ResolvedBoard:
+    """Resolve the board once and compute every roll-up a renderer needs.
+
+    ``needs`` overrides which needs are resolved (the caller filters drafts/client/goal/stale
+    before calling and passes the result); it defaults to the whole model. ``annotate_warnings``
+    appends the cross-need board warnings (#44/#45) to the results, as ``prodc status`` does —
+    the markdown/HTML reports leave it off, exactly as they did before this was factored out.
+    The declared goals/releases/roles come from ``model``; the recurrence/handoffs/orphans views
+    are computed over the resolved ``needs``.
+    """
+    use_needs = list(model.needs) if needs is None else needs
+    results = resolve(use_needs, cfg.adapters, cfg.source_adapters)
+    if annotate_warnings:
+        annotate_board_warnings(results, use_needs)
+    summary = summarize(results)
+    goal_cov, ungoaled = goal_report(results, list(model.goals))
+    rel_cov = release_report(results, list(model.releases))
+    role_cov, unroled = role_report(results, list(model.roles))
+    return ResolvedBoard(
+        results=results,
+        summary=summary,
+        goal_cov=goal_cov,
+        ungoaled=ungoaled,
+        rel_cov=rel_cov,
+        role_cov=role_cov,
+        unroled=unroled,
+        handoffs=handoffs(use_needs),
+        recurrence=recurrence(use_needs),
+        orphans=orphans(use_needs, cfg.adapters),
+    )

prodc-0.3.63/src/prodc/callbacks.py

@@ -0,0 +1,195 @@
+"""Lifecycle callbacks: run a command when a need changes state (#71).
+
+The signal that a need is done already lives in prodc — its proof resolving to DELIVERED. This
+lets a team act on that event: when a need's state changes, prodc runs a command from the project
+config with the affected need (and board context) as JSON on **stdin**. Same trust model as the
+command hook (#70): the command comes only from the config, never from need data; the need data is
+piped as data, never executed.
+
+A state change needs the *previous* state, which prodc (stateless per run — it re-reads every file)
+does not otherwise keep. So a small ledger (``state_file``) records each need's last-seen state;
+`prodc sync` resolves the board, diffs it against the ledger, fires the matching callbacks, and
+writes the ledger forward. The first run records a baseline and fires nothing (everything would
+look new). A callback that fails is reported, never silent, and its need is *not* advanced in the
+ledger, so the next sync retries it.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .model import Need
+
+#: The only event implemented today; others from #71 (capture/report/pre_gate) are follow-ups.
+STATE_CHANGE = "state_change"
+
+#: Runs an argv (no shell) with a JSON payload on stdin, returning (ok, short reason). Injected in
+#: tests so no process spawns; :func:`_invoke` is the real subprocess default.
+Invoker = Callable[[tuple[str, ...], str, Path, float], tuple[bool, str]]
+
+
+@dataclass(frozen=True)
+class Callback:
+    """One configured lifecycle callback: an event, a command, and optional transition filters."""
+
+    event: str
+    command: tuple[str, ...]
+    timeout: float = 30.0
+    on_from: frozenset[str] = frozenset()  # empty = any source state
+    on_to: frozenset[str] = frozenset()  # empty = any target state
+
+    def matches(self, frm: str, to: str) -> bool:
+        """Whether this callback fires for a transition ``frm -> to``."""
+        if self.on_from and frm not in self.on_from:
+            return False
+        return not (self.on_to and to not in self.on_to)
+
+
+@dataclass(frozen=True)
+class Transition:
+    """A need whose resolved state changed since the last sync."""
+
+    need_id: str
+    frm: str
+    to: str
+
+
+@dataclass(frozen=True)
+class Fired:
+    """The outcome of running one callback for one transition."""
+
+    transition: Transition
+    command: tuple[str, ...]
+    ok: bool
+    detail: str
+
+
+def read_ledger(path: Path) -> dict[str, str] | None:
+    """The last-seen state per need id, or ``None`` when no ledger exists yet (first run)."""
+    if not path.exists():
+        return None
+    try:
+        raw: object = json.loads(path.read_text(encoding="utf-8"))
+    except ValueError:
+        return None
+    if not isinstance(raw, dict):
+        return None
+    return {str(k): str(v) for k, v in cast("dict[object, object]", raw).items()}
+
+
+def write_ledger(path: Path, states: dict[str, str]) -> None:
+    """Persist the current state per need id (keys sorted for a stable, reviewable file)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = json.dumps({k: states[k] for k in sorted(states)}, indent=2) + "\n"
+    path.write_text(body, encoding="utf-8")
+
+
+def transitions(ledger: dict[str, str], current: dict[str, str]) -> list[Transition]:
+    """Needs whose state differs from the ledger.
+
+    A need absent from the ledger is *new*, not a transition — it is baselined silently and never
+    fired on, so adding a need does not masquerade as a state change.
+    """
+    out = [
+        Transition(nid, ledger[nid], state)
+        for nid, state in current.items()
+        if nid in ledger and ledger[nid] != state
+    ]
+    out.sort(key=lambda t: t.need_id)
+    return out
+
+
+def fire(
+    trans: list[Transition],
+    callbacks: list[Callback],
+    *,
+    context: dict[str, Need],
+    board: dict[str, object],
+    cwd: Path,
+    invoke: Invoker | None = None,
+) -> list[Fired]:
+    """Run every callback matching each transition, piping the need + board as JSON on stdin.
+
+    ``context`` maps a need id to its :class:`~prodc.model.Need` (for the payload). Returns one
+    :class:`Fired` per (transition, matching callback) actually run, in transition then config
+    order.
+    """
+    run = invoke or _invoke
+    state_cbs = [c for c in callbacks if c.event == STATE_CHANGE]
+    out: list[Fired] = []
+    for t in trans:
+        need = context.get(t.need_id)
+        payload = json.dumps(
+            {
+                "event": STATE_CHANGE,
+                "from": t.frm,
+                "to": t.to,
+                "need": _need_json(need, t.to) if need else {"id": t.need_id, "state": t.to},
+                "board": board,
+            },
+            ensure_ascii=False,
+        )
+        for cb in state_cbs:
+            if cb.matches(t.frm, t.to):
+                ok, detail = run(cb.command, payload, cwd, cb.timeout)
+                out.append(Fired(t, cb.command, ok, detail))
+    return out
+
+
+def advance_ledger(
+    current: dict[str, str], ledger: dict[str, str], fired: list[Fired]
+) -> dict[str, str]:
+    """The ledger to persist: every need at its current state, except a need whose callback failed
+    — that one keeps its prior state so the next sync retries it."""
+    failed = {f.transition.need_id for f in fired if not f.ok}
+    new = dict(current)
+    for nid in failed:
+        if nid in ledger:  # do not advance a need whose callback failed; retry next sync
+            new[nid] = ledger[nid]
+    return new
+
+
+def _invoke(command: tuple[str, ...], payload: str, cwd: Path, timeout: float) -> tuple[bool, str]:
+    """Run ``command`` (no shell) with ``payload`` on stdin; report ok and a short reason.
+
+    Never raises: a spawn failure, a timeout, or a non-zero exit all come back as ``ok=False`` with
+    a reason, so a broken callback is reported, never silent and never fatal to the sync itself.
+    """
+    try:
+        proc = subprocess.run(
+            list(command),
+            input=payload,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return False, f"timed out after {timeout:g}s"
+    except OSError as exc:
+        return False, f"could not run ({exc})"
+    if proc.returncode == 0:
+        return True, "ok"
+    tail = (proc.stderr or proc.stdout or "").strip().splitlines()
+    return False, f"exit {proc.returncode}" + (f": {tail[-1]}" if tail else "")
+
+
+def _need_json(need: Need, state: str) -> dict[str, object]:
+    strongest = need.strongest_kind
+    return {
+        "id": need.id,
+        "text": need.text,
+        "state": state,
+        "who": need.who,
+        "client": need.client,
+        "must": need.must,
+        "goal": need.goal,
+        "release": need.release,
+        "warrant": strongest.value if strongest is not None else "opinion",
+    }