feat: 가상화 문서들 추가

scripts/check-figure-overlap.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""그림 안에서 상자와 라벨이 서로를 덮는지 본다.
+
+`technical-visualizer` 스킬이 적어 둔 사각지대를 기계로 옮긴 것이다.
+
+    **lint 도 검사기도 라벨이 상자를 덮는 것은 못 잡는다.**
+
+lint 는 의미(관계가 이어져 있는가)를 보고 `check-figure-text.py` 는 글자가 이름인가를 본다.
+둘 다 **좌표**를 안 본다. 그래서 zone 둘이 겹쳐 그려지거나 라벨이 상자에 먹혀도 통과한다.
+실제로 keycloak AP4 그림을 다시 만들었을 때 Compose zone 이 Host zone 을 삼키고
+`Host network` 라벨이 `Compose network` 라벨 뒤에 숨었는데 lint 는 PASS 였다.
+
+    python3 scripts/check-figure-overlap.py [프로젝트 ...]
+    python3 scripts/check-figure-overlap.py --file 그림.svg
+
+renderer 가 배경 사각형을 정확한 좌표로 남기므로 글자 폭을 어림하지 않는다 —
+`edge-label-bg` 와 `group-label-bg` 가 그 라벨이 실제로 차지하는 자리다.
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import re
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+RECT = re.compile(r"<rect\b([^>]*)>")
+ATTR = re.compile(r'(\w[\w-]*)="([^"]*)"')
+TEXT = re.compile(r'<text\b([^>]*)>([^<]*)</text>')
+
+# 겹치면 안 되는 짝. (왼쪽 종류, 오른쪽 종류, 무엇이 잘못됐나)
+# group-label-bg 가 group-box 위에 앉는 것과 node-shape 가 group-box 안에 드는 것은 설계다.
+PAIRS = (
+    ("group-box", "group-box", "구역 둘이 겹쳐 그려졌다"),
+    ("group-label-bg", "group-label-bg", "구역 이름이 서로를 덮는다"),
+    ("node-shape", "node-shape", "상자 둘이 겹쳐 그려졌다"),
+    ("edge-label-bg", "node-shape", "이음 라벨이 상자에 먹혔다"),
+    ("edge-label-bg", "edge-label-bg", "이음 라벨끼리 겹친다"),
+)
+
+# 겹침으로 세려면 가로·세로가 둘 다 이만큼은 넘어야 한다.
+# 넓이만 보면 상자가 클수록 예민해진다 — 0.5px 이 50px 짜리 변을 만나면 25px² 이다
+EPS = 1.0
+
+
+def _kind(cls: str) -> str:
+    if "group-box" in cls:
+        return "group-box"
+    if "group-label-bg" in cls:
+        return "group-label-bg"
+    if "edge-label-bg" in cls:
+        return "edge-label-bg"
+    if "node-shape" in cls:
+        return "node-shape"
+    return ""
+
+
+def boxes(svg: str) -> list[tuple[str, float, float, float, float]]:
+    """(종류, x, y, w, h). 좌표가 없는 것은 뺀다 — canvas 가 그렇다."""
+    out = []
+    for attrs in RECT.findall(svg):
+        a = dict(ATTR.findall(attrs))
+        kind = _kind(a.get("class", ""))
+        if not kind:
+            continue
+        try:
+            x, y = float(a["x"]), float(a["y"])
+            w, h = float(a["width"]), float(a["height"])
+        except (KeyError, ValueError):
+            continue
+        out.append((kind, x, y, w, h))
+    return out
+
+
+def labels(svg: str) -> list[tuple[float, float, str]]:
+    """(x, y, 글자). 겹친 자리에 무엇이 있었는지 말해 주려고 쓴다."""
+    out = []
+    for attrs, body in TEXT.findall(svg):
+        a = dict(ATTR.findall(attrs))
+        try:
+            out.append((float(a["x"]), float(a["y"]), body.strip()))
+        except (KeyError, ValueError):
+            continue
+    return out
+
+
+def _overlap(a, b) -> float:
+    """겹친 넓이. 맞닿기만 한 것과 한쪽으로만 얇게 스친 것은 0 이다."""
+    _, ax, ay, aw, ah = a
+    _, bx, by, bw, bh = b
+    dx = min(ax + aw, bx + bw) - max(ax, bx)
+    dy = min(ay + ah, by + bh) - max(ay, by)
+    if dx <= EPS or dy <= EPS:
+        return 0.0
+    return dx * dy
+
+
+def _contains(a, b) -> bool:
+    """a 가 b 를 통째로 품는가. 구역 안의 구역은 설계이지 겹침이 아니다."""
+    _, ax, ay, aw, ah = a
+    _, bx, by, bw, bh = b
+    return ax <= bx and ay <= by and ax + aw >= bx + bw and ay + ah >= by + bh
+
+
+def _near(lbls, box, limit=2) -> str:
+    """상자 안에 든 글자. 어느 라벨이 문제인지 이름으로 말해 준다."""
+    _, x, y, w, h = box
+    hit = [t for lx, ly, t in lbls
+           if t and x - 2 <= lx <= x + w + 2 and y - 14 <= ly <= y + h + 2]
+    return " · ".join(hit[:limit])
+
+
+def check(path: str) -> list[str]:
+    try:
+        svg = open(path, encoding="utf-8").read()
+    except OSError as exc:
+        return [f"읽지 못했다 — {exc}"]
+    bs = boxes(svg)
+    lbls = labels(svg)
+    found: list[str] = []
+    for i, a in enumerate(bs):
+        for b in bs[i + 1:]:
+            for left, right, why in PAIRS:
+                if {a[0], b[0]} != {left, right} if left != right else not (
+                        a[0] == left and b[0] == left):
+                    continue
+                if left == right == "group-box" and (_contains(a, b) or _contains(b, a)):
+                    continue
+                area = _overlap(a, b)
+                if area <= 0:
+                    continue
+                names = " / ".join(n for n in (_near(lbls, a), _near(lbls, b)) if n)
+                found.append(f"{why} — {int(area)}px²{'  ' + names if names else ''}")
+                break
+    return found
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="그림 안에서 상자와 라벨이 겹치는지 본다.")
+    ap.add_argument("projects", nargs="*")
+    ap.add_argument("--file", action="append", default=[], help="SVG 를 직접 준다")
+    ap.add_argument("--samples", type=int, default=4)
+    args = ap.parse_args()
+
+    files = list(args.file)
+    if not files:
+        names = args.projects or sorted(
+            os.path.basename(os.path.dirname(os.path.dirname(p)))
+            for p in glob.glob(os.path.join(ROOT, "docs/*/final/document.md")))
+        for name in names:
+            files += sorted(glob.glob(
+                os.path.join(ROOT, "docs", name, "final/assets/**/*.svg"), recursive=True))
+    if not files:
+        print("볼 그림이 없다", file=sys.stderr)
+        return 0
+
+    bad = 0
+    for path in files:
+        hits = check(path)
+        if not hits:
+            continue
+        bad += 1
+        rel = os.path.relpath(path, ROOT)
+        print(f"✗ {rel}")
+        for line in hits[:args.samples]:
+            print(f"    · {line}")
+        if len(hits) > args.samples:
+            print(f"    … 외 {len(hits) - args.samples}건")
+    print(f"FIGURE OVERLAP: {'FAIL' if bad else 'PASS'} — 그림 {len(files)} · 겹친 그림 {bad}")
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())