"""The Target architecture: one explicit graph, established before code (ADR-0005). Elements every component and the resource that realises it Relationships how Elements connect Checks the numbered, verifiable conditions each must meet, each traced to the requirement or design recommendation it comes from This module is pure: it parses the graph, states what is wrong with it, renders it as a diagram and as tables a person can review, and says whether the Requirements chain through it is complete. """ from __future__ import annotations import json import re from collections.abc import Iterable, Mapping, Sequence from dataclasses import dataclass from typing import Any GRAPH_ATTACHMENT = "target-architecture.json" DIAGRAM_ATTACHMENT = "architecture.mmd" @dataclass(frozen=True) class Element: id: str name: str product: str resource_type: str component: str | None = None # None for a supporting Element, e.g. an identity @dataclass(frozen=True) class Relationship: id: str source: str # "from" in the data target: str # "to" in the data kind: str @dataclass(frozen=True) class Check: id: str applies_to: str # an Element or Relationship id statement: str source: str # a requirement or design recommendation id @dataclass(frozen=True) class NotApplicable: recommendation: str reason: str @dataclass(frozen=True) class TargetArchitecture: elements: tuple[Element, ...] relationships: tuple[Relationship, ...] checks: tuple[Check, ...] not_applicable: tuple[NotApplicable, ...] = () @property def check_ids(self) -> tuple[str, ...]: return tuple(check.id for check in self.checks) def summary(self) -> dict[str, Any]: """What a user approving the design is told about the graph.""" return { "elements": len(self.elements), "relationships": len(self.relationships), "checks": len(self.checks), "not_applicable": [ {"recommendation": item.recommendation, "reason": item.reason} for item in self.not_applicable ], } class GraphError(ValueError): """The graph is not well-formed; `problems` says how, one entry per fault.""" def __init__(self, problems: Sequence[str]) -> None: super().__init__("; ".join(problems)) self.problems = tuple(problems) def parse_graph(text: str) -> TargetArchitecture: """Parse target-architecture.json, or raise GraphError naming every fault.""" name = GRAPH_ATTACHMENT try: data = json.loads(text) except ValueError as exc: raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc if not isinstance(data, dict): raise GraphError( [f"{name}: must be an object with elements, relationships and checks"] ) problems: list[str] = [] def items(key: str, required: Sequence[str]) -> list[dict[str, str]]: raw = data.get(key, []) if not isinstance(raw, list): problems.append(f"{name}.{key}: must be a list") return [] accepted = [] for index, item in enumerate(raw): where = f"{name}.{key}[{index}]" if not isinstance(item, dict): problems.append(f"{where}: must be an object") continue missing = [ field for field in required if not isinstance(item.get(field), str) or not item[field].strip() ] if missing: problems.append(f"{where}: needs a non-empty {', '.join(missing)}") continue accepted.append(item) return accepted elements = tuple( Element( id=item["id"], name=item["name"], product=item["product"], resource_type=item["resource_type"], component=item.get("component") or None, ) for item in items("elements", ("id", "name", "product", "resource_type")) ) relationships = tuple( Relationship(item["id"], item["from"], item["to"], item["kind"]) for item in items("relationships", ("id", "from", "to", "kind")) ) checks = tuple( Check(item["id"], item["applies_to"], item["statement"], item["source"]) for item in items("checks", ("id", "applies_to", "statement", "source")) ) not_applicable = tuple( NotApplicable(item["recommendation"], item["reason"]) for item in items("not_applicable", ("recommendation", "reason")) ) if not elements and not problems: problems.append(f"{name}.elements: the graph has no Elements") seen: set[str] = set() ids = [thing.id for group in (elements, relationships, checks) for thing in group] for identifier in ids: if identifier in seen: problems.append(f"{name}: id {identifier} is used more than once") seen.add(identifier) element_ids = {element.id for element in elements} for relationship in relationships: for end, value in (("from", relationship.source), ("to", relationship.target)): if value not in element_ids: problems.append( f"{name}: Relationship {relationship.id} {end} {value}, " "which is not an Element" ) targets = element_ids | {relationship.id for relationship in relationships} for check in checks: if check.applies_to not in targets: problems.append( f"{name}: Check {check.id} applies to {check.applies_to}, " "which is not an Element or Relationship" ) checked = {check.applies_to for check in checks} for element in elements: if element.id not in checked: problems.append(f"{name}: Element {element.id} has no Check") if problems: raise GraphError(problems) return TargetArchitecture(elements, relationships, checks, not_applicable) # --- the Requirements chain through the graph ---------------------------------------- def chain_gaps( graph: TargetArchitecture, *, requirements: Sequence[Mapping[str, Any]], components: Sequence[Mapping[str, Any]], products: Sequence[Mapping[str, Any]], recommendations: Sequence[Mapping[str, Any]], ) -> tuple[str, ...]: """Every place the Requirements chain stops before reaching a Check. A functional requirement is carried by a component that has an Element, or by a Check of its own. A non-functional requirement and a design recommendation are each a constraint, so each must be the source of a Check (a recommendation may instead be marked not applicable, with a reason). A constraint that lists nothing infrastructure code can show, only what lies outside it, needs none. """ gaps: list[str] = [] requirement_ids = {item["id"] for item in requirements} recommendation_ids = {item["id"] for item in recommendations} sources = {check.source for check in graph.checks} realised = {element.component for element in graph.elements if element.component} for check in graph.checks: if check.source not in requirement_ids | recommendation_ids: gaps.append( f"Check {check.id} has source {check.source}, which is not a " "requirement or design recommendation" ) for element in graph.elements: if element.component and element.component not in {c["id"] for c in components}: gaps.append( f"Element {element.id} realises {element.component}, " "which is not a component" ) for component in components: if component["id"] not in realised: gaps.append(f"Component {component['id']} has no Element") for requirement in requirements: if requirement["id"] in sources: continue served = any( requirement["id"] in component.get("requirements", ()) and component["id"] in realised for component in components ) if requirement.get("kind") == "functional" and served: continue if _only_outside_code(requirement): continue gaps.append(f"Requirement {requirement['id']} has no Check") for selection in products: used = any( element.component == selection["component"] and element.product == selection["product"] for element in graph.elements ) if not used: gaps.append( f"Product {selection['product']} selected for " f"{selection['component']} appears on no Element" ) excused = {item.recommendation for item in graph.not_applicable} for item in graph.not_applicable: if item.recommendation not in recommendation_ids: gaps.append( f"not_applicable names {item.recommendation}, " "which is not a design recommendation" ) for recommendation in recommendations: if recommendation["id"] not in sources | excused and not _only_outside_code( recommendation ): gaps.append(f"Recommendation {recommendation['id']} has no Check") return tuple(gaps) def _only_outside_code(item: Mapping[str, Any]) -> bool: """Whether a constraint says, explicitly, that nothing it asks for can be shown by infrastructure code.""" return item.get("conditions") == [] and bool(item.get("outside_code")) # --- the diagram is a view of the graph ---------------------------------------------- _UNSAFE = re.compile(r'["\[\]{}()<>|`#;]') def _label(*parts: str) -> str: return "
".join(_UNSAFE.sub(" ", part).strip() for part in parts if part) def _node_ids(ids: Iterable[str]) -> dict[str, str]: """Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects.""" return {identifier: f"n{index}" for index, identifier in enumerate(ids)} def render_mermaid(graph: TargetArchitecture) -> str: """The architecture diagram: every Element and Relationship, exactly once.""" nodes = _node_ids(element.id for element in graph.elements) lines = ["flowchart LR"] for element in graph.elements: lines.append( f' {nodes[element.id]}["{_label(element.name, element.product)}"]' ) for relationship in graph.relationships: lines.append( f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| " f"{nodes[relationship.target]}" ) return "\n".join(lines) + "\n" # --- so are the tables a person reviews ---------------------------------------------- def _cell(text: str | None) -> str: return " ".join((text or "").replace("|", "\\|").split()) def _table( heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]] ) -> str: lines = [ f"## {heading}", "", "| " + " | ".join(columns) + " |", "|" + "|".join(" --- " for _ in columns) + "|", ] lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows] return "\n".join(lines) def render_tables(graph: TargetArchitecture) -> str: """The graph as markdown tables: what a person approving the design reads. Written by code, so the tables cannot disagree with the graph and no model spends output repeating it. """ names = {element.id: element.name for element in graph.elements} parts = [ _table( "Elements", ("Id", "Name", "Product", "Resource type", "Component"), ( (e.id, e.name, e.product, e.resource_type, e.component) for e in graph.elements ), ), _table( "Relationships", ("Id", "From", "Kind", "To"), ( (r.id, names[r.source], r.kind, names[r.target]) for r in graph.relationships ), ), _table( "Checks", ("Id", "Applies to", "Statement", "Source"), ((c.id, c.applies_to, c.statement, c.source) for c in graph.checks), ), ] if graph.not_applicable: parts.append( _table( "Not applicable", ("Recommendation", "Reason"), ((n.recommendation, n.reason) for n in graph.not_applicable), ) ) return "\n\n".join(parts) + "\n"