"""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.solution_architecture.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" SCOPE_FILE = "scope.yaml" # the completed scope spec SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it 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. An entry a Change request marked removed is left out: it stays in the file as the record of what was dropped, and asks nothing of what follows. """ 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) and item.get("change") != "removed" ] 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 () OUTSIDE_CODE = "outside_code" def outside_code_of(item: Mapping[str, Any]) -> tuple[str, ...]: """What a requirement asks for that infrastructure code cannot show: an outcome measured in operation, application behaviour, or a process people follow.""" listed = item.get(OUTSIDE_CODE) if not isinstance(listed, list): return () return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip()) 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: under `conditions` what infrastructure code can show, under `outside_code` what it cannot. At least one of the two has an entry.""" problems = [] for item in items: listed = item.get("conditions") outside = item.get(OUTSIDE_CODE, []) well_formed = all( isinstance(group, list) and all(isinstance(c, str) and c.strip() for c in group) for group in (listed, outside) ) if not well_formed or not (listed or outside): problems.append( f"{name}: {item['id']} needs `conditions`: a list with one entry " "for each separate thing it asks for that infrastructure code can " f"show (and `{OUTSIDE_CODE}` for what it cannot)" ) 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 ) problems += _carries_the_scope(items, name, upstream) return problems def agreed_scope(upstream: Upstream | None) -> dict[str, Any]: """The agreed scope, as every Specialist reads it; empty when there is none.""" text = ( ((upstream or {}).get("scope") or {}) .get("attachments", {}) .get(SCOPE_DATA_FILE, "") ) try: data = json.loads(text) if text else {} except ValueError: return {} return data if isinstance(data, dict) else {} def sources_of(item: Mapping[str, Any]) -> tuple[str, ...]: """What a requirement comes from: the customer's own requirement ids and the scope spec's fields, as its `from` lists them.""" listed = item.get("from") return tuple(str(s) for s in listed) if isinstance(listed, list) else () def _carries_the_scope( items: Sequence[Mapping[str, Any]], name: str, upstream: Upstream | None ) -> list[str]: """What the customer stated has to reach the requirements, by name (ADR-0008). Each requirement the customer wrote, and each choice they stated that a design must honour, is named in the `from` of a requirement. A choice is carried by a non-functional requirement with a condition, so the Target architecture owes it a Check. Before this a stated topology could be named in a design and not built: case 08 on 2026-10-11 passed all 101 Checks with no Check asking for it. """ scope = agreed_scope(upstream) if not scope: return [] stated = scope.get("stated") or {} theirs = [ str(entry.get("id")) for entry in ((stated.get("intent") or {}).get("requirements") or []) if isinstance(entry, Mapping) and entry.get("id") ] binding = [str(path) for path in scope.get("binding") or []] cited = {source for item in items for source in sources_of(item)} problems = [ f"{name}: the customer's requirement {reference} is covered by no " "requirement; name it in the `from` of the one that covers it" for reference in theirs if reference not in cited ] problems += [ f"{name}: the customer stated {path} and no requirement carries it; add a " f"non-functional requirement whose `from` names {path}, with the condition " "that shows it was honoured" for path in binding if path not in cited ] for item in items: carried = [source for source in sources_of(item) if source in binding] if carried and ( item.get("kind") != "non_functional" or not conditions_of_listed(item) ): problems.append( f"{name}: {item.get('id')} carries {', '.join(carried)}, a choice " "the customer stated; it must be non_functional with at least one " "entry in `conditions`, so the design is checked against it" ) return problems def conditions_of_listed(item: Mapping[str, Any]) -> tuple[str, ...]: """The conditions a requirement lists outright, with no fallback to its text.""" listed = item.get("conditions") if not isinstance(listed, list): return () return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip()) 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_scope(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]: """The scope a Specialist reads: what the customer stated, what was left to the agent, and what is unknown.""" name = SCOPE_DATA_FILE try: data = json.loads(attachments[name]) except ValueError as exc: return [f"{name}: not valid JSON ({exc})"] if not isinstance(data, dict) or not isinstance(data.get("stated"), dict): return [f"{name}: must be an object with what the customer stated"] return [] 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) ], }