199 lines
6.6 KiB
Python
199 lines
6.6 KiB
Python
"""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)
|