trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/board_lanes.py

@@ -0,0 +1,134 @@
+"""Board lane assignment, server-side (#2953, ADR-0843).
+
+The case 16 rendering rule renders in the browser
+(``packages/web/src/features/board/laneAssignment.ts``). This is the same rule
+as a server derivation, used as the **oracle for ADR-0843 invariant 1**: the
+structure-declaration suites assert that a row promoted to a container by
+indent, or created as one by import, groups here as a lane and never as a card.
+The three invariants are identical to the browser's, and deliberately so — two
+answers to one question is worse than one answer stated twice:
+
+1. **A container is never a card.** A row with structural children is a lane,
+   never a work item in a column, at any depth.
+2. **Every task appears exactly once**, in the lane of its top-level container
+   ancestor. Containers nested below that lane travel on the card as a crumb.
+3. **Root-level work belongs to the project node**, whose lane carries the
+   project's name and is absent when it holds nothing.
+
+``group_depth`` defaults to 1 and is a parameter so a caller can cut lanes
+deeper; the depth distribution measured on 2026-08-18 put 94.9% of leaf rows at
+depth <= 2 with no crumb at all, so nothing asks for anything else today.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .models import Task
+
+#: Sentinel lane id for work hanging directly off the project node.
+ROOT_LANE_ID = "root"
+
+
+@dataclass
+class Lane:
+    """One board swimlane: a real container, or the project node."""
+
+    id: str
+    name: str
+    #: True for the project-node lane — says *which* object it is, not that it lacks one.
+    is_root: bool = False
+    task_ids: list[str] = field(default_factory=list)
+
+
+def _wbs_parts(task: Task) -> list[str]:
+    return str(task.wbs_path).split(".") if task.wbs_path else []
+
+
+def _container_paths(by_path: dict[str, Task]) -> set[str]:
+    """Every path with something beneath it.
+
+    A row is a container iff something else sits beneath it. Derived, exactly as
+    ``task_is_phase`` derives it — this must not diverge from the rollup's notion of a
+    phase (ADR-0844: the derived fact wins for the math).
+    """
+    container_paths: set[str] = set()
+    for path in by_path:
+        parts = path.split(".")
+        for i in range(1, len(parts)):
+            container_paths.add(".".join(parts[:i]))
+    return container_paths
+
+
+def _crumb_for(parts: list[str], lane_path: str, by_path: dict[str, Task]) -> str | None:
+    """The row's own parent name when the lane cannot show it, else ``None``."""
+    parent_path = ".".join(parts[:-1])
+    if parent_path != lane_path:
+        parent = by_path.get(parent_path)
+        if parent is not None:
+            return parent.name
+    return None
+
+
+def build_lanes(
+    tasks: list[Task],
+    *,
+    project_name: str,
+    group_depth: int = 1,
+) -> tuple[list[Lane], dict[str, str]]:
+    """Group ``tasks`` into lanes, and say which crumb each card carries.
+
+    Returns ``(lanes, crumb_by_task_id)``. A task absent from the crumb map sits
+    directly in its lane, which is the overwhelming majority.
+
+    Parenthood is the ltree ``wbs_path`` — there is no ``parent_id`` column — so
+    a lane at ``group_depth=1`` is the first path segment, and the crumb names
+    the row's immediate parent when that parent is not the lane itself.
+    """
+    by_path: dict[str, Task] = {
+        str(t.wbs_path): t for t in tasks if t.wbs_path and not t.is_subtask
+    }
+    container_paths = _container_paths(by_path)
+
+    lanes: dict[str, Lane] = {}
+    order: list[str] = []
+    crumbs: dict[str, str] = {}
+    root_lane = Lane(id=ROOT_LANE_ID, name=project_name, is_root=True)
+
+    for path, task in sorted(by_path.items(), key=lambda kv: _sort_key(kv[0])):
+        if path in container_paths:
+            continue  # invariant 1 — a container is never a card
+
+        parts = path.split(".")
+        if len(parts) <= group_depth:
+            root_lane.task_ids.append(str(task.id))
+            continue
+
+        lane_path = ".".join(parts[:group_depth])
+        head = by_path.get(lane_path)
+        if head is None:
+            # A gap in the tree (a deleted ancestor) must not drop the card.
+            root_lane.task_ids.append(str(task.id))
+            continue
+        if lane_path not in lanes:
+            lanes[lane_path] = Lane(id=str(head.id), name=head.name)
+            order.append(lane_path)
+        lanes[lane_path].task_ids.append(str(task.id))
+
+        crumb = _crumb_for(parts, lane_path, by_path)
+        if crumb is not None:
+            crumbs[str(task.id)] = crumb
+
+    out = [lanes[p] for p in order]
+    # Invariant 3: the project-node lane is absent when it holds nothing.
+    if root_lane.task_ids:
+        out.append(root_lane)
+    return out, crumbs
+
+
+def _sort_key(path: str) -> tuple[int, ...]:
+    """Numeric WBS ordering — ``1.10`` sorts after ``1.9``, not between 1 and 2."""
+    try:
+        return tuple(int(p) for p in path.split("."))
+    except ValueError:
+        return (0,)

