Import sap-architecture skill
This commit is contained in:
@@ -0,0 +1,924 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate a SAP Architecture Center-style .drawio file.
|
||||
|
||||
Catches the bugs that make a diagram look unprofessional:
|
||||
|
||||
Structural
|
||||
* malformed XML / missing mxGeometry / duplicate ids / comments
|
||||
* root-cell skeleton (parentless root + layer first; content on ids 0/1)
|
||||
* ';base64' inside image= style values (truncates -> blank icons)
|
||||
* mxCell ids, including draw.io UserObject wrapper ids
|
||||
Alignment
|
||||
* x/y/width/height not integer multiples of 10 (grid-snap)
|
||||
* edge source+target don't share a center axis (bent arrows)
|
||||
* container children extending outside container bounds
|
||||
* overlapping siblings (unintended stacking)
|
||||
Text
|
||||
* label text wider than the shape (overflow / clipping)
|
||||
* edge label missing `labelBackgroundColor` (disappears in colored zone)
|
||||
Style
|
||||
* colors not in the SAP Horizon palette (warnings)
|
||||
* missing `absoluteArcSize=1` when `arcSize` is set (percent-rendering bug)
|
||||
* fontFamily not Helvetica
|
||||
* strokeWidth outside {1, 1.5, 3, 4}
|
||||
|
||||
Exit code:
|
||||
0 — clean (or only warnings)
|
||||
1 — errors
|
||||
2 — usage
|
||||
|
||||
Flags:
|
||||
--strict warnings become errors
|
||||
--json JSON report to stdout instead of human text
|
||||
|
||||
Run: python3 validate.py <file.drawio>
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
import xml.etree.ElementTree as ET
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
|
||||
# ---------- SAP Horizon palette ----------------------------------------------
|
||||
# Source of truth, in priority order:
|
||||
# 1. SAP/btp-solution-diagrams/guideline/docs/btp_guideline/foundation.md
|
||||
# and diagr_comp/areas.md (primary, semantic, accent)
|
||||
# 2. Hex values observed in SAP/btp-solution-diagrams/assets/
|
||||
# editable-diagram-examples/*.drawio (real-world variations)
|
||||
# 3. SAP/architecture-center/docs/ref-arch/RA*/drawio/*.drawio
|
||||
SAP_PALETTE = {
|
||||
# --- foundation.md primary -------------------------------------------------
|
||||
"#0070F2", "#EBF8FF", # SAP / BTP area: border, fill
|
||||
"#475E75", "#F5F6F7", # Non-SAP area: border, fill
|
||||
"#1D2D3E", # Title text
|
||||
"#556B82", # Body text
|
||||
# --- foundation.md semantic ------------------------------------------------
|
||||
"#188918", "#F5FAE5", # Positive (authentication flows)
|
||||
"#C35500", "#FFF8D6", # Critical
|
||||
"#D20A0A", "#FFEAF4", # Negative
|
||||
# --- foundation.md accent (sparingly) -------------------------------------
|
||||
"#07838F", "#DAFDF5", # Teal
|
||||
"#5D36FF", "#F1ECFF", # Indigo (authorization flows)
|
||||
"#CC00DC", "#FFF0FA", # Pink (trust flows)
|
||||
# --- preset (in drawio-config-all-in-one.json) ----------------------------
|
||||
"#793802", # Brown — present in preset, no documented role
|
||||
# --- darker text / accent variants used in real SAP diagrams --------------
|
||||
"#002A86", "#00185A", "#0057D2", "#2395FF", # SAP blue variants observed in Architecture Center
|
||||
"#266F3A", # darker positive green
|
||||
"#470BED", # darker indigo (preset variant of #5D36FF)
|
||||
"#7F00FF", # alt accent purple
|
||||
# --- observed grey / neutral variations (real SAP files) ------------------
|
||||
"#1A2733", # near-black navy used by some diagrams
|
||||
"#354A5F", # mid grey
|
||||
"#475E74", "#475F75", # off-by-one variants of #475E75
|
||||
"#5B738B", # lighter grey
|
||||
"#595959",
|
||||
"#D5DADD", "#EAECEE", "#EDEDED", "#EDEFF0", "#EAF8FF", "#EDF8FF", "#ECF8FF",
|
||||
"#D1EFFF", "#CCDDFF",
|
||||
"#FCFCFC",
|
||||
# --- additional colors observed in the bundled 71 reference templates -----
|
||||
# These are accepted to avoid flagging SAP's own published diagrams as
|
||||
# off-palette. New generated diagrams should still prefer the documented
|
||||
# Horizon colors above.
|
||||
"#178B1B", "#4628EC", "#C0399F", "#1D1B1B", "#00185B", "#0878F5", "#0D3C56",
|
||||
"#1B91FF", "#1C2D3E", "#6A6A6A", "#89D1FF", "#D2F0FF", "#00144A", "#121212",
|
||||
"#212121", "#5F6369", "#CC01DB", "#FFCC99", "#0070F3", "#8EA2B5", "#CB00DC",
|
||||
"#D3E8FD", "#FFE6CC", "#004C99", "#0170F2", "#053B70", "#0A74F3", "#102937",
|
||||
"#107E3E", "#333333", "#666666", "#6D7F91", "#8695A4", "#BFBFBF", "#D79B00",
|
||||
"#F5F5F5", "#0080F0", "#3333FF", "#3399FF", "#354C5F", "#4D4D4D", "#6666FF",
|
||||
"#6C8EBF", "#A100C2", "#B3B3B3", "#B46504", "#C5761C", "#C87515", "#CCE5FF",
|
||||
"#E7E8E9", "#F65AF2", "#FAD7AC", "#FF8000", "#FFB300", "#0000CC", "#0000FF",
|
||||
"#003366", "#0040B0", "#006600", "#0066CC", "#006EAF", "#0071F2", "#007FFF",
|
||||
"#009500", "#00BEF2", "#00CEAC", "#04221C", "#101C22", "#192B3D", "#1BA1E2",
|
||||
"#221111", "#223548", "#251821", "#314354", "#354B5F", "#36393D", "#384C61",
|
||||
"#470CED", "#60A917", "#647687", "#6600CC", "#67AB9F", "#7F7F7F", "#808080",
|
||||
"#9B76FF", "#A8A8FF", "#CCCCFF", "#D6B656", "#DAE8FC", "#DF8C42", "#E07A5F",
|
||||
"#E6E6E6", "#EEEEEE", "#F2CC8F", "#F9F7ED", "#FF87FF", "#FFB366", "#FFD966",
|
||||
"#FFF2CC",
|
||||
# --- basics ----------------------------------------------------------------
|
||||
"#FFFFFF", "#FFF", "#000000", "#000",
|
||||
}
|
||||
|
||||
COMMENT_RE = re.compile(r"<!--.*?-->", re.S)
|
||||
HEX_RE = re.compile(r"#[0-9A-Fa-f]{6}\b")
|
||||
# data URIs embed their own palette we should NOT flag
|
||||
DATA_URI_RE = re.compile(r"data:image/[^&\";]+")
|
||||
|
||||
GRID = 10
|
||||
ALLOWED_STROKE = {"1", "1.5", "2", "3", "4"}
|
||||
|
||||
# Canonical SAP flow-pill vocabulary, extracted from the published reference
|
||||
# corpus. Pills with labels outside this set tend to indicate hand-crafted
|
||||
# diagrams rather than SAP-style flow narration. We don't enforce strictly —
|
||||
# many cases legitimately add custom verbs — but emit a warning so reviewers
|
||||
# can ratify the deviation.
|
||||
CANONICAL_PILL_LABELS = {
|
||||
# identity / trust / auth
|
||||
"trust", "authenticate", "authentication", "authorization",
|
||||
"identity", "identity lifecycle", "customer-managed identity lifecycle",
|
||||
"user", "usergroup", "group", "role", "role collection", "role collections",
|
||||
"policy", "scim", "saml2/oidc", "oidc", "saml", "openid",
|
||||
# transport
|
||||
"https", "https/active", "https/standby", "rest", "rest/spi",
|
||||
"rest/token", "rest / odata", "odata/rest", "odata/rest/soap",
|
||||
# data flows
|
||||
"destination", "source", "target", "harmonized api",
|
||||
"data federation", "data sync", "task data",
|
||||
# agentic ai vocab seen in RA0029 family
|
||||
"a2a", "mcp", "ord",
|
||||
# business
|
||||
"business data cloud", "business role", "cdm",
|
||||
# other observed
|
||||
"role replica",
|
||||
# semantic renderer labels that follow SAP-style flow narration
|
||||
"commit", "build & test", "release", "deploy", "connectivity", "private link",
|
||||
"sql", "security logs", "alerts, findings & enriched events",
|
||||
"correlated incidents", "status & closure updates", "notification", "open ticket",
|
||||
# generic but acceptable
|
||||
"data", "metadata",
|
||||
}
|
||||
|
||||
# Pill labels Codex observed in failed generations (PROMPT, ROUTE, CONTEXT,
|
||||
# DELEGATE, etc.) — explicit watch-list to surface the most common drift.
|
||||
NOVELTY_PILL_LABELS = {
|
||||
"prompt", "route", "context", "delegate", "answer", "ask", "respond",
|
||||
"query", "fetch", "invoke", "call", "execute", "run", "process",
|
||||
"send", "receive", "publish", "subscribe", "transform",
|
||||
}
|
||||
|
||||
# Light/neutral page backgrounds we accept. Anything else (dark, branded,
|
||||
# strongly tinted) is suspect because no SAP reference uses one.
|
||||
ALLOWED_PAGE_BACKGROUNDS = {None, "", "none", "default", "#ffffff", "#fff", "#FFFFFF", "#FFF"}
|
||||
|
||||
|
||||
# ---------- Report model -----------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class Issue:
|
||||
kind: str # "error" | "warning"
|
||||
category: str # "xml", "align", "text", "style"
|
||||
msg: str
|
||||
cell: str | None = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class Report:
|
||||
path: str
|
||||
issues: list[Issue] = field(default_factory=list)
|
||||
|
||||
def add(self, kind: str, category: str, msg: str, cell: str | None = None) -> None:
|
||||
self.issues.append(Issue(kind, category, msg, cell))
|
||||
|
||||
@property
|
||||
def errors(self) -> list[Issue]:
|
||||
return [i for i in self.issues if i.kind == "error"]
|
||||
|
||||
@property
|
||||
def warnings(self) -> list[Issue]:
|
||||
return [i for i in self.issues if i.kind == "warning"]
|
||||
|
||||
def to_json(self) -> dict:
|
||||
return {
|
||||
"path": self.path,
|
||||
"ok": not self.errors,
|
||||
"errors": [{"category": i.category, "msg": i.msg, "cell": i.cell} for i in self.errors],
|
||||
"warnings": [{"category": i.category, "msg": i.msg, "cell": i.cell} for i in self.warnings],
|
||||
}
|
||||
|
||||
|
||||
# ---------- Geometry helpers -------------------------------------------------
|
||||
|
||||
|
||||
def geom(cell: ET.Element) -> tuple[float, float, float, float] | None:
|
||||
g = cell.find("mxGeometry")
|
||||
if g is None:
|
||||
return None
|
||||
try:
|
||||
x = float(g.get("x", "0"))
|
||||
y = float(g.get("y", "0"))
|
||||
w = float(g.get("width", "0"))
|
||||
h = float(g.get("height", "0"))
|
||||
return x, y, w, h
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def parse_style(style: str | None) -> dict[str, str]:
|
||||
if not style:
|
||||
return {}
|
||||
out: dict[str, str] = {}
|
||||
for part in style.split(";"):
|
||||
part = part.strip()
|
||||
if not part:
|
||||
continue
|
||||
if "=" in part:
|
||||
k, v = part.split("=", 1)
|
||||
out[k.strip()] = v.strip()
|
||||
else:
|
||||
out[part] = "1"
|
||||
return out
|
||||
|
||||
|
||||
def approx_text_width(text: str, font_size: float, bold: bool = False) -> float:
|
||||
"""Crude width estimate in px. Good enough to catch egregious overflow."""
|
||||
if not text:
|
||||
return 0.0
|
||||
# avg char width ≈ 0.55 × font_size for Helvetica regular, 0.60 bold
|
||||
coef = 0.60 if bold else 0.55
|
||||
return len(text) * font_size * coef
|
||||
|
||||
|
||||
def visible_label_lines(label: str) -> list[str]:
|
||||
"""Reduce an HTML-ish draw.io label to visible text lines."""
|
||||
label = html.unescape(label or "")
|
||||
label = re.sub(r"</(?:div|p|li)>", "\n", label, flags=re.I)
|
||||
label = re.sub(r"<br\s*/?>", "\n", label, flags=re.I)
|
||||
no_tags = re.sub(r"<[^>]+>", "", label)
|
||||
lines = [re.sub(r"\s+", " ", line).strip() for line in no_tags.splitlines()]
|
||||
return [line for line in lines if line]
|
||||
|
||||
|
||||
def strip_html(label: str) -> str:
|
||||
"""Reduce HTML label to its visible text (rough)."""
|
||||
return " ".join(visible_label_lines(label))
|
||||
|
||||
|
||||
def html_font_size(label: str, fallback: float) -> float:
|
||||
"""Best-effort font-size extraction from draw.io rich text labels."""
|
||||
sizes: list[float] = []
|
||||
for value in re.findall(r"font-size\s*:\s*([0-9.]+)\s*px", label or "", flags=re.I):
|
||||
try:
|
||||
sizes.append(float(value))
|
||||
except ValueError:
|
||||
pass
|
||||
for value in re.findall(r"<font[^>]*\bsize=[\"']?([0-9]+)", label or "", flags=re.I):
|
||||
# draw.io/browser HTML font size 1 renders small; this is only a fit heuristic.
|
||||
sizes.append({"1": 10.0, "2": 11.0, "3": 12.0, "4": 14.0, "5": 18.0, "6": 24.0, "7": 32.0}.get(value, fallback))
|
||||
return min(sizes) if sizes else fallback
|
||||
|
||||
|
||||
def bbox_overlap(a: tuple[float, float, float, float], b: tuple[float, float, float, float]) -> float:
|
||||
"""Return overlap area in px². 0 if no overlap."""
|
||||
ax, ay, aw, ah = a
|
||||
bx, by, bw, bh = b
|
||||
dx = max(0.0, min(ax + aw, bx + bw) - max(ax, bx))
|
||||
dy = max(0.0, min(ay + ah, by + bh) - max(ay, by))
|
||||
return dx * dy
|
||||
|
||||
|
||||
# ---------- Validators -------------------------------------------------------
|
||||
|
||||
|
||||
def validate(path: Path) -> Report:
|
||||
report = Report(path=str(path))
|
||||
text = path.read_text(encoding="utf-8")
|
||||
|
||||
if COMMENT_RE.search(text):
|
||||
report.add("error", "xml", "XML comments (<!-- -->) forbidden — strip them")
|
||||
|
||||
try:
|
||||
root = ET.fromstring(text)
|
||||
except ET.ParseError as exc:
|
||||
report.add("error", "xml", f"XML parse error: {exc}")
|
||||
return report
|
||||
|
||||
# ---- collect cells & basic structural checks ---------------------------
|
||||
parent_by_elem = {id(child): parent for parent in root.iter() for child in list(parent)}
|
||||
|
||||
def effective_cell_id(cell: ET.Element) -> str | None:
|
||||
cid = cell.get("id")
|
||||
if cid:
|
||||
return cid
|
||||
parent = parent_by_elem.get(id(cell))
|
||||
if parent is not None and parent.tag == "UserObject":
|
||||
return parent.get("id")
|
||||
return None
|
||||
|
||||
graphs = root.findall(".//mxGraphModel") or [root]
|
||||
|
||||
# Page background colour — SAP diagrams are always on a white/transparent canvas.
|
||||
for graph_index, graph in enumerate(graphs):
|
||||
bg = graph.get("background") or graph.get("pageBackgroundColor")
|
||||
if bg and bg.strip().lower() not in {b.lower() for b in ALLOWED_PAGE_BACKGROUNDS if b}:
|
||||
suffix = "" if len(graphs) == 1 else f" (page {graph_index + 1})"
|
||||
report.add(
|
||||
"error",
|
||||
"style",
|
||||
f"page background {bg!r}{suffix} — SAP diagrams use a white/transparent canvas; "
|
||||
"remove the dark/branded background.",
|
||||
)
|
||||
|
||||
def scoped_id(graph_index: int, cell_id: str) -> str:
|
||||
return cell_id if len(graphs) == 1 else f"{graph_index}:{cell_id}"
|
||||
|
||||
cells: dict[str, ET.Element] = {}
|
||||
cell_scopes: dict[str, int] = {}
|
||||
duplicate_ids: set[tuple[int, str]] = set()
|
||||
for graph_index, graph in enumerate(graphs):
|
||||
seen_in_graph: set[str] = set()
|
||||
for cell in graph.iter("mxCell"):
|
||||
cid = effective_cell_id(cell)
|
||||
if cid is None:
|
||||
report.add("error", "xml", "mxCell without id attribute")
|
||||
continue
|
||||
if cid in seen_in_graph:
|
||||
duplicate_ids.add((graph_index, cid))
|
||||
seen_in_graph.add(cid)
|
||||
|
||||
key = scoped_id(graph_index, cid)
|
||||
cells[key] = cell
|
||||
cell_scopes[key] = graph_index
|
||||
|
||||
is_vertex = cell.get("vertex") == "1"
|
||||
is_edge = cell.get("edge") == "1"
|
||||
if (is_vertex or is_edge) and cell.find("mxGeometry") is None:
|
||||
report.add("error", "xml", "vertex/edge missing <mxGeometry>", cell=key)
|
||||
|
||||
for graph_index, cid in duplicate_ids:
|
||||
suffix = "" if len(graphs) == 1 else f" in diagram page {graph_index + 1}"
|
||||
report.add("error", "xml", f"duplicate id {cid!r}{suffix}")
|
||||
|
||||
# ---- root-cell skeleton ------------------------------------------------
|
||||
# mxGraph needs a root cell (no parent, not vertex/edge) and a layer cell
|
||||
# parented to it as the first two cells of each page. SAP files often use
|
||||
# namespaced ids (e.g. <prefix>-0/<prefix>-1) rather than literal 0/1, so
|
||||
# we check structure, not the id values. A content cell reusing literal
|
||||
# "0"/"1" is a collision hazard when pages are merged into files that DO
|
||||
# use the default ids — warn on that.
|
||||
for graph_index, graph in enumerate(graphs):
|
||||
suffix = "" if len(graphs) == 1 else f" in diagram page {graph_index + 1}"
|
||||
page_cells = list(graph.iter("mxCell"))
|
||||
if not page_cells:
|
||||
continue
|
||||
first = page_cells[0]
|
||||
if first.get("parent") is not None or first.get("vertex") == "1" or first.get("edge") == "1":
|
||||
report.add(
|
||||
"error", "xml",
|
||||
f"page has no root cell skeleton{suffix} — the first mxCell must be the parentless "
|
||||
"root (then a layer cell parented to it) before any content; draw.io rejects files without it",
|
||||
)
|
||||
elif len(page_cells) >= 2:
|
||||
layer = page_cells[1]
|
||||
if layer.get("parent") != first.get("id") or layer.get("vertex") == "1" or layer.get("edge") == "1":
|
||||
report.add(
|
||||
"warning", "xml",
|
||||
f"second cell is not a layer parented to the root{suffix} (draw.io convention: root then layer)",
|
||||
)
|
||||
for c in page_cells[2:]:
|
||||
if effective_cell_id(c) in ("0", "1") and (c.get("vertex") == "1" or c.get("edge") == "1"):
|
||||
report.add(
|
||||
"warning", "xml",
|
||||
f"content cell uses id {effective_cell_id(c)!r}{suffix} — mxGraph's default root/layer ids; "
|
||||
"collision-prone, namespace generated ids (n-<id>)",
|
||||
cell=scoped_id(graph_index, effective_cell_id(c)),
|
||||
)
|
||||
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("edge") != "1":
|
||||
continue
|
||||
scope = cell_scopes[cid]
|
||||
for attr in ("source", "target"):
|
||||
ref = cell.get(attr)
|
||||
if ref and scoped_id(scope, ref) not in cells:
|
||||
report.add("warning", "xml", f"edge references missing {attr} id {ref!r}", cell=cid)
|
||||
|
||||
abs_geom_cache: dict[str, tuple[float, float, float, float] | None] = {}
|
||||
|
||||
def absolute_geom(cid: str) -> tuple[float, float, float, float] | None:
|
||||
"""Return geometry in page coordinates, resolving draw.io child parents."""
|
||||
if cid in abs_geom_cache:
|
||||
return abs_geom_cache[cid]
|
||||
cell = cells.get(cid)
|
||||
if cell is None:
|
||||
abs_geom_cache[cid] = None
|
||||
return None
|
||||
g = geom(cell)
|
||||
if not g:
|
||||
abs_geom_cache[cid] = None
|
||||
return None
|
||||
x, y, w, h = g
|
||||
parent_id = cell.get("parent")
|
||||
if parent_id and parent_id not in {"0", "1"}:
|
||||
parent_key = scoped_id(cell_scopes[cid], parent_id)
|
||||
pg = absolute_geom(parent_key)
|
||||
if pg:
|
||||
x += pg[0]
|
||||
y += pg[1]
|
||||
abs_geom_cache[cid] = (x, y, w, h)
|
||||
return abs_geom_cache[cid]
|
||||
|
||||
# ---- style / palette ---------------------------------------------------
|
||||
palette_text = DATA_URI_RE.sub("", text)
|
||||
foreign = {m.upper() for m in HEX_RE.findall(palette_text)} - {c.upper() for c in SAP_PALETTE}
|
||||
for color in sorted(foreign):
|
||||
report.add("warning", "style", f"off-palette color {color}")
|
||||
|
||||
# ---- per-cell checks ---------------------------------------------------
|
||||
grid_total = 0
|
||||
grid_off = 0
|
||||
grid_examples: list[str] = []
|
||||
for cid, cell in cells.items():
|
||||
style = parse_style(cell.get("style"))
|
||||
|
||||
# Grid snap
|
||||
g = geom(cell)
|
||||
if g:
|
||||
x, y, w, h = g
|
||||
for name, val in (("x", x), ("y", y), ("width", w), ("height", h)):
|
||||
grid_total += 1
|
||||
if abs(val - round(val)) > 0.01 or int(round(val)) % GRID != 0:
|
||||
grid_off += 1
|
||||
if len(grid_examples) < 5:
|
||||
grid_examples.append(f"{cid}.{name}={val!r}")
|
||||
|
||||
# absoluteArcSize when arcSize present
|
||||
if "arcSize" in style and style.get("absoluteArcSize") != "1":
|
||||
report.add(
|
||||
"warning",
|
||||
"style",
|
||||
"arcSize without absoluteArcSize=1 renders as percentage",
|
||||
cell=cid,
|
||||
)
|
||||
|
||||
# Font family
|
||||
ff = style.get("fontFamily")
|
||||
if ff and ff.lower() != "helvetica":
|
||||
report.add("warning", "style", f"fontFamily={ff!r} (expected Helvetica)", cell=cid)
|
||||
|
||||
# Image source hygiene
|
||||
raw_style = cell.get("style") or ""
|
||||
if "image=" in raw_style and ";base64," in raw_style:
|
||||
report.add(
|
||||
"error", "style",
|
||||
"';base64' inside image= style — draw.io truncates the value at the ';' "
|
||||
"and the icon renders blank; use image=data:<mime>,<b64> (payload still base64, marker dropped)",
|
||||
cell=cid,
|
||||
)
|
||||
image = style.get("image")
|
||||
if image and image.startswith(("http://", "https://")):
|
||||
report.add("warning", "style", "external image URL — prefer bundled SAP inline assets", cell=cid)
|
||||
elif image and not (image.startswith("data:image/") or image == "img/lib/sap/SAP_Logo.svg"):
|
||||
report.add("warning", "style", f"non-bundled image source {image!r}", cell=cid)
|
||||
|
||||
# Stroke width
|
||||
sw = style.get("strokeWidth")
|
||||
if sw and sw not in ALLOWED_STROKE:
|
||||
report.add("warning", "style", f"strokeWidth={sw!r} (expected one of {sorted(ALLOWED_STROKE)})", cell=cid)
|
||||
|
||||
# Edge-label background
|
||||
if cell.get("edge") == "1":
|
||||
val = cell.get("value") or ""
|
||||
if val.strip() and not style.get("labelBackgroundColor"):
|
||||
report.add(
|
||||
"warning",
|
||||
"text",
|
||||
"edge label without labelBackgroundColor (will bleed into zone fill)",
|
||||
cell=cid,
|
||||
)
|
||||
if "endArrow" not in style and "startArrow" not in style:
|
||||
report.add("warning", "style", "edge without endArrow style", cell=cid)
|
||||
|
||||
# Text overflow (vertex only, has a label, has geometry)
|
||||
if cell.get("vertex") == "1" and g:
|
||||
raw_label = cell.get("value") or ""
|
||||
label = strip_html(raw_label)
|
||||
if label and style.get("autosize") != "1" and style.get("shape") != "image" and "image" not in style:
|
||||
font_size = html_font_size(raw_label, float(style.get("fontSize", "12")))
|
||||
bold = style.get("fontStyle", "0") in {"1", "3", "5", "7"}
|
||||
spacing = float(style.get("spacingLeft", "0")) + float(style.get("spacingRight", "0"))
|
||||
wrap = style.get("whiteSpace") == "wrap" and style.get("html") == "1"
|
||||
effective_w = g[2] - spacing - 6 # 6 px slop
|
||||
if wrap:
|
||||
# With wrapping, only the single longest token needs to fit
|
||||
longest = max(label.split(), key=len, default="")
|
||||
need = approx_text_width(longest, font_size, bold)
|
||||
if effective_w > 0 and need > effective_w + 6:
|
||||
report.add(
|
||||
"warning",
|
||||
"text",
|
||||
f"longest word '{longest}' ~{int(need)}px > shape width {int(g[2])}px — clip",
|
||||
cell=cid,
|
||||
)
|
||||
else:
|
||||
longest_line = max(visible_label_lines(raw_label) or [label], key=len)
|
||||
need = approx_text_width(longest_line, font_size, bold)
|
||||
if effective_w > 0 and need > effective_w + 6:
|
||||
report.add(
|
||||
"warning",
|
||||
"text",
|
||||
f"label ~{int(need)}px wider than shape ({int(g[2])}px) — text will clip",
|
||||
cell=cid,
|
||||
)
|
||||
|
||||
if grid_total:
|
||||
snap_rate = 1.0 - (grid_off / grid_total)
|
||||
if snap_rate < 0.95:
|
||||
examples = f"; examples: {', '.join(grid_examples)}" if grid_examples else ""
|
||||
report.add(
|
||||
"warning",
|
||||
"align",
|
||||
f"grid-snap rate {snap_rate * 100:.1f}% below recommended 95% "
|
||||
f"({grid_off}/{grid_total} geometry values off {GRID}-px grid){examples}",
|
||||
)
|
||||
|
||||
# ---- pill / flow-narration vocabulary check ---------------------------
|
||||
# A pill is roughly arcSize >= 40 with a label. SAP's published corpus uses
|
||||
# a small canonical vocabulary (TRUST, Authenticate, A2A, MCP, ORD, HTTPS,
|
||||
# OData/REST, …). Custom verbs like PROMPT/ROUTE/CONTEXT/DELEGATE indicate
|
||||
# an LLM hand-crafted the diagram instead of starting from a template.
|
||||
# Track the labels we saw, then warn for each one outside the canon.
|
||||
seen_pill_labels: list[tuple[str, str]] = [] # (label, cid)
|
||||
novelty_pills: list[tuple[str, str]] = []
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("vertex") != "1":
|
||||
continue
|
||||
style = parse_style(cell.get("style"))
|
||||
try:
|
||||
arc = int(float(style.get("arcSize", "0")))
|
||||
except ValueError:
|
||||
arc = 0
|
||||
if arc < 40:
|
||||
continue
|
||||
# Pill must be small (single line, < 200 px wide). Larger rounded
|
||||
# shapes can be cards or banners, which use a separate label vocab.
|
||||
g = geom(cell)
|
||||
if not g or g[2] > 220 or g[3] > 60:
|
||||
continue
|
||||
raw = cell.get("value") or ""
|
||||
# UserObject wrapping: a parent UserObject may carry the visible label
|
||||
if not raw:
|
||||
parent = parent_by_elem.get(id(cell))
|
||||
if parent is not None and parent.tag == "UserObject":
|
||||
raw = parent.get("value") or parent.get("label") or ""
|
||||
label_text = strip_html(raw).strip()
|
||||
if not label_text:
|
||||
continue
|
||||
seen_pill_labels.append((label_text, cid))
|
||||
normalized = label_text.lower()
|
||||
if normalized in CANONICAL_PILL_LABELS:
|
||||
continue
|
||||
# Single-token novelty pill — the most common LLM drift mode.
|
||||
first_token = normalized.split()[0] if normalized else ""
|
||||
if first_token in NOVELTY_PILL_LABELS:
|
||||
novelty_pills.append((label_text, cid))
|
||||
report.add(
|
||||
"warning",
|
||||
"text",
|
||||
f"flow pill {label_text!r} is not in the canonical SAP vocabulary "
|
||||
"(TRUST/Authenticate/A2A/MCP/ORD/HTTPS/OData/REST/…). "
|
||||
"Replace with a SAP-style verb or remove the pill.",
|
||||
cell=cid,
|
||||
)
|
||||
|
||||
# ---- sibling overlap checks (vertices sharing a parent) ---------------
|
||||
def is_transparent_or_chrome(cell: ET.Element) -> bool:
|
||||
"""Cells that float on top of others by design and shouldn't be flagged."""
|
||||
s = parse_style(cell.get("style"))
|
||||
if s.get("fillColor") in (None, "none"):
|
||||
return True
|
||||
if s.get("shape") in ("ellipse", "image"):
|
||||
return True
|
||||
# pill (arcSize >= 40 roughly)
|
||||
try:
|
||||
if int(s.get("arcSize", "0")) >= 40:
|
||||
return True
|
||||
except ValueError:
|
||||
pass
|
||||
# text-only cells
|
||||
if s.get("text") == "1" or s.get("strokeColor") == "none":
|
||||
return True
|
||||
return False
|
||||
|
||||
by_parent: dict[str, list[tuple[str, tuple[float, float, float, float], ET.Element]]] = {}
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("vertex") != "1":
|
||||
continue
|
||||
parent = scoped_id(cell_scopes[cid], cell.get("parent") or "")
|
||||
g = geom(cell)
|
||||
if not g or g[2] <= 0 or g[3] <= 0:
|
||||
continue
|
||||
by_parent.setdefault(parent, []).append((cid, g, cell))
|
||||
|
||||
for parent, members in by_parent.items():
|
||||
for i in range(len(members)):
|
||||
for j in range(i + 1, len(members)):
|
||||
ida, ga, ca = members[i]
|
||||
idb, gb, cb = members[j]
|
||||
ov = bbox_overlap(ga, gb)
|
||||
if ov <= 100: # ignore slivers
|
||||
continue
|
||||
ax, ay, aw, ah = ga
|
||||
bx, by_, bw, bh = gb
|
||||
contains = (ax <= bx and ay <= by_ and ax + aw >= bx + bw and ay + ah >= by_ + bh) or (
|
||||
bx <= ax and by_ <= ay and bx + bw >= ax + aw and by_ + bh >= ay + ah
|
||||
)
|
||||
if contains:
|
||||
continue
|
||||
# Pills / icons / text / transparent cells are allowed to float over frames
|
||||
if is_transparent_or_chrome(ca) or is_transparent_or_chrome(cb):
|
||||
continue
|
||||
report.add(
|
||||
"warning",
|
||||
"align",
|
||||
f"cells {ida} and {idb} overlap by {int(ov)}px² (same parent {parent})",
|
||||
)
|
||||
|
||||
# ---- bent-edge detection ----------------------------------------------
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("edge") != "1":
|
||||
continue
|
||||
src_id = cell.get("source")
|
||||
tgt_id = cell.get("target")
|
||||
if not src_id or not tgt_id:
|
||||
continue
|
||||
style = parse_style(cell.get("style"))
|
||||
if style.get("edgeStyle") != "orthogonalEdgeStyle":
|
||||
continue # non-orthogonal edges may legitimately curve
|
||||
# Skip edges with explicit entry/exit anchors — author has chosen the docking
|
||||
if any(k in style for k in ("entryX", "exitX", "entryY", "exitY")):
|
||||
continue
|
||||
scope = cell_scopes[cid]
|
||||
src = cells.get(scoped_id(scope, src_id))
|
||||
tgt = cells.get(scoped_id(scope, tgt_id))
|
||||
if src is None or tgt is None:
|
||||
continue
|
||||
gs = absolute_geom(scoped_id(scope, src_id))
|
||||
gt = absolute_geom(scoped_id(scope, tgt_id))
|
||||
if not gs or not gt:
|
||||
continue
|
||||
cx_s = gs[0] + gs[2] / 2
|
||||
cy_s = gs[1] + gs[3] / 2
|
||||
cx_t = gt[0] + gt[2] / 2
|
||||
cy_t = gt[1] + gt[3] / 2
|
||||
aligned_v = abs(cx_s - cx_t) <= 1.0 # centers on same vertical
|
||||
aligned_h = abs(cy_s - cy_t) <= 1.0 # centers on same horizontal
|
||||
if not (aligned_v or aligned_h):
|
||||
# Is there overlap on an axis? If boxes overlap on X the edge can still drop straight
|
||||
overlap_x = min(gs[0] + gs[2], gt[0] + gt[2]) - max(gs[0], gt[0])
|
||||
overlap_y = min(gs[1] + gs[3], gt[1] + gt[3]) - max(gs[1], gt[1])
|
||||
if overlap_x < 10 and overlap_y < 10:
|
||||
report.add(
|
||||
"warning",
|
||||
"align",
|
||||
f"edge {cid}: source/target centers differ on both axes "
|
||||
f"(Δx={cx_s - cx_t:.0f}, Δy={cy_s - cy_t:.0f}) — arrow will bend. "
|
||||
"Either snap centers or add entryX/exitX anchors.",
|
||||
cell=cid,
|
||||
)
|
||||
|
||||
# ---- duplicate SAP logos check ----------------------------------------
|
||||
# SAP guideline: "It is not recommended to use too many SAP logos in the
|
||||
# same diagram." (product_names.md). One inline SAP_Logo.svg per zone-band
|
||||
# is acceptable; more than ~4 in a single page is suspicious.
|
||||
sap_logo_count = 0
|
||||
for cid, cell in cells.items():
|
||||
style = parse_style(cell.get("style"))
|
||||
image = style.get("image")
|
||||
if image and "sap_logo" in image.lower():
|
||||
sap_logo_count += 1
|
||||
if sap_logo_count > 6:
|
||||
report.add(
|
||||
"warning",
|
||||
"style",
|
||||
f"{sap_logo_count} SAP logos detected — SAP recommends limiting logo "
|
||||
"repetition. Use text-only product labels instead beyond zone branding.",
|
||||
)
|
||||
|
||||
# ---- icon-size check ---------------------------------------------------
|
||||
# SAP corpus: icons cluster tightly at 32x32 (224x), 48x48 (157x), 28x28 (85x).
|
||||
# Icons larger than ~64 px overpower cards and overlap their text — the
|
||||
# most common visible bug from LLM-generated diagrams.
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("vertex") != "1":
|
||||
continue
|
||||
style = parse_style(cell.get("style"))
|
||||
is_icon = (
|
||||
style.get("shape") == "image"
|
||||
and style.get("image", "").startswith(("data:image/svg", "data:image/png"))
|
||||
) or "mxgraph.sap.icon" in (cell.get("style") or "")
|
||||
if not is_icon:
|
||||
continue
|
||||
g = geom(cell)
|
||||
if not g:
|
||||
continue
|
||||
_, _, w, h = g
|
||||
# Only flag near-square images that are big in both dimensions. SAP uses
|
||||
# horizontal text banners (e.g. 67x18 for product names) which are
|
||||
# technically `shape=image` but aren't "icons" in the visual-bug sense.
|
||||
is_square_ish = 0.5 <= (w / max(1, h)) <= 2.0
|
||||
if w > 64 and h > 64 and is_square_ish:
|
||||
report.add(
|
||||
"warning",
|
||||
"style",
|
||||
f"icon w={int(w)}×h={int(h)} is oversized — SAP corpus standard is 32×32 (most common) "
|
||||
"or 48×48 for focal anchors. Resize this icon to avoid overlapping card text.",
|
||||
cell=cid,
|
||||
)
|
||||
|
||||
# ---- icon-overlapping-text check --------------------------------------
|
||||
# An icon dropped on top of a card's text region is the signature failure
|
||||
# of LLM-placed icons. Detect by: icon vertex whose bounding box overlaps
|
||||
# a non-image vertex by more than 25% of the icon's area, where the other
|
||||
# vertex has a non-empty visible label.
|
||||
icon_cells: list[tuple[str, tuple[float, float, float, float]]] = []
|
||||
text_vertex_cells: list[tuple[str, tuple[float, float, float, float]]] = []
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("vertex") != "1":
|
||||
continue
|
||||
g = geom(cell)
|
||||
if not g:
|
||||
continue
|
||||
style = parse_style(cell.get("style"))
|
||||
is_icon = (
|
||||
style.get("shape") == "image"
|
||||
and style.get("image", "").startswith(("data:image/svg", "data:image/png"))
|
||||
) or "mxgraph.sap.icon" in (cell.get("style") or "")
|
||||
if is_icon:
|
||||
icon_cells.append((cid, g))
|
||||
continue
|
||||
# text-bearing card: has a non-empty visible label and a fill (so it's a card, not chrome)
|
||||
raw = cell.get("value") or ""
|
||||
label = strip_html(raw).strip()
|
||||
if not label:
|
||||
continue
|
||||
if style.get("fillColor", "").lower() in ("none", ""):
|
||||
continue
|
||||
if style.get("shape") in ("ellipse",):
|
||||
continue # ellipses are often legend dots, not text cards
|
||||
text_vertex_cells.append((cid, g))
|
||||
|
||||
for icon_id, ig in icon_cells:
|
||||
ix, iy, iw, ih = ig
|
||||
icon_area = max(1.0, iw * ih)
|
||||
for txt_id, tg in text_vertex_cells:
|
||||
ov = bbox_overlap(ig, tg)
|
||||
if ov < icon_area * 0.25:
|
||||
continue
|
||||
# Skip if icon is entirely INSIDE the card (intentional inline placement)
|
||||
tx, ty, tw, th = tg
|
||||
if tx <= ix and ty <= iy and tx + tw >= ix + iw and ty + th >= iy + ih:
|
||||
continue
|
||||
report.add(
|
||||
"warning",
|
||||
"align",
|
||||
f"icon {icon_id} overlaps card {txt_id} by {int(ov)}px² — icon will block "
|
||||
"card text. Move the icon to a dedicated empty region OR shrink it to 32×32 "
|
||||
"and tuck it inside the card.",
|
||||
cell=icon_id,
|
||||
)
|
||||
|
||||
# ---- edges passing through other cells --------------------------------
|
||||
# An edge from A to B should not run its straight-line path across the
|
||||
# bounding box of unrelated card C. This produces the visible bug of
|
||||
# "arrows that look like they hit the card." Sample 50 points along the
|
||||
# edge's straight path; flag if any unrelated vertex contains > 5 of them.
|
||||
other_cells_by_scope: dict[int, list[tuple[str, tuple[float, float, float, float]]]] = {}
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("vertex") != "1":
|
||||
continue
|
||||
g = absolute_geom(cid)
|
||||
if not g or g[2] <= 0 or g[3] <= 0:
|
||||
continue
|
||||
scope = cell_scopes.get(cid, 0)
|
||||
other_cells_by_scope.setdefault(scope, []).append((cid, g))
|
||||
|
||||
for cid, cell in cells.items():
|
||||
if cell.get("edge") != "1":
|
||||
continue
|
||||
s_id, t_id = cell.get("source"), cell.get("target")
|
||||
if not s_id or not t_id:
|
||||
continue
|
||||
scope = cell_scopes.get(cid, 0)
|
||||
src = cells.get(scoped_id(scope, s_id))
|
||||
tgt = cells.get(scoped_id(scope, t_id))
|
||||
if src is None or tgt is None:
|
||||
continue
|
||||
sg = absolute_geom(scoped_id(scope, s_id))
|
||||
tg = absolute_geom(scoped_id(scope, t_id))
|
||||
if not sg or not tg:
|
||||
continue
|
||||
# Endpoints: card centers (this is where draw.io draws straight edges to)
|
||||
sx, sy = sg[0] + sg[2] / 2, sg[1] + sg[3] / 2
|
||||
tx, ty = tg[0] + tg[2] / 2, tg[1] + tg[3] / 2
|
||||
# Walk the straight line; collect any cell that is hit by > 5 sample points
|
||||
through: dict[str, int] = {}
|
||||
steps = 50
|
||||
for i in range(1, steps):
|
||||
tparam = i / steps
|
||||
px = sx + (tx - sx) * tparam
|
||||
py = sy + (ty - sy) * tparam
|
||||
for other_id, og in other_cells_by_scope.get(scope, []):
|
||||
if other_id == src.get("id") or other_id == tgt.get("id"):
|
||||
continue
|
||||
if other_id in (s_id, t_id):
|
||||
continue
|
||||
ox, oy, ow, oh = og
|
||||
if ox < px < ox + ow and oy < py < oy + oh:
|
||||
through[other_id] = through.get(other_id, 0) + 1
|
||||
# Report edges that clearly cross unrelated cells (parents/zones excluded)
|
||||
# A "parent" of source/target is acceptable (the edge enters its own zone)
|
||||
src_parent = src.get("parent")
|
||||
tgt_parent = tgt.get("parent")
|
||||
for other_id, count in sorted(through.items(), key=lambda kv: -kv[1]):
|
||||
# Require substantial coverage: > 25% of the sampled path AND a
|
||||
# minimum absolute step count. Otherwise we get noise from edges
|
||||
# that just clip the corner of an unrelated cell.
|
||||
if count < 13:
|
||||
continue
|
||||
if other_id in {src_parent, tgt_parent}:
|
||||
continue # edge passes through its own zone — fine
|
||||
# Also skip if "other" is a transparent / chrome cell (no fill)
|
||||
other_cell = cells.get(other_id)
|
||||
if other_cell is None:
|
||||
continue
|
||||
if is_transparent_or_chrome(other_cell):
|
||||
continue
|
||||
ostyle = parse_style(other_cell.get("style"))
|
||||
if ostyle.get("fillColor", "").lower() in ("none", "") and ostyle.get("shape") not in ("image",):
|
||||
continue
|
||||
# Skip cells with no visible label — they're decorative chrome
|
||||
# (background bands, page borders, container shells). The user
|
||||
# only cares when an arrow visibly crosses a labeled card.
|
||||
other_raw = other_cell.get("value") or ""
|
||||
other_label = strip_html(other_raw).strip()
|
||||
if not other_label:
|
||||
continue
|
||||
# Skip the source/target's container ancestors (zones the edge
|
||||
# legitimately enters or leaves)
|
||||
anc_id = other_cell.get("parent")
|
||||
ancestors_of_obstacle = set()
|
||||
while anc_id:
|
||||
ancestors_of_obstacle.add(anc_id)
|
||||
anc = cells.get(anc_id)
|
||||
if anc is None:
|
||||
break
|
||||
anc_id = anc.get("parent")
|
||||
if src.get("id") in ancestors_of_obstacle or tgt.get("id") in ancestors_of_obstacle:
|
||||
continue
|
||||
report.add(
|
||||
"warning",
|
||||
"align",
|
||||
f"edge {cid} ({s_id} → {t_id}) passes through cell {other_id} "
|
||||
f"(label={other_label[:40]!r}). Add entryX/exitX/entryY/exitY anchors to dock the edge "
|
||||
"on the card's edge, OR set edgeStyle=orthogonalEdgeStyle and reposition cells so "
|
||||
"the edge can route around the obstacle.",
|
||||
cell=cid,
|
||||
)
|
||||
break # one warning per edge is enough; LLM will fix and re-run
|
||||
|
||||
return report
|
||||
|
||||
|
||||
# ---------- Output ----------------------------------------------------------
|
||||
|
||||
|
||||
def print_text(report: Report) -> None:
|
||||
path = report.path
|
||||
if not report.issues:
|
||||
print(f"{path}: OK")
|
||||
return
|
||||
for i in report.warnings:
|
||||
loc = f" [{i.cell}]" if i.cell else ""
|
||||
print(f"{path}: warning ({i.category}){loc}: {i.msg}")
|
||||
for i in report.errors:
|
||||
loc = f" [{i.cell}]" if i.cell else ""
|
||||
print(f"{path}: error ({i.category}){loc}: {i.msg}")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("files", nargs="+")
|
||||
ap.add_argument("--strict", action="store_true", help="warnings fail the run")
|
||||
ap.add_argument("--json", action="store_true")
|
||||
args = ap.parse_args()
|
||||
|
||||
rc = 0
|
||||
reports = []
|
||||
for f in args.files:
|
||||
p = Path(f)
|
||||
if not p.exists():
|
||||
print(f"{p}: not found", file=sys.stderr)
|
||||
rc = 1
|
||||
continue
|
||||
r = validate(p)
|
||||
reports.append(r)
|
||||
if r.errors or (args.strict and r.warnings):
|
||||
rc = 1
|
||||
|
||||
if args.json:
|
||||
print(json.dumps([r.to_json() for r in reports], indent=2))
|
||||
else:
|
||||
for r in reports:
|
||||
print_text(r)
|
||||
|
||||
return rc
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user