Files
gcp_solution_architecture_a…/app/workflows/chain.py
Jonathan Boniface 5adc911a82 feat: keep an unchanged description, list conditions, review coverage with Jev
After case 02 (completed at 100%, but with two Revisions of the Target
architecture for gaps validation found one pass at a time):

- A Deliverable stands while what it was written from is unchanged. The
  architecture description is written from the Elements and Relationships,
  so a Revision that only adds or rewords Checks no longer runs the describer.
- Non-functional requirements and recommendations list their conditions,
  one entry per separate thing that must be true; submission requires them.
- A coverage review at submission (JEV_COVERAGE_REVIEW, off by default):
  for each condition, Jev chooses which Check verifies it, or none. Asked as
  one broad yes-or-no per requirement it could not tell a complete design
  from one with known gaps; asked as a choice per condition it raised all
  four known gaps of case 02 and nothing on the complete graph. An opt-in
  live test (LIVE_JEV=1) repeats that.
- The validator is told to report every gap in its first pass.

Plans record the case 02 run and both forms of the review with figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:58:38 +01:00

429 lines
14 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 graph_structure(upstream: Upstream | None) -> str | None:
"""The Target architecture's Elements and Relationships, as one comparable value.
What a Deliverable written from the shape of the design, and not from its
Checks, was written from. None when there is no readable graph.
"""
graph = read_graph(upstream)
if graph is None:
return None
return json.dumps(
{
"elements": [
[e.id, e.name, e.product, e.resource_type, e.component]
for e in graph.elements
],
"relationships": [
[r.id, r.source, r.target, r.kind] for r in graph.relationships
],
},
sort_keys=True,
)
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 conditions_of(item: Mapping[str, Any]) -> tuple[str, ...]:
"""The separate things a requirement or recommendation asks for.
Each is one statement that a Check can verify on its own. An item written before
conditions were listed is read as one condition: its whole text.
"""
listed = item.get("conditions")
if isinstance(listed, list):
conditions = tuple(
c.strip() for c in listed if isinstance(c, str) and c.strip()
)
if conditions:
return conditions
text = item.get("text")
return (text.strip(),) if isinstance(text, str) and text.strip() else ()
def _lacking_conditions(items: Sequence[Mapping[str, Any]], name: str) -> list[str]:
"""A constraint must say, one by one, what would have to be true for it to be met."""
problems = []
for item in items:
listed = item.get("conditions")
if (
not isinstance(listed, list)
or not listed
or not all(isinstance(c, str) and c.strip() for c in listed)
):
problems.append(
f"{name}: {item['id']} needs `conditions`: a list with one entry "
"for each separate thing it asks for"
)
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")
problems += _lacking_conditions(
[item for item in items if item["kind"] == "non_functional"], name
)
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")
problems += _lacking_conditions(items, name)
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)
],
}