"""The work breakdown structure: a plan for building the Target architecture. A Specialist divides the build into work packages and activities and estimates each activity's days. Everything after that is code, as it is for the architecture diagram: the plan is checked against the design, the schedule is computed from the days and the dependencies, and the three views a reader sees are written from the result. So the timeline cannot disagree with the plan, and no part of the design can be left out of it. work packages a hierarchy; each delivers named Elements, and is done when the Checks on those Elements pass activities what is done, in which work package, for how many days, after which other activities, and by whom schedule each activity's start and finish day, on a relative axis from Day 0, with no more of the team's activities at once than the team has people; and the critical path """ from __future__ import annotations import datetime as dt import json import math from collections.abc import Mapping, Sequence from dataclasses import dataclass from typing import Any from app.solution_architecture.chain import Upstream, agreed_scope, read_graph WORK_BREAKDOWN_FILE = "work-breakdown.json" TIMELINE_FILE = "timeline.mmd" DICTIONARY_HEADING = "WBS dictionary" TEAM, CUSTOMER = "team", "customer" OWNERS = (TEAM, CUSTOMER) DEFAULT_TEAM_SIZE = 2 DEFAULT_WEEK = 5 MAX_DAYS = 120 # one activity; anything longer is a work package, not an activity _CHART_WIDTH = 60 @dataclass(frozen=True) class Scheduled: id: str start: float finish: float critical: bool def _text(value: Any) -> str: return " ".join(str(value or "").split()) def _list(value: Any) -> list[str]: return [str(item) for item in value] if isinstance(value, list) else [] def parse(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]: """(work packages, activities, problems) from the data file.""" name = WORK_BREAKDOWN_FILE try: data = json.loads(text) except ValueError as exc: return [], [], [f"{name}: not valid JSON ({exc})"] if not isinstance(data, Mapping): return [], [], [f"{name}: must be an object with work_packages and activities"] packages = [p for p in data.get("work_packages") or [] if isinstance(p, Mapping)] activities = [a for a in data.get("activities") or [] if isinstance(a, Mapping)] return [dict(p) for p in packages], [dict(a) for a in activities], [] def check_work_breakdown( attachments: Mapping[str, str], upstream: Upstream | None ) -> list[str]: name = WORK_BREAKDOWN_FILE packages, activities, problems = parse(attachments.get(name, "")) if problems: return problems if not packages: return [f"{name}: lists no work packages"] if not activities: return [f"{name}: lists no activities"] ids = [str(p.get("id", "")) for p in packages] problems += [f"{name}: a work package has no id"] if "" in ids else [] problems += [ f"{name}: work package id {dup} is used more than once" for dup in sorted({i for i in ids if i and ids.count(i) > 1}) ] known = set(ids) parents = {str(p.get("id")): p.get("parent") for p in packages} for package in packages: ident, parent = str(package.get("id")), package.get("parent") if not _text(package.get("name")): problems.append(f"{name}: {ident} has no name") if parent is not None and str(parent) not in known: problems.append( f"{name}: {ident} has parent {parent}, which does not exist" ) seen, node = {ident}, parent while node is not None and str(node) in parents: if str(node) in seen: problems.append(f"{name}: {ident} is its own ancestor") break seen.add(str(node)) node = parents[str(node)] graph = read_graph(upstream) if graph is not None: elements = {element.id for element in graph.elements} covered: set[str] = set() for package in packages: listed = _list(package.get("elements")) covered.update(listed) problems += [ f"{name}: {package.get('id')} delivers {element}, which is not an " "Element of the Target architecture" for element in listed if element not in elements ] left = sorted(elements - covered) if left: problems.append( f"{name}: no work package delivers {', '.join(left)}; every Element " "of the Target architecture belongs to one" ) activity_ids = [str(a.get("id", "")) for a in activities] problems += [ f"{name}: activity id {dup} is used more than once" for dup in sorted({i for i in activity_ids if i and activity_ids.count(i) > 1}) ] known_activities = set(activity_ids) with_work = set() for activity in activities: ident = str(activity.get("id", "")) if not ident or not _text(activity.get("name")): problems.append(f"{name}: an activity needs an id and a name") continue within = str(activity.get("work_package", "")) if within not in known: problems.append(f"{name}: {ident} is in {within}, not a work package") with_work.add(within) days = activity.get("days") if isinstance(days, bool) or not isinstance(days, (int, float)) or days <= 0: problems.append(f"{name}: {ident} needs `days`, a number above 0") elif days > MAX_DAYS: problems.append( f"{name}: {ident} is {days} days; split anything over {MAX_DAYS}" ) problems += [ f"{name}: {ident} comes after {before}, which is not an activity" for before in _list(activity.get("after")) if before not in known_activities ] if activity.get("owner", TEAM) not in OWNERS: problems.append(f"{name}: {ident} owner must be one of {', '.join(OWNERS)}") has_children = {str(parent) for parent in parents.values() if parent is not None} problems += [ f"{name}: {ident} has no activity and no work package beneath it" for ident in ids if ident and ident not in with_work and ident not in has_children ] if not problems and _cycle(activities): problems.append( f"{name}: activities depend on each other in a circle: " + " -> ".join(_cycle(activities)) ) return problems def _cycle(activities: Sequence[Mapping[str, Any]]) -> list[str]: """Activities that depend on each other in a circle; empty when none do.""" after = {str(a["id"]): _list(a.get("after")) for a in activities} state: dict[str, int] = {} def visit(node: str, path: list[str]) -> list[str]: state[node] = 1 for before in after.get(node, ()): if state.get(before) == 1: return ( [*path[path.index(before) :], before] if before in path else [before, node] ) if state.get(before, 0) == 0: found = visit(before, [*path, before]) if found: return found state[node] = 2 return [] for node in after: if state.get(node, 0) == 0: found = visit(node, [node]) if found: return found return [] def schedule( activities: Sequence[Mapping[str, Any]], team_size: int = DEFAULT_TEAM_SIZE ) -> dict[str, Scheduled]: """Each activity's start and finish day, from Day 0. An activity starts when everything it comes after has finished. The team's own activities also wait for a free person: no more run at once than `team_size`. What the customer owns, such as a supplier's lead time, takes nobody from the team. The critical path is every activity with no slack: delay it and the end moves. """ team_size = max(1, int(team_size)) by_id = {str(a["id"]): a for a in activities} after = {ident: _list(a.get("after")) for ident, a in by_id.items()} days = {ident: float(a["days"]) for ident, a in by_id.items()} # The longest chain of work that follows an activity: what to start first when # people are short. followers: dict[str, list[str]] = {ident: [] for ident in by_id} for ident, befores in after.items(): for before in befores: followers[before].append(ident) tail: dict[str, float] = {} def remaining(ident: str) -> float: if ident not in tail: tail[ident] = days[ident] + max( (remaining(f) for f in followers[ident]), default=0.0 ) return tail[ident] start: dict[str, float] = {} finish: dict[str, float] = {} busy: list[tuple[float, float]] = [] # the team's activities already placed pending = set(by_id) while pending: ready = [i for i in pending if all(b in finish for b in after[i])] ready.sort(key=lambda i: (-remaining(i), i)) ident = min( ready, key=lambda i: ( max((finish[b] for b in after[i]), default=0.0), -remaining(i), i, ), ) earliest = max((finish[b] for b in after[ident]), default=0.0) if by_id[ident].get("owner", TEAM) == TEAM: candidates = sorted({earliest, *(end for _, end in busy if end > earliest)}) for moment in candidates: overlapping = sum( 1 for s, e in busy if s < moment + days[ident] and e > moment ) if overlapping < team_size: earliest = moment break busy.append((earliest, earliest + days[ident])) start[ident], finish[ident] = earliest, earliest + days[ident] pending.discard(ident) end = max(finish.values(), default=0.0) latest: dict[str, float] = {} def latest_finish(ident: str) -> float: if ident not in latest: latest[ident] = min( (latest_finish(f) - days[f] for f in followers[ident]), default=end ) return latest[ident] return { ident: Scheduled( ident, start[ident], finish[ident], critical=latest_finish(ident) - finish[ident] < 1e-6, ) for ident in by_id } # --- what the plan is checked against, from the agreed scope ---------------------------- def _scoped(scope: Mapping[str, Any], path: str) -> Any: """A field of the agreed scope, stated or assumed; None when it is neither.""" node: Any = scope.get("stated") or {} for part in path.split("."): node = node.get(part) if isinstance(node, Mapping) else None if node is not None: return node for item in scope.get("assumed") or []: if isinstance(item, Mapping) and item.get("field") == path: return item.get("value") return None def delivery_terms(upstream: Upstream | None) -> dict[str, Any]: """Team size, working week, window and start date, from the agreed scope.""" scope = agreed_scope(upstream) def number(path: str, default: int) -> int: value = _scoped(scope, path) ok = ( isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0 ) return int(value) if ok else default window = _scoped(scope, "delivery.window_weeks") start = _scoped(scope, "delivery.target_start_date") try: start_date = dt.date.fromisoformat(str(start)) if start else None except ValueError: start_date = None return { "team_size": number("delivery.team_size", DEFAULT_TEAM_SIZE), "team_size_stated": _scoped(scope, "delivery.team_size") is not None, "week": number("delivery.working_days_per_week", DEFAULT_WEEK), "window_weeks": window if isinstance(window, (int, float)) else None, "start": start_date, } # --- the three views -------------------------------------------------------------------- def _day(value: float) -> str: return str(int(value)) if float(value).is_integer() else f"{value:.1f}" def _calendar(start: dt.date, day: float, week: int) -> dt.date: """The calendar date of a working day counted from `start`.""" weeks, days = divmod(math.floor(day), week) return start + dt.timedelta(days=weeks * 7 + days) def render(attachments: Mapping[str, str], upstream: Upstream | None) -> str: """The WBS dictionary, the activity sequence and the timeline, as markdown written from the data file. "" when the file cannot be read.""" packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) if problems or not packages or not activities: return "" terms = delivery_terms(upstream) plan = schedule(activities, terms["team_size"]) graph = read_graph(upstream) checks: dict[str, list[str]] = {} for check in graph.checks if graph else (): checks.setdefault(check.applies_to, []).append(check.id) parents = {str(p["id"]): p.get("parent") for p in packages} def depth(ident: str) -> int: level, node = 0, parents.get(ident) while node is not None and str(node) in parents and level < 10: level, node = level + 1, parents.get(str(node)) return level effort: dict[str, float] = {} for activity in activities: effort[str(activity["work_package"])] = effort.get( str(activity["work_package"]), 0.0 ) + float(activity["days"]) def cell(value: Any) -> str: return _text(value).replace("|", "\\|") or "-" lines = [ f"## {DICTIONARY_HEADING}", "", "Each work package, what it delivers, and the Checks that say it is done.", "", "| Id | Work package | Scope | Produces | Elements | Done when these pass | Skills | Days |", "| --- | --- | --- | --- | --- | --- | --- | --- |", ] for package in packages: ident = str(package["id"]) elements = _list(package.get("elements")) accepted = [c for element in elements for c in checks.get(element, [])] lines.append( "| " + " | ".join( [ ident, ("  " * depth(ident)) + cell(package.get("name")), cell(package.get("scope")), cell("; ".join(_list(package.get("produces")))), cell(", ".join(elements)), cell(", ".join(accepted)), cell(", ".join(_list(package.get("skills")))), _day(effort[ident]) if ident in effort else "-", ] ) + " |" ) ordered = sorted(activities, key=lambda a: (plan[str(a["id"])].start, str(a["id"]))) dated = terms["start"] is not None lines += [ "", "## Activity sequence", "", "| Id | Activity | Work package | Days | After | Start | Finish |" + (" Dates |" if dated else "") + " Owner | Critical |", "| --- | --- | --- | --- | --- | --- | --- |" + (" --- |" if dated else "") + " --- | --- |", ] for activity in ordered: item = plan[str(activity["id"])] row = [ str(activity["id"]), cell(activity.get("name")), str(activity.get("work_package")), _day(float(activity["days"])), cell(", ".join(_list(activity.get("after")))), f"Day {_day(item.start)}", f"Day {_day(item.finish)}", ] if dated: begins = _calendar(terms["start"], item.start, terms["week"]) ends = _calendar(terms["start"], max(item.finish - 1e-9, 0), terms["week"]) row.append(f"{begins.isoformat()} to {ends.isoformat()}") row += [str(activity.get("owner", TEAM)), "yes" if item.critical else ""] lines.append("| " + " | ".join(row) + " |") total = max(item.finish for item in plan.values()) weeks = total / terms["week"] lines += [ "", "## Timeline", "", "```text", *_chart(ordered, plan, total), "```", "", ] summary = ( f"{_day(total)} working days, about {weeks:.1f} weeks, with a team of " f"{terms['team_size']}" + ( "" if terms["team_size_stated"] else " (assumed; the scope gives no team size)" ) + f" and a {terms['week']}-day week." ) lines.append(summary) window = terms["window_weeks"] if window is not None: if weeks <= window + 1e-9: lines.append( f"That is inside the {window}-week delivery window, with " f"{window - weeks:.1f} weeks to spare." ) else: path = [str(a["id"]) for a in ordered if plan[str(a["id"])].critical] lines.append( f"**That is {weeks - window:.1f} weeks over the {window}-week delivery " f"window.** The critical path is {' -> '.join(path)}: only shortening " "or removing work on it, or adding people where it waits for them, " "brings the end in." ) theirs = [a for a in ordered if a.get("owner", TEAM) == CUSTOMER] if theirs: lines += ["", "The customer owns these, and the plan waits on them:"] lines += [ f"- {a['id']} {_text(a.get('name'))}: {_day(float(a['days']))} days" + (f". {_text(a.get('assumption'))}" if _text(a.get("assumption")) else "") for a in theirs ] lines += [ "", ( "Durations are estimates made without knowing the team, and are " "indicative. Days are working days counted from Day 0, the day work " "starts; each of the team's activities takes one person." ), ] return "\n".join(lines) + "\n" def _chart( ordered: Sequence[Mapping[str, Any]], plan: Mapping[str, Scheduled], total: float ) -> list[str]: """The timeline as text: one row per activity along a relative day axis.""" scale = min(1.0, _CHART_WIDTH / total) if total else 1.0 labels = [f"{a['id']} {_text(a.get('name'))}"[:38] for a in ordered] width = max(len(label) for label in labels) + 2 step = max(1, math.ceil(total / 6 / 5.0) * 5) axis = [" "] * (int(total * scale) + 8) for day in range(0, int(total) + 1, step): mark = str(day) at = int(day * scale) axis[at : at + len(mark)] = mark rows = [" " * width + "Day " + "".join(axis).rstrip()] for label, activity in zip(labels, ordered, strict=True): item = plan[str(activity["id"])] begin = round(item.start * scale) length = max(1, round((item.finish - item.start) * scale)) block = "░" if activity.get("owner", TEAM) == CUSTOMER else "█" flag = " *" if item.critical else "" rows.append(f"{label.ljust(width)} {' ' * begin}{block * length}{flag}") rows += ["", "█ the team ░ the customer * on the critical path"] return rows def mermaid(attachments: Mapping[str, str], upstream: Upstream | None) -> str: """A Mermaid Gantt chart on calendar dates, when the scope gives a start date. "" otherwise: a relative plan has no dates to draw.""" packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) terms = delivery_terms(upstream) if problems or not activities or terms["start"] is None: return "" plan = schedule(activities, terms["team_size"]) names = {str(p["id"]): _text(p.get("name")) for p in packages} lines = ["gantt", " dateFormat YYYY-MM-DD", " excludes weekends"] for package in packages: own = [ a for a in activities if str(a.get("work_package")) == str(package["id"]) ] if not own: continue lines.append(f" section {names[str(package['id'])].replace(':', ' ')}") for activity in sorted(own, key=lambda a: plan[str(a["id"])].start): item = plan[str(activity["id"])] begins = _calendar(terms["start"], item.start, terms["week"]) tag = "crit, " if item.critical else "" label = _text(activity.get("name")).replace(":", " ") lines.append( f" {label} :{tag}{activity['id']}, {begins.isoformat()}, " f"{max(1, math.ceil(float(activity['days'])))}d" ) return "\n".join(lines) + "\n" def summary( attachments: Mapping[str, str], upstream: Upstream | None ) -> dict[str, Any]: """The plan in a few numbers, for an Approval and for the Execution's record.""" packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) if problems or not activities: return {} terms = delivery_terms(upstream) plan = schedule(activities, terms["team_size"]) total = max(item.finish for item in plan.values()) weeks = round(total / terms["week"], 1) return { "work_packages": len(packages), "activities": len(activities), "working_days": round(total, 1), "weeks": weeks, "team_size": terms["team_size"], "window_weeks": terms["window_weeks"], "within_window": None if terms["window_weeks"] is None else weeks <= terms["window_weeks"], "critical_path": [i for i, item in plan.items() if item.critical], }