153 lines
6.0 KiB
Python
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
|