@taloswork/ose-shared 0.1.8 → 0.1.9

package/skills/diagram-design/scripts/drawio_extract.py

@@ -0,0 +1,856 @@
+#!/usr/bin/env python3
+"""Extract a normalized intermediate representation (IR) from a draw.io file.
+
+The deterministic half of the draw.io import flow: this script never makes a
+design decision. It decodes whatever draw.io wrote (raw XML, deflate+base64
+payloads, PNG/SVG files with an embedded ``mxfile``), flattens the mxGraphModel
+into absolute-positioned nodes and edges, and reports structural signals — hubs,
+containers, depth, cycles, leaf clusters — that the skill uses to pick a diagram
+type and a level of detail.
+
+Usage:
+    python3 drawio_extract.py <file.drawio> [--page N|NAME] [--json]
+                             [--max-rows N] [--out PATH]
+
+Default output is a compact Markdown digest meant to be read into context.
+``--json`` emits the full IR instead (every node, every edge, every style).
+
+Exit codes: 0 ok, 2 unreadable / unsupported input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import html
+import json
+import re
+import struct
+import sys
+import zlib
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+from xml.etree import ElementTree as ET
+
+# --------------------------------------------------------------------------
+# container / payload decoding
+# --------------------------------------------------------------------------
+
+PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+MAX_INPUT_BYTES = 32 * 1024 * 1024
+MAX_XML_BYTES = 64 * 1024 * 1024
+
+
+class PayloadTooLarge(ValueError):
+    """Raised when compressed metadata expands beyond the supported limit."""
+
+
+def _fail(msg: str) -> "NoReturn":  # type: ignore[valid-type]
+    print(f"drawio_extract: {msg}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def _reject_unsafe_xml(xml: str, source: str) -> None:
+    """Reject declarations that can make XML parsing expand external data."""
+    upper = xml.upper()
+    if "<!DOCTYPE" in upper or "<!ENTITY" in upper:
+        _fail(f"{source}: DTD and entity declarations are not supported")
+
+
+def _decompress_limited(data: bytes, wbits: int, limit: int = MAX_XML_BYTES) -> bytes:
+    """Decompress without allowing a small payload to expand without bound."""
+    decompressor = zlib.decompressobj(wbits)
+    output = bytearray()
+    chunk = data
+    while chunk:
+        remaining = limit + 1 - len(output)
+        if remaining <= 0:
+            raise PayloadTooLarge(f"decoded payload exceeds {limit} bytes")
+        output.extend(decompressor.decompress(chunk, remaining))
+        if len(output) > limit:
+            raise PayloadTooLarge(f"decoded payload exceeds {limit} bytes")
+        chunk = decompressor.unconsumed_tail
+    if not decompressor.eof:
+        raise zlib.error("incomplete compressed payload")
+    remaining = limit + 1 - len(output)
+    if remaining <= 0:
+        raise PayloadTooLarge(f"decoded payload exceeds {limit} bytes")
+    output.extend(decompressor.flush(remaining))
+    if len(output) > limit:
+        raise PayloadTooLarge(f"decoded payload exceeds {limit} bytes")
+    return bytes(output)
+
+
+def _inflate(payload: str) -> str | None:
+    """Undo draw.io's base64 + raw-deflate + URL-encoding pipeline."""
+    try:
+        raw = base64.b64decode(payload, validate=False)
+    except Exception:
+        return None
+    for wbits in (-15, 15, 47):
+        try:
+            text = _decompress_limited(raw, wbits).decode("utf-8", "replace")
+        except PayloadTooLarge:
+            _fail(
+                f"decoded diagram exceeds the {MAX_XML_BYTES // (1024 * 1024)} MiB limit"
+            )
+        except Exception:
+            continue
+        # draw.io URL-encodes before deflating; unquote is a no-op if it didn't.
+        return unquote(text)
+    return None
+
+
+def _png_embedded_xml(data: bytes) -> str | None:
+    """Pull the ``mxfile`` tEXt/zTXt chunk out of a draw.io-exported PNG."""
+    pos = len(PNG_MAGIC)
+    while pos + 8 <= len(data):
+        (length,) = struct.unpack(">I", data[pos : pos + 4])
+        ctype = data[pos + 4 : pos + 8]
+        body_end = pos + 8 + length
+        chunk_end = body_end + 4
+        if chunk_end > len(data):
+            _fail("PNG has a truncated metadata chunk")
+        body = data[pos + 8 : body_end]
+        pos = chunk_end
+        if ctype not in (b"tEXt", b"zTXt", b"iTXt"):
+            if ctype == b"IEND":
+                break
+            continue
+        key, _, rest = body.partition(b"\x00")
+        if key.lower() != b"mxfile":
+            continue
+        try:
+            if ctype == b"tEXt":
+                value = rest
+            elif ctype == b"zTXt":
+                value = _decompress_limited(rest[1:], 15)
+            else:  # iTXt: compression flag, method, lang, translated key, text
+                flag = rest[0:1]
+                tail = rest[2:].split(b"\x00", 2)[-1]
+                value = _decompress_limited(tail, 15) if flag == b"\x01" else tail
+        except PayloadTooLarge:
+            _fail(
+                f"embedded PNG diagram exceeds the "
+                f"{MAX_XML_BYTES // (1024 * 1024)} MiB limit"
+            )
+        except (IndexError, ValueError, zlib.error):
+            _fail("PNG has invalid compressed draw.io metadata")
+        return unquote(value.decode("utf-8", "replace"))
+    return None
+
+
+def _svg_embedded_xml(text: str) -> str | None:
+    for match in re.finditer(
+        r"\bcontent\s*=\s*([\"'])(.*?)\1", text, flags=re.IGNORECASE | re.DOTALL
+    ):
+        candidate = html.unescape(match.group(2))
+        if "<mxfile" in candidate or "<mxGraphModel" in candidate:
+            return candidate
+    return None
+
+
+def load_mxfile(path: Path) -> str:
+    """Return the ``<mxfile>`` (or bare ``<mxGraphModel>``) XML for any input."""
+    size = path.stat().st_size
+    if size > MAX_INPUT_BYTES:
+        _fail(
+            f"{path.name}: input is {size} bytes; maximum is "
+            f"{MAX_INPUT_BYTES // (1024 * 1024)} MiB"
+        )
+    data = path.read_bytes()
+    if data.startswith(PNG_MAGIC):
+        xml = _png_embedded_xml(data)
+        if not xml:
+            _fail(f"{path.name}: PNG has no embedded draw.io diagram")
+        return xml
+    text = data.decode("utf-8", "replace").lstrip("").strip()
+    if "<mxfile" in text or "<mxGraphModel" in text:
+        return text
+    if "<svg" in text[:2000]:
+        xml = _svg_embedded_xml(text)
+        if not xml:
+            _fail(f"{path.name}: SVG has no embedded draw.io diagram")
+        return xml
+    inflated = _inflate(text)
+    if inflated and "<mxGraphModel" in inflated:
+        return inflated
+    _fail(f"{path.name}: not a draw.io file (no mxfile, mxGraphModel, or payload)")
+
+
+# --------------------------------------------------------------------------
+# style + label helpers
+# --------------------------------------------------------------------------
+
+BR_RE = re.compile(r"<br\s*/?>|</p\s*>|</div\s*>", re.IGNORECASE)
+TAG_RE = re.compile(r"<[^>]+>")
+
+
+def parse_style(style: str | None) -> dict[str, str]:
+    out: dict[str, str] = {}
+    if not style:
+        return out
+    for part in style.split(";"):
+        part = part.strip()
+        if not part:
+            continue
+        key, sep, value = part.partition("=")
+        out[key.strip()] = value.strip() if sep else "1"
+    return out
+
+
+def clean_label(value: str | None) -> str:
+    """draw.io labels are often HTML fragments; flatten to plain text lines."""
+    if not value:
+        return ""
+    text = BR_RE.sub("\n", value)
+    text = TAG_RE.sub("", text)
+    text = html.unescape(text)
+    text = text.replace("\xa0", " ")
+    lines = [re.sub(r"[ \t]+", " ", ln).strip() for ln in text.split("\n")]
+    return "\n".join(ln for ln in lines if ln).strip()
+
+
+SHAPE_FAMILIES = (
+    ("mxgraph.aws", "aws"),
+    ("mxgraph.azure", "azure"),
+    ("mxgraph.gcp", "gcp"),
+    ("mxgraph.kubernetes", "kubernetes"),
+    ("mxgraph.cisco", "network"),
+    ("mxgraph.veeam", "infra"),
+    ("mxgraph.flowchart", "flowchart"),
+    ("mxgraph.bpmn", "bpmn"),
+    ("mxgraph.er", "er"),
+    ("mxgraph.sysml", "uml"),
+    ("mxgraph.archimate", "archimate"),
+)
+
+# style key -> canonical shape name, checked in order
+SHAPE_KEYS = (
+    ("swimlane", "swimlane"),
+    ("ellipse", "ellipse"),
+    ("rhombus", "rhombus"),
+    ("triangle", "triangle"),
+    ("cylinder", "cylinder"),
+    ("cylinder3", "cylinder"),
+    ("hexagon", "hexagon"),
+    ("cloud", "cloud"),
+    ("actor", "actor"),
+    ("umlActor", "actor"),
+    ("note", "note"),
+    ("card", "card"),
+    ("step", "step"),
+    ("process", "process"),
+    ("parallelogram", "parallelogram"),
+    ("document", "document"),
+    ("datastore", "cylinder"),
+    ("umlLifeline", "lifeline"),
+    ("umlFrame", "frame"),
+    ("table", "table"),
+    ("tableRow", "table-row"),
+    ("partialRectangle", "table-row"),
+    ("image", "image"),
+    ("text", "text"),
+    ("group", "group"),
+)
+
+
+def classify_shape(style: dict[str, str]) -> str:
+    raw = style.get("shape", "")
+    if raw:
+        for key, name in SHAPE_KEYS:
+            if raw == key or raw.startswith(key):
+                return name
+        for prefix, family in SHAPE_FAMILIES:
+            if raw.startswith(prefix):
+                return f"icon:{family}"
+        return f"shape:{raw}"
+    for key, name in SHAPE_KEYS:
+        if key in style:
+            return name
+    if style.get("ellipse") == "1":
+        return "ellipse"
+    return "rect"
+
+
+def shape_family(shape: str) -> str:
+    if shape.startswith("icon:"):
+        return shape.split(":", 1)[1]
+    if shape.startswith("shape:"):
+        return "custom"
+    return shape
+
+
+# --------------------------------------------------------------------------
+# IR model
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Node:
+    id: str
+    label: str = ""
+    shape: str = "rect"
+    parent: str | None = None
+    depth: int = 0
+    x: float = 0.0
+    y: float = 0.0
+    w: float = 0.0
+    h: float = 0.0
+    fill: str = ""
+    stroke: str = ""
+    font_color: str = ""
+    dashed: bool = False
+    rounded: bool = False
+    container: bool = False
+    children: list[str] = field(default_factory=list)
+    link: str = ""
+    attrs: dict[str, str] = field(default_factory=dict)
+    in_degree: int = 0
+    out_degree: int = 0
+
+
+@dataclass
+class Edge:
+    id: str
+    source: str | None
+    target: str | None
+    label: str = ""
+    dashed: bool = False
+    bidirectional: bool = False
+    undirected: bool = False
+    style_name: str = ""
+    waypoints: int = 0
+    stroke: str = ""
+
+
+@dataclass
+class Page:
+    id: str
+    name: str
+    index: int
+    nodes: list[Node] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+
+    @property
+    def node_map(self) -> dict[str, Node]:
+        return {n.id: n for n in self.nodes}
+
+
+def _num(geom: ET.Element | None, key: str) -> float:
+    if geom is None:
+        return 0.0
+    try:
+        return float(geom.get(key, "0") or 0)
+    except ValueError:
+        return 0.0
+
+
+def parse_page(diagram: ET.Element, index: int) -> Page:
+    name = diagram.get("name") or f"Page-{index + 1}"
+    page = Page(id=diagram.get("id") or f"page-{index}", name=name, index=index)
+
+    model = diagram.find(".//mxGraphModel")
+    if model is None:
+        text = (diagram.text or "").strip()
+        inflated = _inflate(text) if text else None
+        if not inflated:
+            return page
+        _reject_unsafe_xml(inflated, f"page {index}")
+        model = ET.fromstring(inflated)
+        if model.tag != "mxGraphModel":
+            found = model.find(".//mxGraphModel")
+            if found is None:
+                return page
+            model = found
+
+    root = model.find("root")
+    if root is None:
+        return page
+
+    # Pass 1: collect raw cells, unwrapping <object>/<UserObject> containers.
+    raw: dict[str, dict[str, Any]] = {}
+    order: list[str] = []
+    for element in root:
+        if element.tag in ("object", "UserObject"):
+            cell = element.find("mxCell")
+            if cell is None:
+                continue
+            attrs = {
+                k: v
+                for k, v in element.attrib.items()
+                if k not in ("id", "label", "placeholders")
+            }
+            cid = element.get("id") or cell.get("id") or ""
+            value = element.get("label", "")
+        elif element.tag == "mxCell":
+            cell = element
+            attrs = {}
+            cid = cell.get("id") or ""
+            value = cell.get("value", "")
+        else:
+            continue
+        if not cid:
+            continue
+        raw[cid] = {"cell": cell, "attrs": attrs, "value": value}
+        order.append(cid)
+
+    # Pass 2: vertices (absolute geometry resolved after the pass).
+    edge_label_parts: dict[str, list[str]] = {}
+    for cid in order:
+        entry = raw[cid]
+        cell = entry["cell"]
+        style = parse_style(cell.get("style"))
+        parent = cell.get("parent")
+        if cell.get("edge") == "1":
+            continue
+        if cell.get("vertex") != "1":
+            continue
+        # An edge label is a vertex parented to an edge; fold it into the edge.
+        parent_entry = raw.get(parent or "")
+        parent_is_edge = bool(
+            parent_entry and parent_entry["cell"].get("edge") == "1"
+        )
+        if parent_is_edge or "edgeLabel" in style:
+            if parent:
+                text = clean_label(entry["value"])
+                if text:
+                    edge_label_parts.setdefault(parent, []).append(text)
+            continue
+
+        geom = cell.find("mxGeometry")
+        node = Node(
+            id=cid,
+            label=clean_label(entry["value"]),
+            shape=classify_shape(style),
+            parent=parent,
+            x=_num(geom, "x"),
+            y=_num(geom, "y"),
+            w=_num(geom, "width"),
+            h=_num(geom, "height"),
+            fill=style.get("fillColor", ""),
+            stroke=style.get("strokeColor", ""),
+            font_color=style.get("fontColor", ""),
+            dashed=style.get("dashed") == "1",
+            rounded=style.get("rounded") == "1",
+            container=style.get("container") == "1" or "swimlane" in style,
+            link=entry["attrs"].get("link", ""),
+            attrs={
+                k: v
+                for k, v in entry["attrs"].items()
+                if k not in ("link", "tooltip")
+            },
+        )
+        page.nodes.append(node)
+
+    node_map = page.node_map
+
+    # Resolve absolute geometry + depth by walking the parent chain.
+    def resolve(node: Node, seen: set[str]) -> tuple[float, float, int]:
+        if node.id in seen:
+            return node.x, node.y, 0
+        seen.add(node.id)
+        parent = node_map.get(node.parent or "")
+        if parent is None:
+            return node.x, node.y, 0
+        px, py, pdepth = resolve(parent, seen)
+        return node.x + px, node.y + py, pdepth + 1
+
+    for node in page.nodes:
+        ax, ay, depth = resolve(node, set())
+        node.x, node.y, node.depth = ax, ay, depth
+        parent = node_map.get(node.parent or "")
+        if parent is not None:
+            parent.children.append(node.id)
+            parent.container = True
+
+    # Pass 3: edges.
+    for cid in order:
+        entry = raw[cid]
+        cell = entry["cell"]
+        if cell.get("edge") != "1":
+            continue
+        style = parse_style(cell.get("style"))
+        geom = cell.find("mxGeometry")
+        waypoints = 0
+        if geom is not None:
+            waypoints = len(
+                [p for p in geom.findall(".//mxPoint") if p.get("as") is None]
+            )
+        label = clean_label(entry["value"])
+        extra = edge_label_parts.get(cid, [])
+        if extra:
+            label = " / ".join([p for p in ([label] + extra) if p])
+        source = cell.get("source")
+        target = cell.get("target")
+        page.edges.append(
+            Edge(
+                id=cid,
+                source=source if source in node_map else None,
+                target=target if target in node_map else None,
+                label=label,
+                dashed=style.get("dashed") == "1",
+                bidirectional=style.get("startArrow", "none")
+                not in ("none", "0", "")
+                and style.get("endArrow", "classic") not in ("none", "0"),
+                undirected=style.get("endArrow") in ("none", "0")
+                and style.get("startArrow", "none") in ("none", "0", ""),
+                style_name=style.get("shape", "")
+                or ("orthogonal" if style.get("edgeStyle") else ""),
+                waypoints=waypoints,
+                stroke=style.get("strokeColor", ""),
+            )
+        )
+
+    for edge in page.edges:
+        if edge.source and edge.source in node_map:
+            node_map[edge.source].out_degree += 1
+        if edge.target and edge.target in node_map:
+            node_map[edge.target].in_degree += 1
+
+    return page
+
+
+def parse_file(path: Path) -> list[Page]:
+    xml = load_mxfile(path)
+    _reject_unsafe_xml(xml, path.name)
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError as exc:
+        _fail(f"{path.name}: malformed XML ({exc})")
+    if root.tag == "mxGraphModel":
+        wrapper = ET.Element("diagram", {"name": path.stem, "id": "single"})
+        wrapper.append(root)
+        return [parse_page(wrapper, 0)]
+    diagrams = root.findall(".//diagram")
+    if not diagrams:
+        _fail(f"{path.name}: mxfile contains no <diagram> pages")
+    return [parse_page(d, i) for i, d in enumerate(diagrams)]
+
+
+# --------------------------------------------------------------------------
+# structural analysis — signals, not decisions
+# --------------------------------------------------------------------------
+
+
+def _has_cycle(nodes: list[Node], edges: list[Edge]) -> bool:
+    adjacency: dict[str, list[str]] = {n.id: [] for n in nodes}
+    for edge in edges:
+        if edge.source and edge.target and edge.source in adjacency:
+            adjacency[edge.source].append(edge.target)
+    WHITE, GREY, BLACK = 0, 1, 2
+    color = {n.id: WHITE for n in nodes}
+
+    def visit(start: str) -> bool:
+        stack = [(start, iter(adjacency.get(start, [])))]
+        color[start] = GREY
+        while stack:
+            nid, it = stack[-1]
+            advanced = False
+            for nxt in it:
+                state = color.get(nxt, BLACK)
+                if state == GREY:
+                    return True
+                if state == WHITE:
+                    color[nxt] = GREY
+                    stack.append((nxt, iter(adjacency.get(nxt, []))))
+                    advanced = True
+                    break
+            if not advanced:
+                color[nid] = BLACK
+                stack.pop()
+        return False
+
+    return any(color[n.id] == WHITE and visit(n.id) for n in nodes)
+
+
+def _aligned(boxes: list[Node], tolerance: float = 8.0) -> bool:
+    """True when the boxes stack as lanes — shared left edge or shared top edge."""
+    if len(boxes) < 2:
+        return False
+    same_x = max(n.x for n in boxes) - min(n.x for n in boxes) <= tolerance
+    same_w = max(n.w for n in boxes) - min(n.w for n in boxes) <= tolerance
+    same_y = max(n.y for n in boxes) - min(n.y for n in boxes) <= tolerance
+    same_h = max(n.h for n in boxes) - min(n.h for n in boxes) <= tolerance
+    return (same_x and same_w) or (same_y and same_h)
+
+
+def analyze(page: Page) -> dict[str, Any]:
+    nodes = page.nodes
+    edges = page.edges
+    drawable = [n for n in nodes if n.shape not in ("text",) and (n.label or n.children)]
+    containers = [n for n in nodes if n.children]
+    leaves = [n for n in nodes if not n.children]
+    shapes: dict[str, int] = {}
+    for node in nodes:
+        shapes[shape_family(node.shape)] = shapes.get(shape_family(node.shape), 0) + 1
+
+    def name_of(node: Node) -> str:
+        return (node.label.replace("\n", " · ") or node.id)
+
+    ranked = sorted(
+        leaves, key=lambda n: (n.in_degree + n.out_degree), reverse=True
+    )
+    hubs = [
+        {"id": n.id, "label": name_of(n), "degree": n.in_degree + n.out_degree}
+        for n in ranked[:5]
+        if (n.in_degree + n.out_degree) > 0
+    ]
+    sources = [name_of(n) for n in leaves if n.out_degree and not n.in_degree]
+    sinks = [name_of(n) for n in leaves if n.in_degree and not n.out_degree]
+    orphans = [name_of(n) for n in leaves if not n.in_degree and not n.out_degree]
+
+    # Type candidates, strongest signal first. Advisory only.
+    candidates: list[str] = []
+    if shapes.get("lifeline"):
+        candidates.append("sequence")
+    if shapes.get("table") or shapes.get("er"):
+        candidates.append("er")
+    lanes = [n for n in nodes if n.shape == "swimlane" and n.children]
+    if len(lanes) >= 2 and _aligned(lanes):
+        candidates.append("swimlane")
+    if shapes.get("rhombus"):
+        candidates.append("flowchart")
+    if shapes.get("ellipse", 0) >= max(2, len(leaves) // 3) and edges:
+        candidates.append("state")
+    if any(f in shapes for f in ("aws", "azure", "gcp", "kubernetes", "network")):
+        candidates.append("architecture")
+    if containers and not shapes.get("swimlane"):
+        candidates.append("nested")
+    if edges and not _has_cycle(nodes, edges) and len(sources) == 1:
+        candidates.append("tree")
+    if edges:
+        candidates.append("architecture")
+    if not candidates:
+        candidates.append("architecture")
+
+    seen: set[str] = set()
+    candidates = [c for c in candidates if not (c in seen or seen.add(c))]
+
+    # Collapse candidates: containers whose children are all leaves, and
+    # fan-out clusters — the first things to merge when simplifying.
+    collapsible = [
+        {
+            "id": c.id,
+            "label": name_of(c),
+            "children": len(c.children),
+            "child_labels": [
+                name_of(page.node_map[cid])
+                for cid in c.children
+                if page.node_map.get(cid) and page.node_map[cid].label
+            ][:8],
+        }
+        for c in containers
+        if c.children and all(not page.node_map[cid].children for cid in c.children)
+    ]
+    collapsible.sort(key=lambda c: c["children"], reverse=True)
+
+    return {
+        "nodes_total": len(nodes),
+        "nodes_drawable": len(drawable),
+        "containers": len(containers),
+        "leaves": len(leaves),
+        "edges_total": len(edges),
+        "edges_labeled": sum(1 for e in edges if e.label),
+        "edges_dangling": sum(1 for e in edges if not (e.source and e.target)),
+        "max_depth": max((n.depth for n in nodes), default=0),
+        "shapes": dict(sorted(shapes.items(), key=lambda kv: -kv[1])),
+        "has_cycle": _has_cycle(nodes, edges),
+        "hubs": hubs,
+        "entry_points": sources[:6],
+        "terminals": sinks[:6],
+        "orphans": orphans[:6],
+        "type_candidates": candidates[:3],
+        "collapsible_groups": collapsible[:8],
+        "over_node_budget": len(drawable) > 9,
+        "over_edge_budget": len(edges) > 12,
+    }
+
+
+# --------------------------------------------------------------------------
+# rendering the digest
+# --------------------------------------------------------------------------
+
+
+def page_bounds(page: Page) -> tuple[float, float, float, float]:
+    boxes = [(n.x, n.y, n.x + n.w, n.y + n.h) for n in page.nodes if n.w and n.h]
+    if not boxes:
+        return (0.0, 0.0, 0.0, 0.0)
+    return (
+        min(b[0] for b in boxes),
+        min(b[1] for b in boxes),
+        max(b[2] for b in boxes),
+        max(b[3] for b in boxes),
+    )
+
+
+def digest(path: Path, pages: list[Page], selected: list[Page], max_rows: int) -> str:
+    out: list[str] = []
+    out.append(f"# draw.io IR — {path.name}")
+    out.append("")
+    out.append(
+        f"{len(pages)} page(s): "
+        + ", ".join(f"[{p.index}] {p.name} ({len(p.nodes)}n/{len(p.edges)}e)" for p in pages)
+    )
+    for page in selected:
+        info = analyze(page)
+        x0, y0, x1, y1 = page_bounds(page)
+        out.append("")
+        out.append(f"## Page {page.index} — {page.name}")
+        out.append("")
+        out.append(
+            f"- source canvas: {int(x1 - x0)}×{int(y1 - y0)} px "
+            f"(aspect {((x1 - x0) / (y1 - y0)):.2f})"
+            if y1 > y0
+            else "- source canvas: empty"
+        )
+        out.append(
+            f"- nodes: {info['nodes_total']} total / {info['nodes_drawable']} drawable "
+            f"/ {info['containers']} containers, depth {info['max_depth']}"
+        )
+        out.append(
+            f"- edges: {info['edges_total']} ({info['edges_labeled']} labeled, "
+            f"{info['edges_dangling']} dangling), cycle: {info['has_cycle']}"
+        )
+        out.append(f"- shapes: {info['shapes']}")
+        out.append(f"- type candidates: {', '.join(info['type_candidates'])}")
+        out.append(
+            f"- budget: nodes {'OVER' if info['over_node_budget'] else 'ok'} (max 9), "
+            f"edges {'OVER' if info['over_edge_budget'] else 'ok'} (max 12)"
+        )
+        if info["hubs"]:
+            hubs = ", ".join(f"{h['label'] or h['id']}({h['degree']})" for h in info["hubs"])
+            out.append(f"- hubs (focal candidates): {hubs}")
+        if info["entry_points"]:
+            out.append(f"- entry points: {', '.join(info['entry_points'])}")
+        if info["terminals"]:
+            out.append(f"- terminals: {', '.join(info['terminals'])}")
+        if info["orphans"]:
+            out.append(f"- unconnected: {', '.join(info['orphans'])}")
+        if info["collapsible_groups"]:
+            out.append("- collapsible groups (simplify here first):")
+            for group in info["collapsible_groups"]:
+                kids = ", ".join(group["child_labels"])
+                out.append(f"  - {group['label']} — {group['children']} children: {kids}")
+
+        out.append("")
+        out.append("### Nodes")
+        out.append("")
+        out.append("| id | label | shape | depth | parent | deg | box |")
+        out.append("|---|---|---|---|---|---|---|")
+        listed = [n for n in page.nodes if n.label or n.children]
+        for node in listed[:max_rows]:
+            label = node.label.replace("\n", " ⏎ ").replace("|", "\\|")
+            out.append(
+                f"| {node.id} | {label} | {node.shape} | {node.depth} | "
+                f"{node.parent or '-'} | {node.in_degree}/{node.out_degree} | "
+                f"{int(node.x)},{int(node.y)} {int(node.w)}×{int(node.h)} |"
+            )
+        if len(listed) > max_rows:
+            out.append(f"| … | +{len(listed) - max_rows} more (use --json) | | | | | |")
+
+        out.append("")
+        out.append("### Edges")
+        out.append("")
+        out.append("| source | target | label | style |")
+        out.append("|---|---|---|---|")
+        names = {n.id: (n.label.split("\n")[0] or n.id) for n in page.nodes}
+        for edge in page.edges[:max_rows]:
+            marks = []
+            if edge.dashed:
+                marks.append("dashed")
+            if edge.bidirectional:
+                marks.append("bidir")
+            if edge.undirected:
+                marks.append("undirected")
+            out.append(
+                f"| {names.get(edge.source or '', '?')} | {names.get(edge.target or '', '?')} "
+                f"| {edge.label.replace('|', chr(92) + '|') or '-'} | {' '.join(marks) or '-'} |"
+            )
+        if len(page.edges) > max_rows:
+            out.append(f"| … | +{len(page.edges) - max_rows} more (use --json) | | |")
+    out.append("")
+    return "\n".join(out)
+
+
+def to_json(path: Path, pages: list[Page], selected: list[Page]) -> str:
+    payload = {
+        "source": str(path),
+        "pages_total": len(pages),
+        "pages": [
+            {
+                "id": p.id,
+                "name": p.name,
+                "index": p.index,
+                "bounds": dict(zip(("x0", "y0", "x1", "y1"), page_bounds(p))),
+                "analysis": analyze(p),
+                "nodes": [asdict(n) for n in p.nodes],
+                "edges": [asdict(e) for e in p.edges],
+            }
+            for p in selected
+        ],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def select_pages(pages: list[Page], selector: str | None) -> list[Page]:
+    if selector is None:
+        return pages if len(pages) == 1 else pages[:1]
+    if selector == "all":
+        return pages
+    if selector.isdigit():
+        index = int(selector)
+        match = [p for p in pages if p.index == index]
+        if not match:
+            _fail(f"no page with index {index} (have 0..{len(pages) - 1})")
+        return match
+    match = [p for p in pages if p.name.lower() == selector.lower()]
+    if not match:
+        names = ", ".join(p.name for p in pages)
+        _fail(f"no page named {selector!r} (have: {names})")
+    return match
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("file", help=".drawio / .xml / .drawio.png / .drawio.svg")
+    parser.add_argument(
+        "--page",
+        help="page index, page name, or 'all' (default: first page)",
+    )
+    parser.add_argument("--json", action="store_true", help="emit the full IR as JSON")
+    parser.add_argument(
+        "--max-rows",
+        type=int,
+        default=40,
+        help="rows per table in the Markdown digest (default 40)",
+    )
+    parser.add_argument("--out", help="write to this path instead of stdout")
+    args = parser.parse_args(argv)
+
+    if args.max_rows < 1:
+        parser.error("--max-rows must be at least 1")
+
+    path = Path(args.file)
+    if not path.is_file():
+        _fail(f"{path}: no such file")
+
+    pages = parse_file(path)
+    selected = select_pages(pages, args.page)
+    text = (
+        to_json(path, pages, selected)
+        if args.json
+        else digest(path, pages, selected, args.max_rows)
+    )
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote {args.out} ({len(text)} bytes)")
+    else:
+        sys.stdout.write(text if text.endswith("\n") else text + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())