trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/product_backlog_services.py

@@ -0,0 +1,450 @@
+"""Service + pure-compute layer for the Product-Owner backlog (ADR-0105).
+
+Separated from the viewset so the logic is unit-testable and has one source of truth:
+
+1. **Scoring** — ``compute_score`` derives a WSJF / RICE / value-effort score from a task's
+   distinct per-model input columns for the project's active model. Computed, never stored.
+2. **Definition of Ready** — ``dor_blockers`` enumerates why a story may not be marked READY;
+   ``ac_counts`` powers the acceptance-criteria meter (from the AcceptanceCriterion child rows).
+   The READY transition is gated on an empty blocker list but is advisory (it does not block
+   the team from pulling a story into a sprint via the planning/scope path).
+3. **Auto-rank** — ``auto_rank`` is a one-shot sort of the project backlog by the active model's
+   score, writing the result into ``priority_rank`` (manual rank as tiebreaker). There is no
+   persistent lock — a later manual drag always wins. Iterated via ``save()`` so each row bumps
+   ``server_version`` and writes ``HistoricalTask`` (audit).
+4. **Dual ordering** — ``seed_sprint_rank`` seeds the within-sprint execution order from
+   ``priority_rank`` at sprint commit; in-sprint reorders write ``sprint_rank`` only (ADR-0105 §5).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from django.db import transaction
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import (
+    AcceptanceCriterion,
+    DorState,
+    PrioritizationModel,
+    Project,
+    Task,
+    TaskStatus,
+    TaskType,
+)
+from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+# ── Scoring ─────────────────────────────────────────────────────────────────
+
+
+def compute_score(task: Task, model: str) -> float | None:
+    """Return the prioritization score for ``task`` under ``model``, or None.
+
+    WSJF = (business_value+time_criticality+risk_reduction)/job_size,
+    RICE = (reach*impact*confidence)/effort, value_effort = value/effort_estimate.
+    Returns None when any required input is missing or the denominator is zero/absent —
+    an unscored story sorts last and renders as "—" rather than a misleading 0.
+    """
+    if model == PrioritizationModel.WSJF:
+        bv, tc, rr = task.business_value, task.time_criticality, task.risk_reduction
+        size = task.job_size
+        if bv is None or tc is None or rr is None or not size:
+            return None
+        return (bv + tc + rr) / size
+    if model == PrioritizationModel.RICE:
+        reach, impact, confidence, effort = task.reach, task.impact, task.confidence, task.effort
+        if reach is None or impact is None or confidence is None or not effort:
+            return None
+        return (reach * impact * confidence) / effort
+    if model == PrioritizationModel.VALUE_EFFORT:
+        if task.value is None or not task.effort_estimate:
+            return None
+        return task.value / task.effort_estimate
+    return None  # NONE or unknown
+
+
+# ── Acceptance criteria + Definition of Ready ────────────────────────────────
+
+
+def ac_counts(task: Task) -> tuple[int, int]:
+    """Return (met, total) acceptance criteria for the AC meter (DA-10/DA-14).
+
+    Uses the prefetched ``acceptance_criteria`` related rows when available (the grooming
+    endpoint prefetches them) so this stays O(1) queries per task.
+    """
+    criteria = list(task.acceptance_criteria.all())
+    return (sum(1 for c in criteria if c.met), len(criteria))
+
+
+def dor_blockers(task: Task) -> list[str]:
+    """Reasons ``task`` cannot be marked READY (empty list ⇒ it may go Ready).
+
+    The Mark-ready gate (#731): estimated AND at least one acceptance criterion AND every
+    criterion met. Machine-stable codes the web maps to the drawer's DoR checklist copy.
+    """
+    blockers: list[str] = []
+    if task.story_points is None:
+        blockers.append("unestimated")
+    met, total = ac_counts(task)
+    if total == 0:
+        blockers.append("no_acceptance_criteria")
+    elif met < total:
+        blockers.append("acceptance_criteria_unmet")
+    return blockers
+
+
+def apply_acceptance_met_change(
+    criterion: AcceptanceCriterion,
+    *,
+    was_met: bool,
+    actor: Any,
+    now: datetime | None = None,
+) -> bool:
+    """Persist a ``met`` flip and (un)stamp the review trail — the single attribution rule.
+
+    The ONE writer of the ``met_by``/``met_at`` trail (ADR-0105 §2 / ADR-0148), shared by
+    the interactive ``AcceptanceCriterionViewSet`` and the CI ingestion endpoint so the
+    attribution rule is declared once and the two paths can never drift. The caller has
+    already set ``criterion.met`` to its new value; this persists it together with the
+    trail in a single ``save()`` (one ``server_version`` bump). ``actor`` is stamped as
+    ``met_by`` on a become-met flip (the human who minted the CI token, never the CI
+    system itself, mirroring ``ProjectApiTokenAuthentication``'s attribution); the trail
+    is cleared on a become-unmet flip. Idempotent: a no-op flip returns ``False`` and
+    writes nothing — so a CI job re-reporting the same result does not churn the version
+    or restamp attribution.
+    """
+    if criterion.met == was_met:
+        return False
+    if criterion.met:
+        criterion.met_by = actor
+        criterion.met_at = now or timezone.now()
+    else:
+        criterion.met_by = None
+        criterion.met_at = None
+    criterion.save(update_fields=["met", "met_by", "met_at", "server_version"])
+    return True
+
+
+class DorTransitionError(Exception):
+    """Raised when a READY transition is attempted with unresolved DoR blockers."""
+
+    def __init__(self, blockers: list[str]) -> None:
+        self.blockers = blockers
+        super().__init__(f"Cannot mark ready: {', '.join(blockers)}")
+
+
+def mark_ready(task: Task, actor: Any) -> Task:
+    """Transition a story to READY, enforcing the (advisory) DoR gate. Idempotent."""
+    blockers = dor_blockers(task)
+    if blockers:
+        raise DorTransitionError(blockers)
+    if task.dor != DorState.READY:
+        task.dor = DorState.READY
+        task.save(update_fields=["dor", "server_version"])
+        _broadcast_task(task)
+    return task
+
+
+def send_to_refine(task: Task, actor: Any) -> Task:
+    """Move a story back to REFINE (no gate — refining is always allowed)."""
+    if task.dor != DorState.REFINE:
+        task.dor = DorState.REFINE
+        task.save(update_fields=["dor", "server_version"])
+        _broadcast_task(task)
+    return task
+
+
+def _broadcast_task(task: Task) -> None:
+    pid, tid = str(task.project_id), str(task.id)
+    transaction.on_commit(lambda: broadcast_board_event(pid, "task_updated", {"id": tid}))
+
+
+# ── Auto-rank ────────────────────────────────────────────────────────────────
+
+
+def _backlog_stories(project: Project) -> list[Task]:
+    """Project-backlog stories eligible for auto-rank.
+
+    Scoped to ``status=BACKLOG`` and ``sprint__isnull=True`` so re-ranking never touches a
+    task's sprint membership or its ADR-0102 ``sprint_pending`` flag. Epics excluded.
+    """
+    return list(
+        Task.objects.filter(
+            project=project,
+            is_deleted=False,
+            status=TaskStatus.BACKLOG,
+            sprint__isnull=True,
+        )
+        .exclude(type=TaskType.EPIC)
+        .order_by("priority_rank", "short_id")
+    )
+
+
+def auto_rank(project: Project, actor: Any) -> int:
+    """One-shot recompute of ``priority_rank`` from the active scoring model.
+
+    Scored stories sort by score descending; ties (and unscored stories) keep their existing
+    manual order (``priority_rank`` asc, then ``short_id``). Returns the count of rows whose
+    rank changed. Idempotent. Not a persistent lock — a later manual drag rewrites
+    ``priority_rank`` and wins.
+    """
+    model = project.prioritization_model
+    stories = _backlog_stories(project)
+
+    def sort_key(item: tuple[int, Task]) -> tuple[int, float, int]:
+        manual_index, task = item
+        score = compute_score(task, model)
+        if score is None:
+            return (1, 0.0, manual_index)
+        return (0, -score, manual_index)
+
+    ordered = [t for _, t in sorted(enumerate(stories), key=sort_key)]
+
+    changed = 0
+    with transaction.atomic():
+        for new_rank, task in enumerate(ordered, start=1):
+            if task.priority_rank != new_rank:
+                task.priority_rank = new_rank
+                # iterate save() (never bulk_update) so server_version bumps + history writes.
+                task.save(update_fields=["priority_rank", "server_version"])
+                changed += 1
+
+    if changed:
+        pid = str(project.id)
+        transaction.on_commit(
+            lambda: broadcast_board_event(pid, "backlog_reranked", {"project_id": pid})
+        )
+    return changed
+
+
+# ── Manual reorder (ADR-0110, #494) ───────────────────────────────────────────
+
+
+class BacklogReorderConflict(Exception):
+    """Raised when the client's backlog snapshot is stale (ADR-0110 §3).
+
+    Covers every "the backlog moved under you" case — a story added or removed
+    concurrently (the supplied set no longer matches the live backlog) or a row whose
+    ``server_version`` advanced since the client loaded it. The view maps this to 409 and
+    the client refetches + replays the drag. ``ids`` lists the offending task ids.
+    """
+
+    def __init__(self, ids: list[str]) -> None:
+        self.ids = ids
+        super().__init__(f"Stale backlog snapshot for tasks: {', '.join(ids)}")
+
+
+def reorder_backlog(project: Project, ordered: list[tuple[str, int]], actor: Any) -> int:
+    """Apply a manual drag reorder of the project backlog (ADR-0110, #494).
+
+    ``ordered`` is the *complete* current backlog as ``[(task_id, server_version), ...]`` in
+    the new priority order. Renumbers ``priority_rank`` densely 1..N (matching ``auto_rank``'s
+    output shape) so a later auto-rank diff stays clean; sparse keys buy nothing under a
+    full-list rewrite. Optimistic-locked on ``server_version`` and on set-completeness: if the
+    supplied set differs from the live backlog (concurrent add/remove) or any row's version is
+    stale, raises :class:`BacklogReorderConflict` (409) and writes nothing.
+
+    Writes only changed rows, each via ``save()`` (never ``bulk_update``) so ``server_version``
+    bumps and ``HistoricalTask`` is written. Returns the count of rows whose rank changed.
+    Idempotent: re-applying the same order writes nothing. Rank-only — never touches
+    ``sprint_rank`` or ``parent_epic`` (ADR-0110 §5).
+    """
+    changed = 0
+    with transaction.atomic():
+        # Lock the live backlog rows first to serialise concurrent reorders, scoped exactly
+        # like _backlog_stories (BACKLOG, sprint-less, non-epic).
+        live = (
+            Task.objects.select_for_update()
+            .filter(
+                project=project,
+                is_deleted=False,
+                status=TaskStatus.BACKLOG,
+                sprint__isnull=True,
+            )
+            .exclude(type=TaskType.EPIC)
+        )
+        by_id = {str(t.pk): t for t in live}
+        supplied = {tid for tid, _ in ordered}
+
+        # Completeness + membership: the client must hold exactly the current backlog. Any
+        # drift (story added/removed since load, or an id that isn't a current backlog story)
+        # is a stale snapshot → 409, not a partial write.
+        drift = sorted((supplied - by_id.keys()) | (by_id.keys() - supplied))
+        if drift:
+            raise BacklogReorderConflict(drift)
+
+        # Per-row optimistic lock.
+        stale = [tid for tid, sv in ordered if by_id[tid].server_version != sv]
+        if stale:
+            raise BacklogReorderConflict(stale)
+
+        for new_rank, (tid, _) in enumerate(ordered, start=1):
+            task = by_id[tid]
+            if task.priority_rank != new_rank:
+                task.priority_rank = new_rank
+                task.save(update_fields=["priority_rank", "server_version"])
+                changed += 1
+
+        # Registered inside the atomic block so it defers to commit (and fires only within a
+        # transaction). pid is a non-mutating local, so the plain closure capture is safe —
+        # matching the auto_rank pattern.
+        if changed:
+            pid = str(project.id)
+            transaction.on_commit(
+                lambda: broadcast_board_event(pid, "backlog_reranked", {"project_id": pid})
+            )
+    return changed
+
+
+# ── Dual ordering (#365) ──────────────────────────────────────────────────────
+
+
+def seed_sprint_rank(sprint: Any) -> None:
+    """Seed within-sprint execution order from product-backlog priority at commit.
+
+    Called when a sprint activates (PLANNED→ACTIVE). Orders the sprint's tasks by
+    ``priority_rank`` and writes ``sprint_rank`` 1..N. In-sprint reorders thereafter write
+    ``sprint_rank`` only and never touch ``priority_rank`` (ADR-0105 §5).
+    """
+    tasks = list(
+        Task.objects.filter(sprint=sprint, is_deleted=False)
+        .exclude(type=TaskType.EPIC)
+        .order_by("priority_rank", "short_id")
+    )
+    with transaction.atomic():
+        for rank, task in enumerate(tasks, start=1):
+            if task.sprint_rank != rank:
+                task.sprint_rank = rank
+                task.save(update_fields=["sprint_rank", "server_version"])
+
+
+class SprintReorderConflict(Exception):
+    """Raised when an in-sprint reorder can't apply because the sprint backlog drifted.
+
+    Mirrors :class:`BacklogReorderConflict`: a concurrent add/remove/move means the
+    client's snapshot is stale, so the whole reorder is a 409 (write nothing) and the
+    client refetches + replays the drag. ``ids`` lists the offending task ids.
+    """
+
+    def __init__(self, ids: list[str]) -> None:
+        self.ids = ids
+        super().__init__(f"Stale sprint snapshot for tasks: {', '.join(ids)}")
+
+
+def reorder_sprint(sprint: Any, ordered: list[tuple[str, int]], actor: Any) -> int:
+    """Apply a manual drag reorder of a sprint's within-sprint execution order (#365).
+
+    The sprint-backlog analog of :func:`reorder_backlog` (ADR-0105 §5): writes ``sprint_rank``
+    *only* and never touches ``priority_rank``, so reordering for execution never disturbs the
+    Product Owner's product-backlog ranking. ``ordered`` is the *complete* current sprint set as
+    ``[(task_id, server_version), ...]`` in the new execution order, scoped exactly like
+    :func:`seed_sprint_rank` (the sprint's live, non-deleted, non-epic tasks).
+
+    Renumbers ``sprint_rank`` densely 1..N. Optimistic-locked on ``server_version`` and on
+    set-completeness: if the supplied set differs from the live sprint set (concurrent
+    add/remove/carry) or any row's version is stale, raises :class:`SprintReorderConflict`
+    (409) and writes nothing. Writes only changed rows, each via ``save()`` so
+    ``server_version`` bumps and ``HistoricalTask`` is written. Returns the count of rows
+    whose rank changed; idempotent (re-applying the same order writes nothing).
+    """
+    changed = 0
+    with transaction.atomic():
+        # Lock the live sprint rows first to serialise concurrent reorders, scoped exactly
+        # like seed_sprint_rank (the set that was seeded at commit): sprint members, non-epic.
+        live = (
+            Task.objects.select_for_update()
+            .filter(sprint=sprint, is_deleted=False)
+            .exclude(type=TaskType.EPIC)
+        )
+        by_id = {str(t.pk): t for t in live}
+        supplied = {tid for tid, _ in ordered}
+
+        # Completeness + membership: the client must hold exactly the current sprint set. Any
+        # drift (task pulled/carried since load, or an id that isn't a current sprint task) is
+        # a stale snapshot → 409, not a partial write.
+        drift = sorted((supplied - by_id.keys()) | (by_id.keys() - supplied))
+        if drift:
+            raise SprintReorderConflict(drift)
+
+        # Per-row optimistic lock.
+        stale = [tid for tid, sv in ordered if by_id[tid].server_version != sv]
+        if stale:
+            raise SprintReorderConflict(stale)
+
+        for new_rank, (tid, _) in enumerate(ordered, start=1):
+            task = by_id[tid]
+            if task.sprint_rank != new_rank:
+                task.sprint_rank = new_rank
+                task.save(update_fields=["sprint_rank", "server_version"])
+                changed += 1
+
+        # Registered inside the atomic block so it defers to commit (and fires only within a
+        # transaction). The board channel is the project; sprint_id lets the client scope the
+        # refetch. pid/sid are stable locals (not loop vars), so a plain closure is safe.
+        if changed:
+            pid = str(sprint.project_id)
+            sid = str(sprint.id)
+            transaction.on_commit(
+                lambda: broadcast_board_event(
+                    pid, "sprint_reranked", {"project_id": pid, "sprint_id": sid}
+                )
+            )
+    return changed
+
+
+# ── Split story ──────────────────────────────────────────────────────────────
+
+
+def split_story(parent: Task, actor: Any, *, name: str | None = None) -> Task:
+    """Create a sibling story under the same epic, carrying over unmet criteria.
+
+    What the child inherits, and why each answer is what it is:
+
+    * ``parent_epic`` — so the split stays grouped under the same epic.
+    * ``priority_rank`` — the parent's position, verbatim (#3002). A split of the #3
+      story is still the #3 story's work; leaving it null sorts the child **below every
+      ranked item** (the client's 9999 sentinel for "unranked"), which is close to the
+      opposite of where the work belongs. Ranks are not unique and ties already break on
+      a secondary sort, so both halves sitting at the parent's position is harmless.
+      Ranking *after* the parent was rejected: it renumbers neighbors, and ``auto_rank``
+      / ``reorder`` already own the rank space — a third writer of it is a worse problem
+      than a tie. This matches what #2906 decided for the program-backlog pull.
+    * Only **unmet** acceptance criteria are copied — the remaining work.
+    * Story points are **not** divided, and no estimate field carries: the PO re-estimates
+      both halves, so velocity is never double-counted. This is the deliberate asymmetry
+      with ``priority_rank`` — *where* the work sits is known and worth preserving, *how
+      big* it is has to be answered again.
+
+    ``test_every_task_field_is_classified_for_the_split`` holds the rest of the field set
+    to the same standard: every concrete ``Task`` field is classified as carried or
+    explicitly not, so adding one to the model forces the decision rather than defaulting
+    it to "dropped" the way ``priority_rank`` was.
+    """
+    from trueppm_api.apps.projects.models import AcceptanceCriterion
+
+    unmet = [c for c in parent.acceptance_criteria.all() if not c.met]
+    with transaction.atomic():
+        child = Task.objects.create(
+            project=parent.project,
+            name=name or f"{parent.name} (split)",
+            type=parent.type,
+            parent_epic=parent.parent_epic,
+            priority_rank=parent.priority_rank,
+            status=TaskStatus.BACKLOG,
+            sprint=None,
+            dor=DorState.IDEA,
+            notes=f"Split from {parent.short_id or parent.id}.",
+        )
+        for pos, c in enumerate(unmet):
+            AcceptanceCriterion.objects.create(
+                task=child,
+                text=c.text,
+                given=c.given,
+                when=c.when,
+                then=c.then,
+                position=pos,
+            )
+    pid, cid = str(parent.project_id), str(child.id)
+    transaction.on_commit(lambda: broadcast_board_event(pid, "task_created", {"id": cid}))
+    return child

trueppm_api/apps/projects/program_label_services.py

@@ -0,0 +1,94 @@
+"""Program-scoped label reads (ADR-0638, issue #2333).
+
+Labels are project-scoped (`unique(project, name)`), so "every task tagged
+`security-review` in this program" cannot be answered by label id — the same name
+is a different row, with a different id and possibly a different color, in every
+project that uses it. These helpers answer it by **name** instead.
+
+Both functions take an explicit ``project_ids`` iterable rather than a ``Program``.
+That is deliberate and load-bearing (ADR-0638 Decision 4): it is the seam
+``trueppm-enterprise`` calls with a *portfolio's* project set to build the
+cross-program view, without the OSS package ever learning that portfolios exist.
+Callers in this repo are responsible for passing only project ids the requesting
+user may read — the viewset does that, and these functions do not re-check.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TypedDict
+from uuid import UUID
+
+from django.db.models import Count, Min, Prefetch, QuerySet
+from django.db.models.functions import Lower
+
+from trueppm_api.apps.projects.models import Label, Task
+
+
+class LabelCatalogEntry(TypedDict):
+    """One distinct label name across a set of projects."""
+
+    name: str
+    project_count: int
+
+
+def tasks_by_label_name(*, project_ids: Iterable[UUID | str], label_name: str) -> QuerySet[Task]:
+    """Tasks in ``project_ids`` carrying a label whose name matches ``label_name``.
+
+    Matching is **case-insensitive** (ADR-0638 Decision 3): a PM who typed
+    ``Security-Review`` in one project and ``security-review`` in another means one
+    concept, and treating them as two is a bug report waiting to happen.
+
+    Ordering is ``(project.name, wbs_path)`` — grouped by project because the
+    user's first question about a cross-project row is "which project is this in",
+    then plan order within each group. The ordering is total and stable, which
+    matters for pagination: a non-deterministic order across projects lets a page
+    boundary silently skip rows.
+    """
+    return (
+        Task.objects.filter(
+            project_id__in=list(project_ids),
+            is_deleted=False,
+            labels__name__iexact=label_name,
+            labels__is_deleted=False,
+        )
+        .select_related("project")
+        # Soft-deleted labels must never render as a pill — the established
+        # Prefetch pattern for every label read.
+        .prefetch_related(Prefetch("labels", queryset=Label.objects.filter(is_deleted=False)))
+        # A task carrying two labels that both match would otherwise repeat.
+        .distinct()
+        .order_by("project__name", "wbs_path")
+    )
+
+
+def program_label_catalog(*, project_ids: Iterable[UUID | str]) -> list[LabelCatalogEntry]:
+    """Distinct label names across ``project_ids``, with the count of projects using each.
+
+    The count is of **projects carrying the name**, not of tasks. A task count
+    would mean joining the whole task table to render a picker — a read that looks
+    free at five projects and is not at fifty (ADR-0638 Decision 5). This is the
+    one place the program view deliberately differs from ADR-0620, where per-label
+    counts are computed client-side over already-loaded rows; here there is no
+    single loaded row set to count over.
+
+    Grouping is **case-insensitive**, and must be: ``tasks_by_label_name`` matches
+    with ``iexact``, so if the catalog grouped by exact name then ``Security-Review``
+    and ``security-review`` would list as two entries that return byte-identical
+    result sets — the picker would contradict the filter. Rows are keyed on the
+    lowercased name and displayed using the alphabetically-first original spelling,
+    so one concept yields one entry whose label still reads the way a human typed it.
+
+    One aggregate query, not one per project.
+    """
+    rows = (
+        Label.objects.filter(project_id__in=list(project_ids), is_deleted=False)
+        .annotate(name_key=Lower("name"))
+        .values("name_key")
+        .annotate(project_count=Count("project", distinct=True), display_name=Min("name"))
+        .order_by("name_key")
+    )
+    return [
+        LabelCatalogEntry(name=row["display_name"], project_count=row["project_count"])
+        for row in rows
+    ]