trueppm_api/apps/projects/bulk_settings.py

@@ -0,0 +1,194 @@
+"""Bulk-PATCH of inherited settings across many Program or Project rows (ADR-0161, #1233).
+
+The settings matrix (Workspace → Programs and Program → Projects) lets an admin set an
+inherited field — methodology, iteration label, risk policy — on a *selection* of entities
+in one call instead of N per-entity PATCHes. This module holds the request envelope, the
+per-scope field-whitelist serializers (which reuse the same field-level validation as the
+per-entity serializers), and the atomic apply routine. The thin ``ProgramViewSet`` actions
+in :mod:`program_views` wire these to two routes.
+
+Scope of the 0.3 slice (the rest of #1233's field list is deferred — see ADR-0161):
+  * Programs (workspace scope): ``methodology``, ``iteration_label``,
+    ``risk_slip_propagation``, ``risk_escalation_days``.
+  * Projects (program scope): ``methodology``, ``iteration_label``.
+
+``calendar`` (Project-only, schedule-affecting with no bulk recalc path yet) and the
+notification defaults (not Program/Project fields — they live in
+``ProjectNotificationPreference``) are deferred to follow-ups.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db.models import QuerySet
+from rest_framework import serializers
+from rest_framework.exceptions import PermissionDenied
+
+from trueppm_api.apps.projects.methodology import methodology_override_locked
+from trueppm_api.apps.projects.models import Program, Project
+from trueppm_api.apps.workspace.models import Workspace
+
+# Cap on the rows a single bulk call may touch. Generous for a real workspace (programs) or
+# program (projects) selection, but bounds the per-row ``select_for_update`` + ``save`` loop
+# so the endpoint can't be used to lock a large slice of the table in one request.
+MAX_BULK_TARGETS = 200
+
+
+def _validate_iteration_label(value: str | None) -> str | None:
+    """Mirror ``Program/ProjectSerializer.validate_iteration_label`` (ADR-0116).
+
+    ``None`` clears the override so the row inherits its parent's label; a non-null
+    empty/whitespace string is rejected because "inherit" already has an explicit
+    representation (``null``). ``max_length`` is enforced by the model field.
+    """
+    if value is None:
+        return None
+    stripped = value.strip()
+    if not stripped:
+        raise serializers.ValidationError(
+            "Enter a label for the iteration container, or clear it to inherit the parent default."
+        )
+    return stripped
+
+
+class _InheritedMethodologyMixin:
+    """Shared ``methodology`` lock backstop (ADR-0107 §4).
+
+    A per-entity methodology override is forbidden only while a workspace enforcement lock
+    is active — which never happens in OSS (no enforcement provider is registered), so this
+    is the server-side backstop for a direct API write. Re-sending the current value is a
+    harmless no-op and is allowed even under a lock. ``PermissionDenied`` (403) is the
+    correct response for a policy refusal, matching the per-entity serializers.
+    """
+
+    instance: Any  # set by DRF when the serializer wraps a model row
+    context: dict[str, Any]  # provided by the DRF serializer this mixes into
+
+    def validate_methodology(self, value: str) -> str:
+        instance = getattr(self, "instance", None)
+        if instance is not None and value == instance.methodology:
+            return value
+        # Read the singleton from context (hoisted once per bulk call by
+        # apply_bulk_fields) so a 200-row batch doesn't reload it per row; fall back to a
+        # direct load when the serializer is used standalone.
+        workspace = self.context.get("workspace") or Workspace.load()
+        if methodology_override_locked(workspace):
+            raise PermissionDenied(
+                "This workspace's methodology policy locks the delivery model to the "
+                "workspace default — it can't be set per entity."
+            )
+        return value
+
+
+class ProgramBulkFieldsSerializer(_InheritedMethodologyMixin, serializers.ModelSerializer[Program]):
+    """Whitelist + field validation for a workspace-scope program bulk-PATCH."""
+
+    class Meta:
+        model = Program
+        fields = [  # noqa: RUF012 — DRF Meta field list (matches the serializers.py per-file ignore)
+            "methodology",
+            "iteration_label",
+            "risk_slip_propagation",
+            "risk_escalation_days",
+        ]
+
+    def validate_iteration_label(self, value: str | None) -> str | None:
+        return _validate_iteration_label(value)
+
+
+class ProjectBulkFieldsSerializer(_InheritedMethodologyMixin, serializers.ModelSerializer[Project]):
+    """Whitelist + field validation for a program-scope project bulk-PATCH.
+
+    Deliberately narrower than :class:`ProgramBulkFieldsSerializer`: ``calendar`` is
+    omitted (schedule-affecting, no bulk recalc path yet) and the program-only risk fields
+    do not exist on Project. Only the two benign, non-schedule inherited fields ship here.
+    """
+
+    class Meta:
+        model = Project
+        fields = ["methodology", "iteration_label"]  # noqa: RUF012 — DRF Meta field list
+
+    def validate_iteration_label(self, value: str | None) -> str | None:
+        return _validate_iteration_label(value)
+
+
+class BulkFieldsRequestSerializer(serializers.Serializer[Any]):
+    """Request envelope: which rows to change, and which fields to set on them.
+
+    ``ids`` are the entities the user checked; ``fields`` is the partial field map to apply.
+    Only the named fields on the named rows change — every other row and every other field
+    keeps inheriting (#1233). The *values* in ``fields`` are validated per-scope by the
+    per-entity serializer the caller passes to :func:`apply_bulk_fields`; this envelope only
+    enforces the request shape (non-empty, well-typed ids, bounded count).
+    """
+
+    ids = serializers.ListField(
+        child=serializers.UUIDField(),
+        allow_empty=False,
+        max_length=MAX_BULK_TARGETS,
+    )
+    # The wire key is "fields" (the partial field map). Declaring a field named ``fields``
+    # shadows DRF's base ``Serializer.fields`` property for the type checker only — at
+    # runtime declared fields live in ``_declared_fields`` and the ``.fields`` property
+    # still returns the BindingDict (verified by the endpoint tests).
+    fields = serializers.DictField(allow_empty=False)  # type: ignore[assignment]
+
+
+def apply_bulk_fields(
+    *,
+    field_serializer_cls: type[serializers.ModelSerializer[Any]],
+    queryset: QuerySet[Any],
+    ids: list[Any],
+    fields: dict[str, Any],
+) -> list[Any]:
+    """Validate ``fields`` against the scope whitelist and apply them to the rows in
+    ``queryset`` whose pk is in ``ids``. **Must run inside ``transaction.atomic()``**
+    (it locks the targets with ``select_for_update``).
+
+    Raises ``serializers.ValidationError`` (→ 400) for a field not bulk-editable in this
+    scope, an id outside the allowed scope, or a bad value. All-or-nothing: any failure
+    raises inside the caller's atomic block and rolls the whole batch back. Returns the
+    updated rows with their freshly bumped ``server_version``.
+    """
+    allowed = set(field_serializer_cls.Meta.fields)
+    unknown = sorted(set(fields) - allowed)
+    if unknown:
+        raise serializers.ValidationError(
+            {"fields": f"Not bulk-editable in this scope: {unknown}. Allowed: {sorted(allowed)}."}
+        )
+
+    # Dedupe while preserving the caller's order; compare as str so UUID objects and the
+    # DB's UUID pks match regardless of representation.
+    unique_ids = list(dict.fromkeys(str(i) for i in ids))
+    rows = list(queryset.filter(pk__in=unique_ids).select_for_update())
+    found = {str(r.pk) for r in rows}
+    missing = [i for i in unique_ids if i not in found]
+    if missing:
+        # 400, not silent skip: an id outside scope is a client error (wrong program,
+        # archived/closed/deleted row, or another tenant's entity) the caller should see.
+        raise serializers.ValidationError(
+            {"ids": f"Not found or outside the allowed scope: {missing}."}
+        )
+
+    # Hoist the workspace singleton out of the loop — the methodology validator needs it,
+    # and reloading it per row would be a needless N+1 on a 200-row batch (perf-check #1233).
+    workspace = Workspace.load()
+    for row in rows:
+        ser = field_serializer_cls(row, data=fields, partial=True, context={"workspace": workspace})
+        ser.is_valid(raise_exception=True)
+        ser.save()  # per-row save() so VersionedModel bumps server_version + history audits
+    return rows
+
+
+def build_bulk_response(rows: list[Any], fields: dict[str, Any]) -> dict[str, Any]:
+    """Lightweight, context-free response for a bulk apply.
+
+    Returns each touched row's id and its new ``server_version`` (so an offline client can
+    advance its sync watermark) plus the field names applied — not a full re-serialization,
+    which would need the viewset's queryset annotations and request context.
+    """
+    return {
+        "updated": [{"id": str(r.pk), "server_version": r.server_version} for r in rows],
+        "fields": sorted(fields),
+    }

trueppm_api/apps/projects/bundled_templates.py

@@ -0,0 +1,215 @@
+"""The starter templates that ship with the install (#2909, ADR-0789).
+
+Why these exist at all: **Template** is one of three peer ways in on the Start
+sheet, and on every fresh install it was empty — the only row-creation site was
+the publish action, and no publish UI existed. A way-in that is empty on first
+contact is worse than no way-in, because the user has already chosen it.
+
+They also carry the product's own argument. `createdProjectDestination` sends an
+**AGILE + template** project straight to a seeding Product Backlog rather than to
+an empty Schedule, which is the "this is a sprint tool, not a Gantt with a board
+bolted on" signal a delivery lead is looking for — and until now that path could
+not be walked, because it needed a template that did not exist.
+
+Deliberately small. A starter is a **shape to argue with**, not a plan: enough
+structure that the phases and the dependency spine are visible, few enough rows
+that deleting the half that does not apply is a minute's work. A 140-row starter
+reads as somebody else's project.
+
+They are `COMMUNITY` provenance, which is what the gallery labels "Bundled" and
+sorts last — on a workspace that has published its own shapes, the local ones are
+the ones worth reading first.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Names are the identity: the seeding migration is idempotent on them, so
+#: renaming one here creates a second row rather than editing the first.
+SCRUM_TEAM = "Scrum product team"
+STAGE_GATE = "Stage-gate delivery"
+HYBRID_RELEASE = "Regulated release"
+
+BUNDLED_TEMPLATE_NAMES = (SCRUM_TEAM, STAGE_GATE, HYBRID_RELEASE)
+
+
+def _node(
+    ref: str,
+    name: str,
+    path: str,
+    *,
+    duration: int | None = 5,
+    milestone: bool = False,
+    mode: str = "waterfall",
+    governance: str = "flow",
+    task_type: str = "task",
+    notes: str = "",
+) -> dict[str, Any]:
+    return {
+        "ref": ref,
+        "name": name,
+        "wbs_path": path,
+        "duration": 0 if milestone else duration,
+        "is_milestone": milestone,
+        "delivery_mode": "milestone" if milestone else mode,
+        "governance_class": governance,
+        "type": task_type,
+        "is_subtask": False,
+        "notes": notes,
+    }
+
+
+def _document(
+    methodology: str,
+    tasks: list[dict[str, Any]],
+    dependencies: list[dict[str, Any]],
+    *,
+    sprint_length: int | None = None,
+) -> dict[str, Any]:
+    """Wrap nodes in the structure envelope `validate_structure` accepts.
+
+    ``extracted_at`` is deliberately absent: these were not extracted from any
+    project, and stamping a time would imply a provenance they do not have. The
+    field is optional in the envelope for exactly this case.
+    """
+    carries = ["structure"]
+    if dependencies:
+        carries.append("dependencies")
+    if any(t["duration"] for t in tasks):
+        carries.append("durations")
+    if any(t["is_milestone"] for t in tasks):
+        carries.append("milestones")
+    carries.append("delivery_modes")
+    if sprint_length:
+        carries.append("sprint_length")
+    return {
+        "version": 1,
+        "methodology": methodology,
+        "sprint_length_days": sprint_length,
+        "tasks": tasks,
+        "dependencies": dependencies,
+        "carries": carries,
+    }
+
+
+def _fs(pred: str, succ: str, lag: int = 0) -> dict[str, Any]:
+    return {"predecessor": pred, "successor": succ, "dep_type": "FS", "lag": lag}
+
+
+def scrum_product_team() -> dict[str, Any]:
+    """A squad's first two sprints, plus the discovery that precedes them."""
+    tasks = [
+        _node("dsc", "Discovery", "1", duration=10, mode="scrum"),
+        _node("dsc-1", "Frame the problem and the users", "1.1", duration=3, mode="scrum"),
+        _node("dsc-2", "Shape the first slice", "1.2", duration=4, mode="scrum"),
+        _node("dsc-3", "Size and order the backlog", "1.3", duration=3, mode="scrum"),
+        _node("rdy", "Backlog ready", "1.4", milestone=True),
+        _node("s1", "Sprint 1 — walking skeleton", "2", duration=10, mode="scrum"),
+        _node("s1-1", "Thinnest end-to-end path", "2.1", duration=5, mode="scrum"),
+        _node("s1-2", "Make it demonstrable", "2.2", duration=3, mode="scrum"),
+        _node("s1-3", "Sprint review and retro", "2.3", duration=1, mode="scrum"),
+        _node("s2", "Sprint 2 — the first real slice", "3", duration=10, mode="scrum"),
+        _node("s2-1", "Build the slice", "3.1", duration=6, mode="scrum"),
+        _node("s2-2", "Harden and instrument", "3.2", duration=3, mode="scrum"),
+        _node("s2-3", "Sprint review and retro", "3.3", duration=1, mode="scrum"),
+    ]
+    deps = [_fs("dsc", "s1"), _fs("s1", "s2"), _fs("dsc-3", "rdy")]
+    return _document("AGILE", tasks, deps, sprint_length=10)
+
+
+def stage_gate_delivery() -> dict[str, Any]:
+    """Five gated phases with a hold point at each — the classic waterfall spine."""
+    tasks = [
+        _node("ini", "Initiate", "1", duration=10, governance="gated"),
+        _node("ini-1", "Charter and scope", "1.1", duration=5, governance="gated"),
+        _node("ini-2", "Stakeholders and constraints", "1.2", duration=5, governance="gated"),
+        _node("g1", "Gate 1 — approved to plan", "1.3", milestone=True, governance="gated"),
+        _node("pln", "Plan", "2", duration=15, governance="gated"),
+        _node("pln-1", "Work breakdown", "2.1", duration=7, governance="gated"),
+        _node("pln-2", "Schedule and resource plan", "2.2", duration=8, governance="gated"),
+        _node("g2", "Gate 2 — approved to execute", "2.3", milestone=True, governance="gated"),
+        _node("exe", "Execute", "3", duration=40, governance="gated"),
+        _node("exe-1", "Build", "3.1", duration=25, governance="gated"),
+        _node("exe-2", "Integrate", "3.2", duration=15, governance="gated"),
+        _node("ver", "Verify", "4", duration=15, governance="gated"),
+        _node("ver-1", "Test and defect burn-down", "4.1", duration=10, governance="gated"),
+        _node("ver-2", "Acceptance", "4.2", duration=5, governance="gated"),
+        _node("g3", "Gate 3 — approved to release", "4.3", milestone=True, governance="gated"),
+        _node("clo", "Close", "5", duration=10, governance="gated"),
+        _node("clo-1", "Handover and documentation", "5.1", duration=6, governance="gated"),
+        _node("clo-2", "Lessons learned", "5.2", duration=4, governance="gated"),
+        _node("g4", "Gate 4 — closed", "5.3", milestone=True, governance="gated"),
+    ]
+    deps = [
+        _fs("ini", "pln"),
+        _fs("pln", "exe"),
+        _fs("exe", "ver"),
+        _fs("ver", "clo"),
+        _fs("ini-2", "g1"),
+        _fs("pln-2", "g2"),
+        _fs("ver-2", "g3"),
+        _fs("clo-2", "g4"),
+        _fs("exe-1", "exe-2"),
+    ]
+    return _document("WATERFALL", tasks, deps)
+
+
+def regulated_release() -> dict[str, Any]:
+    """A gated validation branch beside a sprint-driven build branch.
+
+    The shape hybrid exists for: the build runs in sprints and the evidence trail
+    runs on gates, and they converge once rather than interleaving.
+    """
+    tasks = [
+        _node("pre", "Preparation", "1", duration=10, governance="hybrid"),
+        _node("pre-1", "Scope and regulatory basis", "1.1", duration=5, governance="gated"),
+        _node("pre-2", "Backlog and release goal", "1.2", duration=5, mode="scrum"),
+        _node("bld", "Build", "2", duration=30, mode="scrum"),
+        _node("bld-1", "Sprint 1", "2.1", duration=10, mode="scrum"),
+        _node("bld-2", "Sprint 2", "2.2", duration=10, mode="scrum"),
+        _node("bld-3", "Sprint 3", "2.3", duration=10, mode="scrum"),
+        _node("val", "Validation", "3", duration=20, governance="gated"),
+        _node("val-1", "Protocol and traceability", "3.1", duration=8, governance="gated"),
+        _node("val-2", "Execute and record evidence", "3.2", duration=12, governance="gated"),
+        _node("gv", "Validation gate", "3.3", milestone=True, governance="gated"),
+        _node("rel", "Release", "4", duration=8, governance="gated"),
+        _node("rel-1", "Release notes and sign-off", "4.1", duration=5, governance="gated"),
+        _node("rel-2", "Deploy", "4.2", duration=3, governance="gated"),
+        _node("gr", "Released", "4.3", milestone=True, governance="gated"),
+    ]
+    deps = [
+        _fs("pre", "bld"),
+        _fs("pre-1", "val-1"),
+        _fs("bld-1", "bld-2"),
+        _fs("bld-2", "bld-3"),
+        _fs("bld", "val-2"),
+        _fs("val-2", "gv"),
+        _fs("gv", "rel"),
+        _fs("rel-2", "gr"),
+    ]
+    return _document("HYBRID", tasks, deps, sprint_length=10)
+
+
+#: ``(name, description, structure_builder)`` — one starter per methodology, so
+#: whichever way in a new team picks, the gallery has something for it.
+BUNDLED_TEMPLATES: tuple[tuple[str, str, Any], ...] = (
+    (
+        SCRUM_TEAM,
+        "Discovery, then two sprints that build a walking skeleton before a real "
+        "slice. For a squad with no history yet.",
+        scrum_product_team,
+    ),
+    (
+        STAGE_GATE,
+        "Five gated phases with a hold point at each. Heavy on milestones, light "
+        "on tasks — the spine, not the plan.",
+        stage_gate_delivery,
+    ),
+    (
+        HYBRID_RELEASE,
+        "A gated validation branch beside a sprint-driven build branch, converging "
+        "once at release. For work that ships iteratively and must evidence itself.",
+        regulated_release,
+    ),
+)