Files
Jonathan Boniface 9e503885cc ALZ-F01 Discovery: package step, value scorecard, application grouping, cases
- New cp1-discovery-package-agent (ADR 0020): one package per reviewed run, every part
  hashed (sha256 over canonical JSON), with a manifest and a value scorecard.
- Applications grouped CMDB -> tag -> resource group with a judged model fallback (ADR 0021):
  CMDB 0.7.0 carries ownership, dependency mapping 0.6.0 groups, report 0.9.0 shows them.
- Critic 0.6.1 accepts the producers' enums; build_workflow.py refuses a consumer enum
  narrower than its producer's.
- Code hooks, sub-agents and tests for the inventory, CMDB, dependency, planner and critic
  agents; the report and Well-Architected review agents; ADRs 0012-0021.
- Workflow cases with value bars and run limits; run evaluation and usage collection scripts;
  the run context template and the field-by-field review for ADR 0016.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

488 lines
30 KiB
Python

"""The Well-Architected review: evidence collected and judged in code, rendered as Markdown and HTML (ADR 0014).
`review(payload, call)` reads the live estate through the cloud discovery server's read-only tools, applies fixed
checks per pillar, rolls up the provider's own recommendations by pillar and impact, and adds guidance references
from the provider's own discovery server. No model is involved, so every figure can be recomputed from the evidence. `call(name, args)`
is the runtime's call_tool; tests pass a stand-in. A pillar with no evidence is "not assessed", never a pass.
"""
from __future__ import annotations
import html
import re
from collections import Counter, defaultdict
from datetime import date
from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
PILLARS = ("security", "reliability", "cost", "operations", "performance", "sustainability")
TITLES = {"security": "Security", "reliability": "Reliability", "cost": "Cost optimisation",
"operations": "Operational excellence", "performance": "Performance efficiency", "sustainability": "Sustainability"}
# The provider's own discovery server accepts only these fixed topics (mcp-servers/_common/knowledge_support.py).
TOPICS = {"security": "network segmentation", "reliability": "high availability", "cost": "cost allocation",
"operations": "logging and monitoring", "performance": "scaling", "sustainability": "virtual machines"}
ADMIN_PORTS = {22, 3389, 21, 1433, 3306, 5432}
OPEN = {"0.0.0.0/0", "::/0", "*", "internet", "any"}
OWNER_KEYS = ("owner", "team", "cost-center", "cost_center", "costcenter", "environment", "env", "application", "app")
PAGE_SIZE = 200
MAX_PAGES = 40 # per call: 8,000 items is far beyond the estates seen so far, and bounds a runaway
KINDS = {
"gcp": {"servers": ("gcp_list_servers", ["instances"]), "workloads": ("gcp_list_workloads", ["cloud_run", "cloud_functions", "app_engine"]),
"clusters": ("gcp_list_kubernetes_clusters", ["clusters"]), "stores": ("gcp_list_data_stores", ["cloud_sql", "firestore", "cloud_storage"]),
"rules": ("gcp_get_network_topology", ["firewall_rules"]),
"org_policies": ("gcp_list_organization_policies", ["organization_policies"])},
"azure": {"servers": ("azure_list_servers", ["virtual_machines", "scale_sets"]),
"workloads": ("azure_list_workloads", ["app_service", "container_apps", "container_instances"]),
"clusters": ("azure_list_kubernetes_clusters", [None]),
"stores": ("azure_list_data_stores", ["sql", "cosmos_db", "storage_accounts", "postgresql", "mysql", "redis"]),
"rules": ("azure_get_network_topology", ["network_security_groups"]),
"public_ips": ("azure_get_network_topology", ["public_ips"]),
"org_policies": ("azure_list_organization_policies", ["assignments"]),
"locks": ("azure_list_resource_policies", ["resource_locks"])},
}
GCP_RECOMMENDERS = ("google.compute.instance.MachineTypeRecommender", "google.compute.instance.IdleResourceRecommender",
"google.compute.disk.IdleResourceRecommender", "google.iam.policy.Recommender")
# ---------------------------------------------------------------- evidence ----------------------------------------------
def _data(result: Any) -> Dict[str, Any]:
"""The servers' envelope, {success, data} or {success: false, error: {code, message}}; a refusal raises."""
if not isinstance(result, dict):
raise ValueError(f"unexpected reply {type(result).__name__}")
if result.get("success") is False or (result.get("error") and "data" not in result):
error = result.get("error") or {}
raise ValueError(f"{error.get('code', 'refused')}: {error.get('message', '')}"[:200] if isinstance(error, dict) else str(error)[:200])
return result.get("data") if isinstance(result.get("data"), dict) else result
def _items(result: Any) -> Tuple[List[Dict[str, Any]], Optional[str], Optional[str]]:
"""A tool reply's items, next page token and evidence reference; a refusal raises."""
data = _data(result)
return list(data.get("items") or []), data.get("next_page_token"), data.get("evidence_ref")
def _all_pages(call: Callable, tool: str, args: Dict[str, Any], issues: List[str], refs: List[str]) -> List[Dict[str, Any]]:
out, token = [], None
for _ in range(MAX_PAGES):
try:
items, token, ref = _items(call(tool, {**args, "page_size": PAGE_SIZE, **({"page_token": token} if token else {})}))
except Exception as error: # noqa: BLE001 - a refusal or failure is evidence of a gap, not a crash
issues.append(f"{tool}({', '.join(f'{k}={v}' for k, v in args.items())}): {str(error)[:160]}")
return out
out += items
if ref:
refs.append(ref)
if not token:
return out
issues.append(f"{tool}: stopped after {MAX_PAGES} pages")
return out
def _resource(item: Dict[str, Any]) -> Dict[str, Any]:
"""The provider's own resource body: GCP versionedResources[0].resource.data, or an Azure row's properties."""
versions = item.get("versionedResources") or []
if versions:
body = (versions[0] or {}).get("resource") or {}
return body.get("data") or body
return item.get("properties") or item.get("resource", {}).get("data") or {}
def _name(item: Dict[str, Any]) -> str:
return str(item.get("name") or item.get("id") or "")
def _short(name: str) -> str:
return name.rstrip("/").rsplit("/", 1)[-1]
def collect(provider: str, call: Callable, scope: Iterable[str]) -> Dict[str, Any]:
"""Every piece of evidence the checks use, with the calls that failed and the evidence references returned."""
issues: List[str] = []
refs: List[str] = []
ev: Dict[str, Any] = {}
failed = set()
for key, (tool, kinds) in KINDS[provider].items():
ev[key] = []
for kind in kinds:
before = len(issues)
ev[key] += _all_pages(call, tool, {"kind": kind} if kind else {}, issues, refs)
if len(issues) > before:
failed.add(key) # this evidence wasn't fully read: its checks say so instead of passing
scope = set(scope)
if scope: # the checks judge the scope the plan accounted for; structure and rules stay as listed
for key in ("servers", "workloads", "clusters", "stores"):
ev[key] = [i for i in ev[key] if _name(i) in scope]
if provider == "gcp":
projects = sorted({m.group(1) for n in scope for m in [re.search(r"/projects/([^/]+)", n)] if m})
zones = sorted({m.group(1) for n in scope for m in [re.search(r"/zones/([^/]+)", n)] if m})
recs = []
for project in projects:
for recommender in GCP_RECOMMENDERS:
for location in (["global"] if recommender.startswith("google.iam") else zones or ["global"]):
recs += _all_pages(call, "gcp_list_recommendations",
{"project_id": project, "recommender": recommender, "location": location}, issues, refs)
ev["recommendations"] = recs
else:
ev["recommendations"] = _all_pages(call, "azure_list_recommendations", {}, issues, refs)
ev["issues"], ev["evidence_refs"], ev["failed"] = issues, refs, failed
return ev
# ---------------------------------------------------------------- checks ------------------------------------------------
def _labels(item: Dict[str, Any]) -> Dict[str, Any]:
body = _resource(item)
return item.get("labels") or item.get("tags") or body.get("labels") or body.get("tags") or {}
def _ports(spec: Any) -> set:
out = set()
for part in re.split(r"[,\s]+", str(spec or "")):
if not part or part == "*":
out |= ADMIN_PORTS if part == "*" else set()
continue
lo, _, hi = part.partition("-")
if lo.isdigit():
out |= {p for p in ADMIN_PORTS if int(lo) <= p <= int(hi or lo)}
return out
def _exposures(provider: str, rules: List[Dict[str, Any]]) -> List[str]:
"""Inbound allow rules open to the internet on an administrative or database port."""
found = []
for item in rules:
r = _resource(item)
if provider == "gcp":
if r.get("disabled") or str(r.get("direction", "INGRESS")).upper() != "INGRESS":
continue
if not set(r.get("sourceRanges") or []) & OPEN:
continue
for allowed in r.get("allowed") or []:
proto = str(allowed.get("IPProtocol", "")).lower()
ports = set().union(*[_ports(p) for p in allowed.get("ports") or []]) if allowed.get("ports") else (
ADMIN_PORTS if proto in ("all", "tcp") else set())
if ports:
found.append(f"{_short(_name(item))}: {', '.join(str(p) for p in sorted(ports))}")
else:
for rule in r.get("securityRules") or []:
p = rule.get("properties") or rule
if str(p.get("access")).lower() != "allow" or str(p.get("direction")).lower() != "inbound":
continue
sources = {str(p.get("sourceAddressPrefix", "")).lower(), *[str(s).lower() for s in p.get("sourceAddressPrefixes") or []]}
if not sources & OPEN:
continue
ports = set().union(_ports(p.get("destinationPortRange")), *[_ports(x) for x in p.get("destinationPortRanges") or []])
if ports:
found.append(f"{_short(_name(item))}/{rule.get('name')}: {', '.join(str(x) for x in sorted(ports))}")
return found
def _check(pillar: str, cid: str, title: str, affected: Optional[List[str]], basis: str) -> Dict[str, Any]:
"""`affected` None means the evidence wasn't available; [] means checked and clean."""
result = "no_evidence" if affected is None else ("fail" if affected else "pass")
return {"pillar": pillar, "check_id": cid, "title": title, "result": result, "affected": affected or [], "basis": basis}
def checks(provider: str, ev: Dict[str, Any]) -> List[Dict[str, Any]]:
servers, stores, rules = ev.get("servers") or [], ev.get("stores") or [], ev.get("rules") or []
compute = servers + (ev.get("workloads") or []) + (ev.get("clusters") or [])
everything = compute + stores
gcp = provider == "gcp"
failed = ev.get("failed") or set()
def read(*keys): # True when every piece of evidence a check rests on was read in full
return not (set(keys) & failed)
out = []
# Security
out.append(_check("security", "SEC-01", "No administrative or database port is open to the internet",
_exposures(provider, rules) if read("rules") else None,
f"{len(rules)} firewall or NSG rule sets read"))
if gcp:
public = [_short(_name(s)) for s in servers
if any(ni.get("accessConfigs") for ni in _resource(s).get("networkInterfaces") or [])]
boot = [_short(_name(s)) for s in servers
if not (_resource(s).get("shieldedInstanceConfig") or {}).get("enableSecureBoot")]
buckets = [s for s in stores if "storage" in str(s.get("assetType", "")).lower()]
open_buckets = [_short(_name(b)) for b in buckets
if str((_resource(b).get("iamConfiguration") or {}).get("publicAccessPrevention", "")).lower() != "enforced"]
else:
public = [_short(_name(p)) for p in ev.get("public_ips") or []]
boot = [_short(_name(s)) for s in servers
if not ((_resource(s).get("securityProfile") or {}).get("uefiSettings") or {}).get("secureBootEnabled")]
buckets = [s for s in stores if "storageaccounts" in str(s.get("type", "")).lower()]
open_buckets = [_short(_name(b)) for b in buckets if _resource(b).get("allowBlobPublicAccess") is not False]
out.append(_check("security", "SEC-02", "Servers have no public address",
public if read("servers", *([] if gcp else ["public_ips"])) and (servers or not gcp) else None,
f"{len(servers)} servers read" + ("" if gcp else f", {len(ev.get('public_ips') or [])} public addresses")))
out.append(_check("security", "SEC-03", "Secure Boot is on for every server", boot if servers else None, f"{len(servers)} servers read"))
out.append(_check("security", "SEC-04", "Storage blocks public access", open_buckets if buckets else None, f"{len(buckets)} storage resources read"))
pol = ev.get("org_policies")
out.append(_check("security", "SEC-05", "Guardrail policies are set at the scope root",
(["no organisation policy or policy assignment found"] if not pol else []) if read("org_policies") else None,
f"{len(pol or [])} policies read"))
# Reliability
zones = sorted({z for s in compute for z in [_zone(s)] if z})
out.append(_check("reliability", "REL-01", "Compute isn't confined to a single zone",
([f"all compute in {zones[0]}"] if len(zones) == 1 and len(compute) > 1 else []) if compute else None,
f"zones: {', '.join(zones) or 'none recorded'}"))
if gcp:
unprotected = [_short(_name(s)) for s in servers if not _resource(s).get("deletionProtection")]
no_backup = [_short(_name(s)) for s in stores if "sqladmin" in str(s.get("assetType", "")).lower()
and not ((_resource(s).get("settings") or {}).get("backupConfiguration") or {}).get("enabled")]
sql = [s for s in stores if "sqladmin" in str(s.get("assetType", "")).lower()]
no_versioning = [_short(_name(b)) for b in buckets if not (_resource(b).get("versioning") or {}).get("enabled")]
else:
locked = {str(l.get("properties", {}).get("scope") or _name(l)).lower() for l in ev.get("locks") or []}
unprotected = [_short(_name(s)) for s in servers if not any(_name(s).lower().startswith(x.rsplit("/providers/microsoft.authorization", 1)[0]) for x in locked)]
sql = [s for s in stores if "sql" in str(s.get("type", "")).lower()]
no_backup = [] # Azure SQL backups are on by default and not exposed by this server's kinds
no_versioning = []
out.append(_check("reliability", "REL-02", "Servers are protected from accidental deletion", unprotected if servers else None,
"deletion protection" if gcp else "resource locks"))
out.append(_check("reliability", "REL-03", "Databases have automated backups", no_backup if sql else None, f"{len(sql)} databases read"))
if gcp:
out.append(_check("reliability", "REL-04", "Storage keeps object versions", no_versioning if buckets else None, f"{len(buckets)} buckets read"))
# Cost and sustainability
stopped = [_short(_name(s)) for s in servers if str(_resource(s).get("status") or s.get("state") or
((_resource(s).get("extended") or {}).get("instanceView") or {}).get("powerState", {}).get("code", "")).upper()
in ("TERMINATED", "STOPPED", "SUSPENDED", "POWERSTATE/DEALLOCATED", "POWERSTATE/STOPPED")]
out.append(_check("cost", "COST-01", "No stopped server is still holding paid resources", stopped if servers else None,
"stopped servers keep their disks and addresses, which are still billed"))
unlabelled = [_short(_name(i)) for i in everything if not any(k.lower() in OWNER_KEYS for k in _labels(i))]
out.append(_check("cost", "COST-02", "Resources carry cost-allocation labels", unlabelled if everything else None,
f"labels looked for: {', '.join(OWNER_KEYS[:4])}…"))
out.append(_check("sustainability", "SUS-01", "No idle or stopped resources", stopped if servers else None,
"the same stopped servers, as wasted capacity"))
# Operations
out.append(_check("operations", "OPS-01", "Resources name an owner or environment", unlabelled if everything else None,
"the same labels identify who runs a resource"))
if gcp and buckets:
no_logs = [_short(_name(b)) for b in buckets if not _resource(b).get("logging")]
out.append(_check("operations", "OPS-02", "Storage access is logged", no_logs, f"{len(buckets)} buckets read"))
return out
def _zone(item: Dict[str, Any]) -> Optional[str]:
m = re.search(r"/zones/([^/]+)", _name(item))
if m:
return m.group(1)
zones = item.get("zones") or _resource(item).get("zones")
return ",".join(zones) if zones else None
# ---------------------------------------------------------------- roll-up ------------------------------------------------
def _impact(provider: str, rec: Dict[str, Any]) -> str:
if provider == "gcp":
return {"P1": "high", "P2": "high", "P3": "medium", "P4": "low"}.get(str(rec.get("priority")), "unknown")
return str((rec.get("properties") or {}).get("impact") or "unknown").lower()
def _summary(provider: str, rec: Dict[str, Any]) -> str:
if provider == "gcp":
return str(rec.get("description") or rec.get("recommenderSubtype") or "")[:160]
p = rec.get("properties") or {}
return str((p.get("shortDescription") or {}).get("problem") or p.get("description") or "")[:160]
def roll_up(provider: str, recs: List[Dict[str, Any]]) -> Dict[str, Any]:
by_pillar: Dict[str, Counter] = defaultdict(Counter)
top: Dict[str, Counter] = defaultdict(Counter)
for r in recs:
pillar = r.get("pillar") or "other"
impact = _impact(provider, r)
by_pillar[pillar][impact] += 1
top[pillar][(impact, _summary(provider, r))] += 1
rank = {"high": 0, "medium": 1, "low": 2}
return {"total": len(recs),
"by_pillar": {p: dict(c) for p, c in by_pillar.items()},
"top": {p: [{"impact": i, "summary": s, "count": n}
for (i, s), n in sorted(c.items(), key=lambda kv: (rank.get(kv[0][0], 3), -kv[1]))[:5]]
for p, c in top.items()}}
def guidance(provider: str, call: Callable, issues: List[str]) -> Dict[str, Dict[str, Any]]:
out = {}
for pillar in PILLARS:
try:
data = _data(call(f"{provider}_search_well_architected", {"pillar": pillar, "topic": TOPICS[pillar]}))
results = data.get("results") or []
first = results[0] if results and isinstance(results[0], dict) else {}
text = first.get("text") or first.get("content") or first.get("snippet") or (results[0] if results else "")
title, link = first.get("title"), first.get("url") or first.get("link")
out[pillar] = {"topic": TOPICS[pillar], "title": title, "url": link, "excerpt": " ".join(str(text).split())[:400],
"evidence_refs": [data["evidence_ref"]] if data.get("evidence_ref") else []}
except Exception as error: # noqa: BLE001
issues.append(f"{provider}_search_well_architected({pillar}): {str(error)[:120]}")
return out
def pillars(chks: List[Dict[str, Any]], recs: Dict[str, Any], guide: Dict[str, Dict[str, Any]]) -> List[Dict[str, Any]]:
out = []
for p in PILLARS:
mine = [c for c in chks if c["pillar"] == p]
counted = recs["by_pillar"].get(p, {})
evidenced = [c for c in mine if c["result"] != "no_evidence"]
failed = [c for c in evidenced if c["result"] == "fail"]
status = "not_assessed" if not evidenced and not counted else ("attention" if failed or counted.get("high") else "reviewed")
out.append({"pillar": p, "title": TITLES[p], "status": status, "checks_passed": len(evidenced) - len(failed),
"checks_failed": len(failed), "checks_no_evidence": len(mine) - len(evidenced),
"recommendations": counted, "top_recommendations": recs["top"].get(p, []),
"guidance": guide.get(p)})
return out
def review(payload: Dict[str, Any], call: Callable) -> Dict[str, Any]:
provider = payload.get("provider") or "sample"
base = {"engagement_id": payload.get("engagement_id"), "run_id": payload.get("run_id"), "provider": provider}
if provider not in KINDS:
result = {**base, "status": "not_applicable", "pillars": [], "checks": [], "recommendations": {"total": 0, "by_pillar": {}, "top": {}},
"call_issues": [], "evidence_refs": [],
"note": "Not applicable: the sample estate has no cloud configuration to review against the Well-Architected Framework."}
else:
scope = [r.get("scope_entry_id") for r in payload.get("records") or [] if r.get("scope_entry_id")]
ev = collect(provider, call, scope)
chks = checks(provider, ev)
recs = roll_up(provider, ev["recommendations"])
guide = guidance(provider, call, ev["issues"])
result = {**base, "status": "assessed", "pillars": pillars(chks, recs, guide), "checks": chks, "recommendations": recs,
"call_issues": ev["issues"], "evidence_refs": ev["evidence_refs"][:200],
"note": (f"{len(scope)} in-scope resources, {recs['total']} provider recommendations. Configuration and "
"recommendations only: no utilisation telemetry, so performance and sustainability are partial.")}
result["waf_markdown"] = render(result, payload)
result["waf_html"] = render_html(result, payload, "Draft. Not for release until the Engagement Lead approves it.")
result["final_waf_html"] = render_html(result, payload)
return result
# ---------------------------------------------------------------- rendering ----------------------------------------------
STATUS_TEXT = {"reviewed": "Reviewed", "attention": "Needs attention", "not_assessed": "Not assessed"}
RESULT_TEXT = {"pass": "Pass", "fail": "Fail", "no_evidence": "No evidence"}
def _md(value: Any) -> str:
if value is None or value == "" or value == []:
return "-"
if isinstance(value, (list, tuple)):
value = ", ".join(str(v) for v in value)
text = " ".join(str(value).split())
for char in ("\\", "|", "`", "*", "_", "<", ">", "[", "]"):
text = text.replace(char, f"\\{char}")
return text
def _table(headers: List[str], rows: List[List[Any]]) -> List[str]:
return ["| " + " | ".join(headers) + " |", "|" + "---|" * len(headers)] + ["| " + " | ".join(_md(v) for v in r) + " |" for r in rows]
def render(r: Dict[str, Any], payload: Dict[str, Any]) -> str:
lines = [f"# Well-Architected review: {_md(r.get('engagement_id'))}", "",
*_table(["Item", "Value"], [["Run", r.get("run_id")], ["Provider", r.get("provider")], ["Status", r.get("status")],
["Discovery critic verdict", payload.get("verdict") or "not supplied"]]), "",
f"> {_md(r.get('note'))}", ""]
if r["status"] != "assessed":
return "\n".join(lines)
lines += ["## Pillars", "", *_table(["Pillar", "Status", "Checks passed", "Checks failed", "No evidence", "Recommendations"],
[[p["title"], STATUS_TEXT[p["status"]], p["checks_passed"], p["checks_failed"], p["checks_no_evidence"],
sum(p["recommendations"].values())] for p in r["pillars"]]), ""]
for p in r["pillars"]:
lines += [f"## {p['title']}", ""]
mine = [c for c in r["checks"] if c["pillar"] == p["pillar"]]
lines += (_table(["Check", "Result", "Affected", "Basis"],
[[f"{c['check_id']} {c['title']}", RESULT_TEXT[c["result"]], c["affected"], c["basis"]] for c in mine])
if mine else ["No fixed check covers this pillar; see the provider's recommendations."]) + [""]
if p["top_recommendations"]:
lines += ["Provider recommendations:", "", *_table(["Impact", "Recommendation", "Count"],
[[t["impact"], t["summary"], t["count"]] for t in p["top_recommendations"]]), ""]
if p.get("guidance") and p["guidance"].get("excerpt"):
lines += [f"Guidance ({_md(p['guidance']['topic'])}): {_md(p['guidance']['excerpt'])}", ""]
if p["status"] == "not_assessed":
lines += ["**Not assessed:** no evidence was available for this pillar. This is not a pass.", ""]
gaps = payload.get("source_gaps") or []
lines += ["## What this review doesn't cover", "",
"- Utilisation telemetry: performance and sustainability rest on configuration and recommendations only."]
lines += [f"- {_md(g.get('source'))}: {_md(g.get('impact'))}" for g in gaps]
if r["call_issues"]:
lines += ["", "## Evidence that couldn't be read", "", *[f"- {_md(i)}" for i in r["call_issues"]]]
return "\n".join(lines) + "\n"
def _h(value: Any) -> str:
if value is None or value == "" or value == []:
return "-"
if isinstance(value, (list, tuple)):
value = ", ".join(str(v) for v in value)
return html.escape(str(value))
TONE = {"Fail": "bad", "Needs attention": "bad", "No evidence": "warn", "Not assessed": "warn", "Pass": "ok", "Reviewed": "ok", "high": "bad",
"medium": "warn", "low": "ok"}
STYLE = """
:root { --ground:#f4f6f8; --surface:#fff; --ink:#16202c; --muted:#566373; --line:#dbe1e8; --band:#10283f; --band-ink:#f2f6fa;
--band-muted:#b5c4d3; --bad:#9f2229; --bad-bg:#fbe8e9; --warn:#855700; --warn-bg:#fcf0d5; --ok:#1a6640; --ok-bg:#e1f2e8;
--sans:"Segoe UI",system-ui,-apple-system,Roboto,Arial,sans-serif; --serif:Georgia,"Times New Roman",serif; }
@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --ground:#10161d; --surface:#182029; --ink:#e6ebf1;
--muted:#9dabb9; --line:#2e3945; --band:#0b1f33; --bad:#ff9fa3; --bad-bg:#40191d; --warn:#f0c46e; --warn-bg:#3a2c10; --ok:#84d9a8;
--ok-bg:#153223; color-scheme: dark; } }
:root[data-theme="dark"] { --ground:#10161d; --surface:#182029; --ink:#e6ebf1; --muted:#9dabb9; --line:#2e3945; --band:#0b1f33;
--bad:#ff9fa3; --bad-bg:#40191d; --warn:#f0c46e; --warn-bg:#3a2c10; --ok:#84d9a8; --ok-bg:#153223; color-scheme: dark; }
* { box-sizing: border-box; } body { margin:0; background:var(--ground); color:var(--ink); font:16px/1.55 var(--sans); }
.wrap { max-width:68rem; margin:0 auto; padding-left:max(16px,env(safe-area-inset-left,0px)); padding-right:max(16px,env(safe-area-inset-right,0px)); }
.cover { background:var(--band); color:var(--band-ink); } .cover .wrap { padding-block:3rem 2.5rem; display:grid; gap:.6rem; }
.eyebrow { margin:0; color:var(--band-muted); font-size:.8rem; letter-spacing:.08em; text-transform:uppercase; }
h1 { margin:0; font:400 2.6rem/1.15 var(--serif); } h2 { margin:0 0 .75rem; font:400 1.5rem/1.25 var(--serif); }
main.wrap { padding-block:2rem 4rem; display:grid; gap:2.5rem; } main > * { min-width:0; }
.notice { margin:0; padding:.75rem 1rem; border-radius:4px; background:var(--warn-bg); color:var(--warn); }
.scroll { overflow-x:auto; background:var(--surface); border:1px solid var(--line); }
table { border-collapse:collapse; width:100%; font-size:.9rem; } th { text-align:left; color:var(--muted); font-size:.8rem; }
th, td { padding:.55rem .8rem; border-bottom:1px solid var(--line); vertical-align:top; } tr:last-child td { border-bottom:0; }
.pill { display:inline-block; padding:0 .45rem; border-radius:3px; font-size:.8rem; font-weight:600; white-space:nowrap; }
.pill.bad { background:var(--bad-bg); color:var(--bad); } .pill.warn { background:var(--warn-bg); color:var(--warn); }
.pill.ok { background:var(--ok-bg); color:var(--ok); } .muted { color:var(--muted); margin:.5rem 0 0; font-size:.9rem; }
@media (max-width:30rem) { h1 { font-size:2rem; } }
@media print { body { background:#fff; } .cover, .pill, .notice { print-color-adjust:exact; -webkit-print-color-adjust:exact; } section { break-inside:avoid-page; } }
"""
def _cell(v: Any) -> str:
tone = TONE.get(str(v))
return f'<span class="pill {tone}">{_h(v)}</span>' if tone else _h(v)
def _htable(headers: List[str], rows: List[List[Any]]) -> str:
head = "".join(f'<th scope="col">{_h(h)}</th>' for h in headers)
body = "".join("<tr>" + "".join(f"<td>{_cell(v)}</td>" for v in row) + "</tr>" for row in rows)
return f'<div class="scroll"><table><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>'
def render_html(r: Dict[str, Any], payload: Dict[str, Any], notice: Optional[str] = None) -> str:
parts = [f'<p class="notice">{_h(notice)}</p>'] if notice else []
parts.append(f'<section><h2>Overview</h2>{_htable(["Item", "Value"], [["Provider", r.get("provider")], ["Status", r.get("status")], ["Discovery critic verdict", payload.get("verdict") or "not supplied"]])}'
f'<p class="muted">{_h(r.get("note"))}</p></section>')
if r["status"] == "assessed":
parts.append("<section><h2>Pillars</h2>" + _htable(["Pillar", "Status", "Passed", "Failed", "No evidence", "Recommendations"],
[[p["title"], STATUS_TEXT[p["status"]], p["checks_passed"], p["checks_failed"], p["checks_no_evidence"],
sum(p["recommendations"].values())] for p in r["pillars"]]) + "</section>")
for p in r["pillars"]:
mine = [c for c in r["checks"] if c["pillar"] == p["pillar"]]
body = _htable(["Check", "Result", "Affected", "Basis"], [[c["title"], RESULT_TEXT[c["result"]], c["affected"], c["basis"]] for c in mine]) if mine else ""
if p["top_recommendations"]:
body += '<p class="muted">Provider recommendations</p>' + _htable(["Impact", "Recommendation", "Count"],
[[t["impact"], t["summary"], t["count"]] for t in p["top_recommendations"]])
if p["status"] == "not_assessed":
body += '<p class="muted">Not assessed: no evidence was available for this pillar. This is not a pass.</p>'
parts.append(f"<section><h2>{_h(p['title'])}</h2>{body}</section>")
gaps = "".join(f"<li>{_h(g.get('source'))}: {_h(g.get('impact'))}</li>" for g in payload.get("source_gaps") or [])
parts.append("<section><h2>What this review doesn't cover</h2><ul><li>Utilisation telemetry: performance and sustainability "
f"rest on configuration and recommendations only.</li>{gaps}</ul></section>")
cover = (f'<header class="cover"><div class="wrap"><p class="eyebrow">Well-Architected review</p><h1>{_h(r.get("engagement_id"))}</h1>'
f'<p class="eyebrow">Run {_h(r.get("run_id"))} · {date.today():%-d %B %Y}</p></div></header>')
return (f'<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">'
f'<title>Well-Architected review {_h(r.get("engagement_id"))}</title><style>{STYLE}</style></head>'
f'<body>{cover}<main class="wrap">{"".join(parts)}</main></body></html>')