prodc 0.3.62__tar.gz → 0.3.63__tar.gz

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

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

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

@@ -20,6 +20,16 @@ from pathlib import Path
 from typing import cast
 
 from . import __version__
+from .board import (
+    annotate_board_warnings as _annotate_board_warnings,
+)
+from .board import (
+    gather,
+    need_payload,
+)
+from .board import (
+    warrant as _warrant,
+)
 from .callbacks import advance_ledger, fire, read_ledger, transitions, write_ledger
 from .config import Config, ConfigError
 from .dedup import (
@@ -39,7 +49,6 @@ from .model import (
     NeedState,
     Release,
     Role,
-    SourceKind,
     ears_shape,
 )
 from .report import render_markdown
@@ -52,18 +61,10 @@ from .status import (
     applicable_needs,
     argument_defects,
     evidence_age_days,
-    flow_orphan_warnings,
-    goal_report,
-    handoffs,
-    last_observed,
-    orphans,
     proof_suggestions,
     rank,
     recurrence,
-    release_report,
     resolve,
-    role_report,
-    shared_proof_warnings,
     state_priority,
     summarize,
 )
@@ -90,22 +91,6 @@ _LABEL = {
 }
 
 
-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 _provenance_counts(results: list[NeedResult]) -> dict[str, int]:
     """How many needs carry each evidence tier (primary/secondary/assumption/opinion)."""
     counts = {"primary": 0, "secondary": 0, "assumption": 0, "opinion": 0}
@@ -349,52 +334,6 @@ def _summary_payload(summary: Summary, orphan_map: dict[str, list[str]]) -> dict
     }
 
 
-def _need_payload(r: NeedResult) -> dict[str, object]:
-    """One need's common fields — shared by the board and `show` so the two never drift."""
-    need = r.need
-    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,
-    }
-
-
 def _to_json(
     results: list[NeedResult],
     summary: Summary,
@@ -463,7 +402,7 @@ def _to_json(
             for goal, gsum in goal_cov
         ],
         "ungoaled": [r.need.id for r in ungoaled],
-        "needs": [_need_payload(r) for r in results],
+        "needs": [need_payload(r) for r in results],
     }
     return json.dumps(payload, indent=2)
 
@@ -482,17 +421,6 @@ def _load_or_report(args: argparse.Namespace) -> tuple[Config, Model] | None:
         return None
 
 
-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 _annotate_duplicate_warnings(
     results: list[NeedResult], needs: list[Need], threshold: float
 ) -> None:
@@ -628,15 +556,15 @@ def _cmd_status(args: argparse.Namespace) -> int:
             for n in needs
             if (age := evidence_age_days(n, today)) is not None and age > args.stale
         ]
-    results = resolve(needs, cfg.adapters, cfg.source_adapters)
-    _annotate_board_warnings(results, needs)
-    summary = summarize(results)
-    orphan_map = orphans(needs, cfg.adapters)
-    recs = recurrence(needs)
-    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))
-    hos = handoffs(needs)
+    board = gather(cfg, model, needs=needs, annotate_warnings=True)
+    results = board.results
+    summary = board.summary
+    orphan_map = board.orphans
+    recs = board.recurrence
+    goal_cov, ungoaled = board.goal_cov, board.ungoaled
+    rel_cov = board.rel_cov
+    role_cov, unroled = board.role_cov, board.unroled
+    hos = board.handoffs
 
     if args.columns:
         bad = [c for c in args.columns if c not in _COLUMNS]
@@ -776,7 +704,7 @@ def _render_show(r: NeedResult, importance_label: str | None = None) -> str:
 
 def _show_json(r: NeedResult) -> str:
     need = r.need
-    payload = _need_payload(r)  # the shared core — never drifts from the board
+    payload = need_payload(r)  # the shared core — never drifts from the board
     payload.update(
         {
             "label": need.label,

{prodc-0.3.62 → prodc-0.3.63}/src/prodc/report.py

@@ -11,18 +11,10 @@ from __future__ import annotations
 
 from datetime import date
 
+from .board import gather
 from .config import Config
 from .model import Model, NeedResult, NeedState
-from .status import (
-    goal_report,
-    handoffs,
-    recurrence,
-    release_report,
-    resolve,
-    role_report,
-    state_priority,
-    summarize,
-)
+from .status import state_priority
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -58,14 +50,14 @@ def render_markdown(
     model (so `--client` reuses the same filter the board uses). ``rev`` is an optional short git
     revision to stamp the report, so a printed copy says which state it reflects.
     """
-    needs = list(model.needs)
-    results = resolve(needs, cfg.adapters, cfg.source_adapters)
-    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))
-    hos = handoffs(needs)
-    recs = recurrence(needs)
+    board = gather(cfg, model)
+    results = board.results
+    summary = board.summary
+    goal_cov, ungoaled = board.goal_cov, board.ungoaled
+    rel_cov = board.rel_cov
+    role_cov, unroled = board.role_cov, board.unroled
+    hos = board.handoffs
+    recs = board.recurrence
 
     scope = f" — {client}" if client else ""
     stamp = date.today().isoformat() + (f" · {rev}" if rev else "")

{prodc-0.3.62 → prodc-0.3.63}/src/prodc/report_html.py

@@ -12,74 +12,21 @@ from __future__ import annotations
 import json
 from datetime import date
 
+from .board import gather, need_payload
 from .config import Config
-from .model import Model, NeedResult
-from .status import (
-    goal_report,
-    handoffs,
-    recurrence,
-    release_report,
-    resolve,
-    role_report,
-    summarize,
-)
-
-
-def _need_payload(r: NeedResult) -> dict[str, object]:
-    """One need, flattened to the plain JSON the viewer renders a row and its detail from."""
-    need = r.need
-    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
-        ],
-    }
+from .model import Model
 
 
 def board_payload(
     cfg: Config, model: Model, *, client: str | None = None, rev: str | None = None
 ) -> dict[str, object]:
     """Gather the resolved board into a plain-dict snapshot (the data the viewer renders)."""
-    needs = list(model.needs)
-    results = resolve(needs, cfg.adapters, cfg.source_adapters)
-    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))
+    board = gather(cfg, model)
+    results = board.results
+    summary = board.summary
+    goal_cov, ungoaled = board.goal_cov, board.ungoaled
+    rel_cov = board.rel_cov
+    role_cov, unroled = board.role_cov, board.unroled
 
     def _cov(delivered: int, total: int) -> dict[str, object]:
         pct = round(delivered / total * 100) if total else None
@@ -102,7 +49,7 @@ def board_payload(
             "opinion": summary.opinion,
             "coverage_pct": round(summary.coverage * 100),
         },
-        "needs": [_need_payload(r) for r in results if r.need.product],
+        "needs": [need_payload(r, flavor="html") for r in results if r.need.product],
         "goals": [{"id": g.id, "text": g.text, **_cov(s.delivered, s.total)} for g, s in goal_cov],
         "ungoaled": [r.need.id for r in ungoaled],
         "releases": [
@@ -119,7 +66,7 @@ def board_payload(
                 "count": rec.count,
                 "clients": list(rec.clients),
             }
-            for rec in recurrence(needs)
+            for rec in board.recurrence
         ],
         "handoffs": [
             {
@@ -129,7 +76,7 @@ def board_payload(
                 "from_need": h.from_need.id,
                 "to_need": h.to_need.id,
             }
-            for h in handoffs(needs)
+            for h in board.handoffs
         ],
     }