Files
gcp_solution_architecture_a…/app/workflows/chain.py
Jonathan Boniface 5bb22d984e
Some checks failed
validation / verify (push) Failing after 8s
fixed multile issues
2026-10-07 17:33:36 +01:00

368 lines
12 KiB
Python

"""The data files along the Requirements chain, and what each must hold (ADR-0005).
requirements.json requirements with ids
components.json components, and the requirements each serves
products.json the product selected for each component
recommendations.json design recommendations with ids
target-architecture.json the graph (see target_architecture.py)
implementation.json which code satisfies each Check
verdicts.json the validation verdict on each Check
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
and submit again. `upstream` is the Deliverables a submission builds on, by kind; a
link to one of them is checked only when it is there.
"""
from __future__ import annotations
import json
from collections.abc import Mapping, Sequence
from typing import Any
from app.workflows.target_architecture import (
GRAPH_ATTACHMENT,
GraphError,
TargetArchitecture,
chain_gaps,
parse_graph,
)
REQUIREMENTS_FILE = "requirements.json"
COMPONENTS_FILE = "components.json"
PRODUCTS_FILE = "products.json"
RECOMMENDATIONS_FILE = "recommendations.json"
IMPLEMENTATION_FILE = "implementation.json"
VERDICTS_FILE = "verdicts.json"
REQUIREMENT_KINDS = ("functional", "non_functional")
VERDICTS = ("pass", "fail", "not_verifiable")
DRY_RUN_VERDICTS = ("pass", "fail", "not_run")
Upstream = Mapping[str, Mapping[str, Any]]
def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
"""An upstream data file as a list of objects; empty when absent or unreadable."""
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
try:
data = json.loads(text)
except ValueError:
return []
return (
[item for item in data if isinstance(item, dict)]
if isinstance(data, list)
else []
)
def read_graph(upstream: Upstream | None) -> TargetArchitecture | None:
text = (
((upstream or {}).get("target_architecture") or {})
.get("attachments", {})
.get(GRAPH_ATTACHMENT, "")
)
try:
return parse_graph(text)
except GraphError:
return None
def _objects(
text: str, name: str, strings: Sequence[str], lists: Sequence[str] = ()
) -> tuple[list[dict[str, Any]], list[str]]:
"""The file's objects that have every required field, and what is wrong with it."""
try:
data = json.loads(text)
except ValueError as exc:
return [], [f"{name}: not valid JSON ({exc})"]
if not isinstance(data, list):
return [], [f"{name}: must be a JSON list"]
accepted, problems = [], []
for index, item in enumerate(data):
where = f"{name}[{index}]"
if not isinstance(item, dict):
problems.append(f"{where}: must be an object")
continue
missing = [
field
for field in strings
if not isinstance(item.get(field), str) or not item[field].strip()
]
missing += [
field
for field in lists
if not isinstance(item.get(field), list)
or not all(isinstance(value, str) for value in item[field])
]
if missing:
problems.append(f"{where}: needs {', '.join(missing)}")
continue
accepted.append(item)
return accepted, problems
def _repeated(
items: Sequence[Mapping[str, Any]], name: str, key: str = "id"
) -> list[str]:
seen: set[str] = set()
problems = []
for item in items:
if item[key] in seen:
problems.append(f"{name}: {key} {item[key]} is used more than once")
seen.add(item[key])
return problems
def check_requirements(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = REQUIREMENTS_FILE
items, problems = _objects(attachments[name], name, ("id", "kind", "text"))
problems += _repeated(items, name)
problems += [
f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}"
for item in items
if item["kind"] not in REQUIREMENT_KINDS
]
if not items and not problems:
problems.append(f"{name}: lists no requirements")
return problems
def check_components(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = COMPONENTS_FILE
items, problems = _objects(
attachments[name], name, ("id", "name"), ("requirements",)
)
problems += _repeated(items, name)
if not items and not problems:
problems.append(f"{name}: lists no components")
requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE)
if requirements:
known = {item["id"] for item in requirements}
served: set[str] = set()
for item in items:
served.update(item["requirements"])
problems += [
f"{name}: {item['id']} serves {reference}, which is not a requirement"
for reference in item["requirements"]
if reference not in known
]
problems += [
f"{name}: functional requirement {item['id']} is served by no component"
for item in requirements
if item.get("kind") == "functional" and item["id"] not in served
]
return problems
def check_products(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = PRODUCTS_FILE
items, problems = _objects(attachments[name], name, ("component", "product"))
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
if components:
known = {item["id"] for item in components}
chosen = {item["component"] for item in items}
problems += [
f"{name}: {item['component']} is not a component"
for item in items
if item["component"] not in known
]
problems += [
f"{name}: component {identifier} has no product selected"
for identifier in sorted(known - chosen)
]
return problems
def check_recommendations(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = RECOMMENDATIONS_FILE
items, problems = _objects(
attachments[name], name, ("id", "pillar", "text"), ("components",)
)
problems += _repeated(items, name)
if not items and not problems:
problems.append(f"{name}: lists no recommendations")
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
if components:
known = {item["id"] for item in components}
problems += [
f"{name}: {item['id']} names {reference}, which is not a component"
for item in items
for reference in item["components"]
if reference not in known
]
return problems
def check_target_architecture(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
try:
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
except GraphError as exc:
return list(exc.problems)
if upstream is None:
return []
return list(
chain_gaps(
graph,
requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE),
components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE),
products=read_list(upstream, "product_selection", PRODUCTS_FILE),
recommendations=read_list(
upstream, "design_recommendations", RECOMMENDATIONS_FILE
),
)
)
def _covers_every_check(
items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None
) -> list[str]:
problems = _repeated(items, name, "check")
if graph is None:
return problems
given = {item["check"] for item in items}
problems += [
f"{name}: {identifier} is not a Check in the Target architecture"
for identifier in sorted(given - set(graph.check_ids))
]
problems += [
f"{name}: Check {identifier} is not accounted for"
for identifier in graph.check_ids
if identifier not in given
]
return problems
def _split_implementation(text: str, name: str) -> tuple[str, str]:
"""The entries that say where a Check is met, and those that say it cannot be."""
try:
data = json.loads(text)
except ValueError:
return text, "[]"
if not isinstance(data, list):
return text, "[]"
cannot = [
item for item in data if isinstance(item, dict) and "unimplementable" in item
]
met = [item for item in data if item not in cannot]
return json.dumps(met), json.dumps(cannot)
def check_implementation(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = IMPLEMENTATION_FILE
met_text, cannot_text = _split_implementation(attachments[name], name)
met, problems = _objects(met_text, name, ("check", "file", "address"))
cannot, faults = _objects(cannot_text, name, ("check", "unimplementable"))
problems += faults
problems += _covers_every_check([*met, *cannot], name, read_graph(upstream))
problems += [
f"{name}: {item['check']} names {item['file']}, which is not attached"
for item in met
if item["file"] not in attachments
]
return problems
def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]:
"""The Checks the code's author found cannot be met as written, with the reason.
Each is a fault in the Target architecture, not in the code: the Check names
something the resource does not have.
"""
_, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE)
cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable"))
return [
{"check": item["check"], "reason": item["unimplementable"]} for item in cannot
]
def check_verdicts(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = VERDICTS_FILE
try:
data = json.loads(attachments[name])
except ValueError as exc:
return [f"{name}: not valid JSON ({exc})"]
if not isinstance(data, dict):
return [
f"{name}: must be an object with dry_run, checks and proposed_additions"
]
problems: list[str] = []
dry_run = data.get("dry_run")
if (
not isinstance(dry_run, dict)
or dry_run.get("verdict") not in DRY_RUN_VERDICTS
or not isinstance(dry_run.get("evidence"), str)
or not dry_run["evidence"].strip()
):
problems.append(
f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence"
)
items, faults = _objects(
json.dumps(data.get("checks", [])),
f"{name}.checks",
("check", "verdict", "evidence"),
)
problems += faults
problems += [
f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}"
for item in items
if item["verdict"] not in VERDICTS
]
problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream))
_, faults = _objects(
json.dumps(data.get("proposed_additions", [])),
f"{name}.proposed_additions",
("statement", "applies_to", "reason"),
)
return problems + faults
def validation_outcome(verdicts_text: str) -> dict[str, Any]:
"""What a validation decided, for routing a Revision and for scoring.
Failed Checks are faults in the code. A Check that could not be verified and a
proposed addition are gaps in the Target architecture.
"""
try:
data = json.loads(verdicts_text)
except ValueError:
data = {}
if not isinstance(data, dict):
data = {}
checks = [item for item in data.get("checks", []) if isinstance(item, dict)]
def with_verdict(verdict: str) -> list[dict[str, Any]]:
return [
{"check": item.get("check"), "evidence": item.get("evidence")}
for item in checks
if item.get("verdict") == verdict
]
dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {}
return {
"dry_run": dry_run,
"passed": [
item.get("check") for item in checks if item.get("verdict") == "pass"
],
"failed": with_verdict("fail"),
"not_verifiable": with_verdict("not_verifiable"),
"proposed_additions": [
item
for item in data.get("proposed_additions", [])
if isinstance(item, dict)
],
}