- 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>
488 lines
30 KiB
Python
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>')
|