Files
orchestration_engine/execution_engine/workflows/deliverables.py

153 lines
6.0 KiB
Python

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