"""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 Callable, Mapping from dataclasses import dataclass from enum import StrEnum from app.workflows.chain import ( COMPONENTS_FILE, IMPLEMENTATION_FILE, PRODUCTS_FILE, RECOMMENDATIONS_FILE, REQUIREMENTS_FILE, VERDICTS_FILE, Upstream, check_components, check_implementation, check_products, check_recommendations, check_requirements, check_target_architecture, check_verdicts, ) from app.workflows.target_architecture import GRAPH_ATTACHMENT class PhaseId(StrEnum): REQUIREMENTS_DISCOVERY = "requirements_discovery" # Design: ends with the Target architecture, approved before any code is written. SOLUTION_ARCHITECTURE = "solution_architecture" SOLUTION_IMPLEMENTATION = "solution_implementation" 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" DESIGN_RECOMMENDATIONS = "design_recommendations" TARGET_ARCHITECTURE = "target_architecture" ARCHITECTURE_DESCRIPTION = "architecture_description" 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, ...] = () # Which earlier Deliverables the Specialist reads whole. None means the ones it # depends on. Every other input arrives as its data file alone: the ids the # Requirements chain runs through, without the prose written around them. reads_in_full: tuple[DeliverableKind, ...] | None = None # The Deliverable whose files this Specialist's tools work on. Its own kind: the # files are its working copy, kept across attempts and attached on submission. # Another kind: a fresh copy of that Deliverable's files on every attempt. working_copy: DeliverableKind | None = None def contract(self) -> dict[str, list[str]]: """What a submission must contain, as plain data for the Specialist's context.""" return { "sections": list(self.sections), "attachments": list(self.attachments), } _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", ), attachments=(REQUIREMENTS_FILE,), ), DeliverableSpec( _K.TECHNICAL_DECOMPOSITION, PhaseId.REQUIREMENTS_DISCOVERY, "decomposer", depends_on=(_K.REQUIREMENTS,), sections=("Components",), attachments=(COMPONENTS_FILE,), ), DeliverableSpec( _K.PRODUCT_SELECTION, PhaseId.SOLUTION_ARCHITECTURE, "product-selector", depends_on=(_K.TECHNICAL_DECOMPOSITION,), sections=("Products and features mapping",), attachments=(PRODUCTS_FILE,), ), 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", ), attachments=(RECOMMENDATIONS_FILE,), ), DeliverableSpec( _K.TARGET_ARCHITECTURE, PhaseId.SOLUTION_ARCHITECTURE, "target-architect", depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS), # The Specialist writes the reasoning and the graph. On submission the # engine adds the Elements, Relationships and Checks tables to the content # and architecture.mmd to the attachments, both rendered from the graph. sections=("Design rationale",), attachments=(GRAPH_ATTACHMENT,), ), DeliverableSpec( _K.ARCHITECTURE_DESCRIPTION, PhaseId.SOLUTION_IMPLEMENTATION, "describer", depends_on=(_K.TARGET_ARCHITECTURE,), sections=("Components", "Flow"), ), DeliverableSpec( _K.DEPLOYMENT_GUIDANCE, PhaseId.SOLUTION_IMPLEMENTATION, "iac-author", depends_on=(_K.TARGET_ARCHITECTURE,), sections=( "Deployment prerequisites", "Step-by-step deployment instructions", ), attachments=( "terraform/main.tf", "terraform/variables.tf", IMPLEMENTATION_FILE, ), # The graph is all the code is written from. reads_in_full=(), working_copy=_K.DEPLOYMENT_GUIDANCE, ), DeliverableSpec( _K.VALIDATION_RESULTS, PhaseId.SOLUTION_VALIDATION, "validator", depends_on=(_K.DEPLOYMENT_GUIDANCE,), sections=("Deployment dry-run", "Architecture and policy analysis"), attachments=(VERDICTS_FILE,), working_copy=_K.DEPLOYMENT_GUIDANCE, ), 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", ), # The guide is assembled from every Deliverable's prose. reads_in_full=tuple(_K)[:-1], ), ) } # What each data file along the Requirements chain must hold, checked at submission. DATA_CHECKS: Mapping[ DeliverableKind, tuple[str, Callable[[Mapping[str, str], Upstream | None], list[str]]], ] = { _K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements), _K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components), _K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products), _K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations), _K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture), _K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation), _K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts), } 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 dependencies_for( kind: DeliverableKind, deliverables: Mapping[str, Mapping[str, object]] ) -> dict[str, dict[str, object]]: """What a Specialist is given of each Deliverable it works from. A Deliverable read in full arrives as submitted. Any other arrives as its data file alone, which is all the Requirements chain needs of it. """ spec = DEPENDENCY_GRAPH[kind] in_full = spec.depends_on if spec.reads_in_full is None else spec.reads_in_full given: dict[str, dict[str, object]] = {} for dependency in inputs_of(kind): deliverable = deliverables[dependency.value] if dependency in in_full or dependency not in DATA_CHECKS: given[dependency.value] = dict(deliverable) continue name = DATA_CHECKS[dependency][0] attachments = deliverable.get("attachments") files = attachments if isinstance(attachments, Mapping) else {} given[dependency.value] = { "attachments": {name: files[name]} if name in files else {} } return given 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], upstream: Upstream | None = None, ) -> tuple[str, ...]: """Return what a submission lacks against its contract; empty means it's complete. `upstream` is the Deliverables this one builds on, by kind. With it, the links along the Requirements chain are checked too. """ 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}") elif not attachments[name].strip(): missing.append(f"attachment: {name} must not be empty") if kind in DATA_CHECKS: name, check = DATA_CHECKS[kind] if attachments.get(name, "").strip(): missing.extend(check(attachments, upstream)) return tuple(missing)