"""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) ], }