The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
327 lines
12 KiB
Python
327 lines
12 KiB
Python
"""What a Change request changed against its Baseline (ADR-0006).
|
|
|
|
Ids are stable from one version of a Customer case's architecture to the next: a
|
|
requirement, component, recommendation, Element, Relationship or Check that still
|
|
holds keeps its id. That is what lets code, with no model, say what was added, what
|
|
changed and what was removed; trace from each changed requirement to everything it
|
|
reaches; and list apart anything that changed without being reached. Nobody asked
|
|
for those, so a reader should see them as such.
|
|
|
|
This module is pure: data in, data out.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from collections.abc import Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from app.solution_architecture.chain import (
|
|
COMPONENTS_FILE,
|
|
RECOMMENDATIONS_FILE,
|
|
REQUIREMENTS_FILE,
|
|
)
|
|
from app.solution_architecture.target_architecture import GRAPH_ATTACHMENT
|
|
|
|
CHANGES_FILE = "changes.json"
|
|
UNCHANGED, ADDED, CHANGED, REMOVED = "unchanged", "added", "changed", "removed"
|
|
CHANGE_KINDS = (UNCHANGED, ADDED, CHANGED, REMOVED)
|
|
|
|
Deliverables = Mapping[str, Mapping[str, Any]]
|
|
|
|
|
|
def _items(deliverables: Deliverables | None, kind: str, name: str) -> list[dict]:
|
|
"""A data file as a list of objects, removed requirements included."""
|
|
text = ((deliverables 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 _graph(deliverables: Deliverables | None) -> dict[str, list[dict]]:
|
|
text = (
|
|
((deliverables or {}).get("target_architecture") or {})
|
|
.get("attachments", {})
|
|
.get(GRAPH_ATTACHMENT, "")
|
|
)
|
|
try:
|
|
data = json.loads(text)
|
|
except ValueError:
|
|
data = {}
|
|
if not isinstance(data, dict):
|
|
data = {}
|
|
return {
|
|
key: [item for item in data.get(key, []) if isinstance(item, dict)]
|
|
for key in ("elements", "relationships", "checks")
|
|
}
|
|
|
|
|
|
# --- the requirements say what changed --------------------------------------------------
|
|
|
|
|
|
def check_requirement_changes(
|
|
attachments: Mapping[str, str], baseline: Mapping[str, Any] | None
|
|
) -> list[str]:
|
|
"""What is wrong with a Change request's requirements.json against the Baseline's.
|
|
|
|
Every requirement carries a `change`. One that still holds keeps its id and is
|
|
`unchanged`, with its text as it was. One that differs is `changed`; one no
|
|
longer wanted stays in the list as `removed`; a new one takes a new id and is
|
|
`added`. Everything but `unchanged` says why.
|
|
"""
|
|
name = REQUIREMENTS_FILE
|
|
before = {
|
|
item["id"]: item
|
|
for item in _items({"requirements": baseline or {}}, "requirements", name)
|
|
if isinstance(item.get("id"), str) and item.get("change") != REMOVED
|
|
}
|
|
revised = _items(
|
|
{"requirements": {"attachments": attachments}}, "requirements", name
|
|
)
|
|
problems: list[str] = []
|
|
seen = set()
|
|
for item in revised:
|
|
identifier = item.get("id")
|
|
if not isinstance(identifier, str):
|
|
continue
|
|
seen.add(identifier)
|
|
change = item.get("change")
|
|
if change not in CHANGE_KINDS:
|
|
problems.append(
|
|
f"{name}: {identifier} needs a `change`: one of "
|
|
f"{', '.join(CHANGE_KINDS)}"
|
|
)
|
|
continue
|
|
reason = item.get("reason")
|
|
if change != UNCHANGED and not (isinstance(reason, str) and reason.strip()):
|
|
problems.append(f"{name}: {identifier} is {change} and needs a `reason`")
|
|
if change == ADDED and identifier in before:
|
|
problems.append(
|
|
f"{name}: {identifier} is marked added, but the Baseline has that "
|
|
"id; a new requirement takes a new id"
|
|
)
|
|
if change != ADDED and identifier not in before:
|
|
problems.append(
|
|
f"{name}: {identifier} is marked {change}, but the Baseline has no "
|
|
"such requirement; mark a new one added"
|
|
)
|
|
if (
|
|
change == UNCHANGED
|
|
and identifier in before
|
|
and _text(item) != _text(before[identifier])
|
|
):
|
|
problems.append(
|
|
f"{name}: {identifier} is marked unchanged, but its text differs "
|
|
"from the Baseline's; restore it or mark it changed"
|
|
)
|
|
problems += [
|
|
f"{name}: Baseline requirement {identifier} is missing; keep it, or keep it "
|
|
"marked removed with the reason"
|
|
for identifier in before
|
|
if identifier not in seen
|
|
]
|
|
if revised and all(item.get("change") == UNCHANGED for item in revised):
|
|
problems.append(
|
|
f"{name}: nothing is marked added, changed or removed; a Change request "
|
|
"changes at least one requirement"
|
|
)
|
|
return problems
|
|
|
|
|
|
def _text(item: Mapping[str, Any]) -> str:
|
|
return " ".join(str(item.get("text", "")).split())
|
|
|
|
|
|
def requirement_changes(deliverables: Deliverables | None) -> list[dict[str, str]]:
|
|
"""The requirements a Change request added, changed or removed, with the reason."""
|
|
return [
|
|
{
|
|
"id": str(item.get("id")),
|
|
"change": str(item["change"]),
|
|
"reason": str(item.get("reason", "")),
|
|
"text": str(item.get("text", "")),
|
|
}
|
|
for item in _items(deliverables, "requirements", REQUIREMENTS_FILE)
|
|
if item.get("change") in (ADDED, CHANGED, REMOVED)
|
|
]
|
|
|
|
|
|
# --- comparing two versions -------------------------------------------------------------
|
|
|
|
|
|
def _compare(
|
|
before: Sequence[Mapping[str, Any]],
|
|
after: Sequence[Mapping[str, Any]] | None,
|
|
key: str = "id",
|
|
ignore: Sequence[str] = ("change", "reason"),
|
|
) -> dict[str, list[str]]:
|
|
"""Ids added, changed and removed between two lists of objects.
|
|
|
|
`after` is None while the revised Deliverable has not been produced: nothing
|
|
has changed yet, which is not the same as everything having been removed.
|
|
"""
|
|
if after is None:
|
|
return {ADDED: [], CHANGED: [], REMOVED: []}
|
|
|
|
def body(item: Mapping[str, Any]) -> dict[str, Any]:
|
|
return {name: value for name, value in item.items() if name not in ignore}
|
|
|
|
old = {str(item.get(key)): body(item) for item in before if item.get(key)}
|
|
new = {str(item.get(key)): body(item) for item in after if item.get(key)}
|
|
return {
|
|
ADDED: [identifier for identifier in new if identifier not in old],
|
|
CHANGED: [
|
|
identifier
|
|
for identifier in new
|
|
if identifier in old and new[identifier] != old[identifier]
|
|
],
|
|
REMOVED: [identifier for identifier in old if identifier not in new],
|
|
}
|
|
|
|
|
|
def reach(
|
|
changed: Sequence[str],
|
|
components: Sequence[Mapping[str, Any]],
|
|
recommendations_changed: Sequence[str],
|
|
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
|
) -> set[str]:
|
|
"""The Elements, Relationships and Checks a set of changed requirements reaches.
|
|
|
|
A changed requirement reaches the components that serve it, the Elements that
|
|
realise those components, the Relationships at those Elements, and every Check
|
|
on any of them or with the requirement as its source. A recommendation that
|
|
changed reaches the Checks that come from it and what they apply to.
|
|
"""
|
|
sources = set(changed) | set(recommendations_changed)
|
|
served = {
|
|
str(component.get("id"))
|
|
for component in components
|
|
if set(component.get("requirements") or ()) & set(changed)
|
|
}
|
|
reached = {
|
|
str(element.get("id"))
|
|
for element in graph.get("elements", ())
|
|
if element.get("component") in served
|
|
}
|
|
for check in graph.get("checks", ()):
|
|
if check.get("source") in sources:
|
|
reached.add(str(check.get("id")))
|
|
reached.add(str(check.get("applies_to")))
|
|
reached |= {
|
|
str(relationship.get("id"))
|
|
for relationship in graph.get("relationships", ())
|
|
if relationship.get("from") in reached or relationship.get("to") in reached
|
|
}
|
|
reached |= {
|
|
str(check.get("id"))
|
|
for check in graph.get("checks", ())
|
|
if check.get("applies_to") in reached
|
|
}
|
|
return reached
|
|
|
|
|
|
def change_summary(
|
|
baseline: Deliverables | None, current: Deliverables | None
|
|
) -> dict[str, Any]:
|
|
"""What a Change request changed, as changes.json holds it.
|
|
|
|
Requirements carry their own account. Everything else is compared by id. What
|
|
changed inside the reach of the changed requirements is listed as requested;
|
|
anything else that changed is listed apart as unrequested.
|
|
"""
|
|
requirements = requirement_changes(current)
|
|
changed_ids = [item["id"] for item in requirements]
|
|
produced = current or {}
|
|
recommendations = _compare(
|
|
_items(baseline, "design_recommendations", RECOMMENDATIONS_FILE),
|
|
_items(current, "design_recommendations", RECOMMENDATIONS_FILE)
|
|
if "design_recommendations" in produced
|
|
else None,
|
|
)
|
|
components = _compare(
|
|
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
|
|
_items(current, "technical_decomposition", COMPONENTS_FILE)
|
|
if "technical_decomposition" in produced
|
|
else None,
|
|
)
|
|
old_graph, new_graph = _graph(baseline), _graph(current)
|
|
designed = "target_architecture" in produced
|
|
# Reach is traced through both versions: what a requirement used to touch can
|
|
# change or go, as well as what it touches now.
|
|
touched_recommendations = recommendations[ADDED] + recommendations[CHANGED]
|
|
reached = reach(
|
|
changed_ids,
|
|
_items(current, "technical_decomposition", COMPONENTS_FILE),
|
|
touched_recommendations,
|
|
new_graph,
|
|
) | reach(
|
|
changed_ids,
|
|
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
|
|
touched_recommendations + recommendations[REMOVED],
|
|
old_graph,
|
|
)
|
|
graph: dict[str, dict[str, list[str]]] = {}
|
|
unrequested: dict[str, list[str]] = {}
|
|
for part in ("elements", "relationships", "checks"):
|
|
compared = _compare(old_graph[part], new_graph[part] if designed else None)
|
|
graph[part] = compared
|
|
outside = [
|
|
identifier
|
|
for change in (ADDED, CHANGED, REMOVED)
|
|
for identifier in compared[change]
|
|
if identifier not in reached
|
|
]
|
|
if outside:
|
|
unrequested[part] = outside
|
|
return {
|
|
"requirements": requirements,
|
|
"components": components,
|
|
"recommendations": recommendations,
|
|
**graph,
|
|
# Changed without being reached by any changed requirement.
|
|
"unrequested": unrequested,
|
|
}
|
|
|
|
|
|
def is_empty(summary: Mapping[str, Any]) -> bool:
|
|
return not summary.get("requirements") and not any(
|
|
summary.get(part, {}).get(change)
|
|
for part in (
|
|
"components",
|
|
"recommendations",
|
|
"elements",
|
|
"relationships",
|
|
"checks",
|
|
)
|
|
for change in (ADDED, CHANGED, REMOVED)
|
|
)
|
|
|
|
|
|
# What an Approval of each kind of Deliverable shows of the change.
|
|
_SHOWN_WITH = {
|
|
"requirements": ("requirements",),
|
|
"technical_decomposition": ("components",),
|
|
"design_recommendations": ("recommendations",),
|
|
"target_architecture": ("elements", "relationships", "checks", "unrequested"),
|
|
}
|
|
|
|
|
|
def changes_for(summary: Mapping[str, Any], kinds: Sequence[str]) -> dict[str, Any]:
|
|
"""The part of a change summary that belongs to the Deliverables being approved,
|
|
with the parts that hold nothing left out."""
|
|
shown: dict[str, Any] = {}
|
|
for kind in kinds:
|
|
for part in _SHOWN_WITH.get(kind, ()):
|
|
value = summary.get(part)
|
|
if isinstance(value, Mapping):
|
|
value = {name: ids for name, ids in value.items() if ids}
|
|
if value:
|
|
shown[part] = value
|
|
return shown
|