forked from diegoecab/oci-deal-accelerator
Diagram generator calibrated from 37 Oracle ref architectures + KB health tooling
Diagram generator (oci_diagram_gen.py): - Icon sizing calibrated: 63px target height, 45px min width (from 37 Oracle Architecture Center .drawio files: 12,617 cells, 234x 63x63 service icons) - Auto-sizing: containers grow from content, never overflow (validated by script) - DRG placed outside VCN, inside region (Oracle hub-spoke pattern) - Gateway stacking uses _calc_service_block_h to prevent label overlap - Edge labels: mxGeometry offset injection (15-20px away from midpoint) - Tight icon groups: edges connect to visible icon, not invisible wide group - VCN/subnet dash pattern corrected to "4 2", stroke to #aa643b (Oracle ref) - jettySize=auto, dual connection merge, container=1;collapsible=0 New tools: - scripts/validate-diagram.py: checks icon sizes, overlaps, container overflow - tools/refresh_arch_catalog.py --check-links: HTTP HEAD check on all 123 URLs - .gitea/workflows/kb-health.yaml: weekly link + freshness check (Mon 8am UTC) - kb/diagram/oracle-ref-measurements.md: exact measurements from Oracle refs - kb/CHANGELOG.md: KB change log shown in welcome banner SKILL.md: - Pre-flight: python→python3, silent errors, git fetch check for local users - Changelog banner in welcome flow - Anti-hallucination guardrails (from earlier commit, carried forward) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
184
scripts/validate-diagram.py
Normal file
184
scripts/validate-diagram.py
Normal file
@@ -0,0 +1,184 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Diagram quality validator — checks generated .drawio files against
|
||||
Oracle Architecture Center visual standards.
|
||||
|
||||
Usage:
|
||||
python3 scripts/validate-diagram.py examples/output-demo-pharma-mx/opt02-architecture.drawio
|
||||
"""
|
||||
|
||||
import sys
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
MIN_ICON_H = 45 # Minimum icon height (px) — Oracle refs use 50-60
|
||||
MIN_ICON_W = 30 # Minimum icon width (px)
|
||||
MAX_EMPTY_RATIO = 0.7 # Max empty space ratio in a container
|
||||
MIN_LABEL_FONT = 10 # Minimum label font size
|
||||
MIN_GAP_PX = 5 # Minimum gap between sibling elements
|
||||
|
||||
|
||||
def validate(filepath: str) -> list:
|
||||
"""Return list of (severity, message) tuples."""
|
||||
issues = []
|
||||
tree = ET.parse(filepath)
|
||||
root = tree.getroot()
|
||||
|
||||
icon_groups = []
|
||||
containers = []
|
||||
all_cells = {}
|
||||
|
||||
for cell in root.iter('mxCell'):
|
||||
cid = cell.get('id', '')
|
||||
style = cell.get('style', '')
|
||||
value = cell.get('value', '')
|
||||
geo = cell.find('mxGeometry')
|
||||
all_cells[cid] = cell
|
||||
|
||||
if geo is None:
|
||||
continue
|
||||
|
||||
w = float(geo.get('width', 0))
|
||||
h = float(geo.get('height', 0))
|
||||
x = float(geo.get('x', 0))
|
||||
y = float(geo.get('y', 0))
|
||||
|
||||
# Icon groups
|
||||
if 'group' in style and 'connectable=1' in style:
|
||||
icon_groups.append({
|
||||
'id': cid, 'x': x, 'y': y, 'w': w, 'h': h,
|
||||
'parent': cell.get('parent', ''),
|
||||
})
|
||||
if h < MIN_ICON_H:
|
||||
issues.append(('WARN', f'Icon {cid} too short: {h:.0f}px (min {MIN_ICON_H})'))
|
||||
if w < MIN_ICON_W:
|
||||
issues.append(('WARN', f'Icon {cid} too narrow: {w:.0f}px (min {MIN_ICON_W})'))
|
||||
|
||||
# Containers (regions, VCNs, subnets)
|
||||
if value and any(kw in value for kw in ['Region', 'VCN', 'Subnet', 'Oracle Cloud']):
|
||||
containers.append({
|
||||
'id': cid, 'name': value[:40], 'x': x, 'y': y, 'w': w, 'h': h,
|
||||
'parent': cell.get('parent', ''),
|
||||
})
|
||||
|
||||
# Check children overflow parents
|
||||
container_map = {}
|
||||
for cell in root.iter('mxCell'):
|
||||
cid = cell.get('id', '')
|
||||
val = cell.get('value', '')
|
||||
geo = cell.find('mxGeometry')
|
||||
if geo is not None and val:
|
||||
container_map[cid] = {
|
||||
'name': val[:50], 'x': float(geo.get('x', 0)),
|
||||
'y': float(geo.get('y', 0)), 'w': float(geo.get('width', 0)),
|
||||
'h': float(geo.get('height', 0)), 'parent': cell.get('parent', ''),
|
||||
}
|
||||
|
||||
for cid, c in container_map.items():
|
||||
parent = container_map.get(c['parent'])
|
||||
if parent:
|
||||
child_right = c['x'] + c['w']
|
||||
child_bottom = c['y'] + c['h']
|
||||
overflow_r = child_right - parent['w']
|
||||
overflow_b = child_bottom - parent['h']
|
||||
if overflow_r > 2:
|
||||
issues.append(('ERROR', f'{c["name"]} overflows {parent["name"]} RIGHT by {overflow_r:.0f}px'))
|
||||
if overflow_b > 2:
|
||||
issues.append(('ERROR', f'{c["name"]} overflows {parent["name"]} BOTTOM by {overflow_b:.0f}px'))
|
||||
|
||||
# Check for overlapping siblings (same parent)
|
||||
by_parent = {}
|
||||
for ig in icon_groups:
|
||||
by_parent.setdefault(ig['parent'], []).append(ig)
|
||||
|
||||
for parent_id, siblings in by_parent.items():
|
||||
siblings.sort(key=lambda s: (s['y'], s['x']))
|
||||
for i in range(len(siblings) - 1):
|
||||
a = siblings[i]
|
||||
b = siblings[i + 1]
|
||||
# Check vertical overlap (same column, x ranges overlap)
|
||||
x_overlap = not (a['x'] + a['w'] < b['x'] or b['x'] + b['w'] < a['x'])
|
||||
if x_overlap:
|
||||
gap = b['y'] - (a['y'] + a['h'])
|
||||
if gap < MIN_GAP_PX:
|
||||
issues.append(('ERROR', f'Overlap between icons in parent {parent_id}: gap={gap:.0f}px'))
|
||||
|
||||
# Check container utilization (warn on mostly empty containers)
|
||||
for cont in containers:
|
||||
children_area = 0
|
||||
for ig in icon_groups:
|
||||
if ig['parent'] == cont['id']:
|
||||
children_area += ig['w'] * ig['h']
|
||||
for child_cont in containers:
|
||||
if child_cont['parent'] == cont['id']:
|
||||
children_area += child_cont['w'] * child_cont['h']
|
||||
cont_area = cont['w'] * cont['h']
|
||||
if cont_area > 0:
|
||||
fill_ratio = children_area / cont_area
|
||||
if fill_ratio < (1 - MAX_EMPTY_RATIO):
|
||||
issues.append(('INFO', f'{cont["name"]}: {fill_ratio:.0%} filled ({cont["w"]:.0f}x{cont["h"]:.0f})'))
|
||||
|
||||
# Check edge labels have offset (mxPoint as="offset")
|
||||
edges_with_label = 0
|
||||
edges_with_offset = 0
|
||||
for cell in root.iter('mxCell'):
|
||||
if cell.get('edge') == '1' and cell.get('value', '').strip():
|
||||
edges_with_label += 1
|
||||
geo = cell.find('mxGeometry')
|
||||
if geo is not None:
|
||||
offset = geo.find('.//mxPoint[@as="offset"]')
|
||||
if offset is not None:
|
||||
edges_with_offset += 1
|
||||
|
||||
if edges_with_label > 0 and edges_with_offset < edges_with_label:
|
||||
issues.append(('WARN', f'{edges_with_label - edges_with_offset}/{edges_with_label} edge labels missing offset'))
|
||||
|
||||
# Check jettySize=auto present
|
||||
has_jetty = False
|
||||
for cell in root.iter('mxCell'):
|
||||
if 'jettySize=auto' in cell.get('style', ''):
|
||||
has_jetty = True
|
||||
break
|
||||
if not has_jetty:
|
||||
issues.append(('WARN', 'No edges with jettySize=auto'))
|
||||
|
||||
# Check container=1 present
|
||||
has_container = False
|
||||
for cell in root.iter('mxCell'):
|
||||
if 'container=1' in cell.get('style', ''):
|
||||
has_container = True
|
||||
break
|
||||
if not has_container:
|
||||
issues.append(('WARN', 'No containers with explicit container=1 style'))
|
||||
|
||||
return issues
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 2:
|
||||
print(f"Usage: {sys.argv[0]} <diagram.drawio>")
|
||||
sys.exit(1)
|
||||
|
||||
filepath = sys.argv[1]
|
||||
issues = validate(filepath)
|
||||
|
||||
if not issues:
|
||||
print(f"✅ {filepath}: All checks passed")
|
||||
sys.exit(0)
|
||||
|
||||
errors = [i for i in issues if i[0] == 'ERROR']
|
||||
warns = [i for i in issues if i[0] == 'WARN']
|
||||
infos = [i for i in issues if i[0] == 'INFO']
|
||||
|
||||
print(f"📋 Diagram validation: {filepath}")
|
||||
print(f" {len(errors)} errors, {len(warns)} warnings, {len(infos)} info")
|
||||
print()
|
||||
|
||||
for severity, msg in issues:
|
||||
icon = {'ERROR': '❌', 'WARN': '⚠️', 'INFO': 'ℹ️'}.get(severity, '?')
|
||||
print(f" {icon} [{severity}] {msg}")
|
||||
|
||||
sys.exit(1 if errors else 0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user