"""What a Workflow says about one Deliverable, and what follows from a graph of them. The engine declares no Phase and no Deliverable. A Workflow does (ADR-0001), and these functions read whatever graph it gives. Kinds and Phase ids are strings; a Workflow may write them as a StrEnum of its own. """ from __future__ import annotations import re from collections.abc import Callable, Mapping, Sequence from dataclasses import dataclass from typing import Any # The Deliverables a submission builds on, by kind: {kind: {content, attachments}}. Upstream = Mapping[str, Mapping[str, Any]] # What is wrong with a data file, one entry per fault; empty when nothing is. DataCheck = Callable[[Mapping[str, str], Upstream | None], list[str]] # The same, for a Change request: the attachments against the Baseline's version. BaselineCheck = Callable[[Mapping[str, str], Mapping[str, object]], list[str]] @dataclass(frozen=True) class ListShape: """One list of a working graph: what each of its items must and may hold.""" required: tuple[str, ...] optional: tuple[str, ...] = () key: str = "id" # the field that identifies an item # How the list is named when the graph's size is reported; None leaves it out. label: str | None = None @dataclass(frozen=True) class GraphShape: """A Deliverable that is a graph: built a few items at a time, attached as one file.""" attachment: str lists: Mapping[str, ListShape] @dataclass(frozen=True) class DeliverableSpec: kind: str phase: str specialist: str depends_on: tuple[str, ...] = () 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 # chain runs through, without the prose written around them. reads_in_full: tuple[str, ...] | 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: str | None = None # What the Deliverable is written from, as one comparable value. When a Revision # upstream leaves that value as it was, the last submission still stands and the # Specialist is not run again. written_from: Callable[[Upstream | None], str | None] | None = None # Earlier Deliverables this Specialist is not shown. They are still held for # the checks its submission is put through, and it can read any of them on # request. What a Specialist is given at the start is sent again with every # request it makes, so what it does not use is paid for many times over. not_shown: tuple[str, ...] = () # Set when the Deliverable's data file is a graph the Specialist builds in its # working copy; the engine then gives it the tools to do so. graph: GraphShape | 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), } Graph = Mapping[str, DeliverableSpec] def deliverables_in(graph: Graph, phase: str) -> tuple[str, ...]: return tuple(kind for kind, spec in graph.items() if spec.phase == phase) def inputs_of(graph: Graph, phases: Sequence[str], kind: str) -> tuple[str, ...]: """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 = graph[kind] earlier_phases = phases[: list(phases).index(spec.phase)] upstream: set[str] = set() frontier = set(spec.depends_on) while frontier: upstream |= frontier frontier = { dependency for item in frontier for dependency in graph[item].depends_on } - upstream return tuple( candidate for candidate, candidate_spec in graph.items() if candidate in upstream or candidate_spec.phase in earlier_phases ) def dependents_of(graph: Graph, kind: str) -> tuple[str, ...]: """Every Deliverable that depends on `kind`, directly or not, in graph order.""" dependents: set[str] = set() frontier = {kind} while frontier: frontier = { candidate for candidate, spec in graph.items() if candidate not in dependents and frontier & set(spec.depends_on) } dependents |= frontier return tuple(candidate for candidate in graph if candidate in dependents) _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 missing_from( spec: DeliverableSpec, content: str, attachments: Mapping[str, str] ) -> list[str]: """The sections and attachments of its contract a submission lacks. A section matches a heading by suffix, so a template that numbers and prefixes its headings ("4.1. Google Cloud products and features mapping") still matches the section a Workflow names ("Products and features mapping"). """ 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") return missing