This commit is contained in:
198
app/workflows/deliverables.py
Normal file
198
app/workflows/deliverables.py
Normal file
@@ -0,0 +1,198 @@
|
||||
"""The dependency graph of Deliverables, grouped into Phases.
|
||||
|
||||
This is the only place Phases, Deliverables and Dependencies are declared. Section
|
||||
names are provider-neutral; they match the numbered headings of a Cloud provider's
|
||||
solution-guide template by suffix (e.g. "Products and features mapping" matches
|
||||
"4.1. Google Cloud products and features mapping").
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass
|
||||
from enum import StrEnum
|
||||
|
||||
|
||||
class PhaseId(StrEnum):
|
||||
REQUIREMENTS_DISCOVERY = "requirements_discovery"
|
||||
SOLUTION_ARCHITECTURE = "solution_architecture"
|
||||
SOLUTION_VALIDATION = "solution_validation"
|
||||
PACKAGING = "packaging"
|
||||
|
||||
|
||||
PHASE_ORDER: tuple[PhaseId, ...] = tuple(PhaseId)
|
||||
|
||||
|
||||
class DeliverableKind(StrEnum):
|
||||
REQUIREMENTS = "requirements"
|
||||
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
||||
PRODUCT_SELECTION = "product_selection"
|
||||
ARCHITECTURE_DIAGRAM = "architecture_diagram"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
||||
DEPLOYMENT_GUIDANCE = "deployment_guidance"
|
||||
VALIDATION_RESULTS = "validation_results"
|
||||
SOLUTION_GUIDE = "solution_guide"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class DeliverableSpec:
|
||||
kind: DeliverableKind
|
||||
phase: PhaseId
|
||||
specialist: str
|
||||
depends_on: tuple[DeliverableKind, ...] = ()
|
||||
sections: tuple[str, ...] = ()
|
||||
attachments: tuple[str, ...] = ()
|
||||
|
||||
|
||||
_K = DeliverableKind
|
||||
|
||||
DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
spec.kind: spec
|
||||
for spec in (
|
||||
DeliverableSpec(
|
||||
_K.REQUIREMENTS,
|
||||
PhaseId.REQUIREMENTS_DISCOVERY,
|
||||
"requirements-analyst",
|
||||
sections=(
|
||||
"Functional requirements",
|
||||
"Non-functional requirements",
|
||||
"Current state",
|
||||
"Dependencies",
|
||||
),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.TECHNICAL_DECOMPOSITION,
|
||||
PhaseId.REQUIREMENTS_DISCOVERY,
|
||||
"decomposer",
|
||||
depends_on=(_K.REQUIREMENTS,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.PRODUCT_SELECTION,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"product-selector",
|
||||
depends_on=(_K.TECHNICAL_DECOMPOSITION,),
|
||||
sections=("Products and features mapping",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DIAGRAM,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"diagrammer",
|
||||
depends_on=(_K.PRODUCT_SELECTION,),
|
||||
attachments=("architecture.mmd",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DESCRIPTION,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"describer",
|
||||
depends_on=(_K.ARCHITECTURE_DIAGRAM, _K.PRODUCT_SELECTION),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DESIGN_RECOMMENDATIONS,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"design-advisor",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.REQUIREMENTS),
|
||||
sections=(
|
||||
"Security, privacy, and compliance",
|
||||
"Reliability",
|
||||
"Operational excellence",
|
||||
"Cost optimization",
|
||||
"Performance efficiency",
|
||||
"Sustainability",
|
||||
),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DEPLOYMENT_GUIDANCE,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"iac-author",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
|
||||
sections=(
|
||||
"Deployment prerequisites",
|
||||
"Step-by-step deployment instructions",
|
||||
),
|
||||
attachments=("terraform/main.tf", "terraform/variables.tf"),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.VALIDATION_RESULTS,
|
||||
PhaseId.SOLUTION_VALIDATION,
|
||||
"validator",
|
||||
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
|
||||
sections=("Deployment dry-run", "Architecture and policy analysis"),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.SOLUTION_GUIDE,
|
||||
PhaseId.PACKAGING,
|
||||
"packager",
|
||||
depends_on=(_K.VALIDATION_RESULTS,),
|
||||
sections=(
|
||||
"Executive summary and workload overview",
|
||||
"Requirements and current state",
|
||||
"Technical decomposition of the workload",
|
||||
"Proposed solution architecture",
|
||||
"Design and configuration recommendations",
|
||||
"Deployment guidance",
|
||||
"Validation plan",
|
||||
"References",
|
||||
),
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
|
||||
"""The Deliverables a Specialist works from, in graph order.
|
||||
|
||||
Every Deliverable in an earlier Phase (all approved by the time `kind` is ready),
|
||||
plus everything `kind` depends on, directly or not, within its own Phase.
|
||||
"""
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
earlier_phases = PHASE_ORDER[: PHASE_ORDER.index(spec.phase)]
|
||||
upstream: set[DeliverableKind] = set()
|
||||
frontier = set(DEPENDENCY_GRAPH[kind].depends_on)
|
||||
while frontier:
|
||||
upstream |= frontier
|
||||
frontier = {
|
||||
dependency
|
||||
for item in frontier
|
||||
for dependency in DEPENDENCY_GRAPH[item].depends_on
|
||||
} - upstream
|
||||
return tuple(
|
||||
candidate
|
||||
for candidate, candidate_spec in DEPENDENCY_GRAPH.items()
|
||||
if candidate in upstream or candidate_spec.phase in earlier_phases
|
||||
)
|
||||
|
||||
|
||||
def deliverables_in(phase: PhaseId) -> tuple[DeliverableKind, ...]:
|
||||
return tuple(kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase)
|
||||
|
||||
|
||||
_HEADING = re.compile(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)
|
||||
_NUMBERING = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
|
||||
_TRAILING = re.compile(r"[\s:.\-–—]+$")
|
||||
|
||||
|
||||
def _normalise(text: str) -> str:
|
||||
text = _NUMBERING.sub("", text.strip().lower())
|
||||
return " ".join(_TRAILING.sub("", text).split())
|
||||
|
||||
|
||||
def check_submission(
|
||||
kind: DeliverableKind, content: str, attachments: Mapping[str, str]
|
||||
) -> tuple[str, ...]:
|
||||
"""Return what a submission lacks against its contract; empty means it's complete."""
|
||||
if not content.strip():
|
||||
return ("content: must not be empty",)
|
||||
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
headings = [_normalise(match) for match in _HEADING.findall(content)]
|
||||
missing = []
|
||||
for section in spec.sections:
|
||||
required = _normalise(section)
|
||||
if not any(h == required or h.endswith(" " + required) for h in headings):
|
||||
missing.append(f"section: {section}")
|
||||
for name in spec.attachments:
|
||||
if name not in attachments:
|
||||
missing.append(f"attachment: {name}")
|
||||
return tuple(missing)
|
||||
Reference in New Issue
Block a user