"""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)