spolvero 0.3.0__py3-none-any.whl

spolvero/ir.py

@@ -0,0 +1,248 @@
+"""Normalized IR generation and Mermaid flowchart parsing."""
+
+from __future__ import annotations
+
+import html
+import re
+from typing import Any
+
+from spolvero.constants import SCHEMA_VERSION
+from spolvero.models import DiagramSource
+from spolvero.source import first_significant_line
+
+
+def normalize_diagram(diagram: DiagramSource) -> dict[str, Any]:
+    if diagram.source_type == "mermaid_flowchart":
+        return parse_mermaid_flowchart(diagram)
+    if diagram.source_type and diagram.source_type.startswith("topology"):
+        from spolvero.topology import parse_topology
+
+        return parse_topology(diagram)
+    warnings = list(diagram.warnings)
+    warnings.append("No normalized native-shape IR was produced for this source type.")
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "id": diagram.id,
+        "title": diagram.title,
+        "diagram_type": "reference",
+        "orientation": "unknown",
+        "pages": [{"id": "page-001", "title": diagram.title, "size": "Letter Landscape"}],
+        "nodes": [],
+        "edges": [],
+        "containers": [],
+        "warnings": list(dict.fromkeys(warnings)),
+    }
+
+
+def parse_mermaid_flowchart(diagram: DiagramSource) -> dict[str, Any]:
+    lines = diagram.text.splitlines()
+    first = first_significant_line(diagram.text)
+    orientation = "top_down"
+    direction_match = re.match(r"^(?:flowchart|graph)\s+([A-Za-z]{2})\b", first, re.IGNORECASE)
+    if direction_match:
+        direction = direction_match.group(1).upper()
+        if direction in {"LR", "RL"}:
+            orientation = "left_to_right"
+        elif direction in {"TD", "TB", "BT"}:
+            orientation = "top_down"
+
+    nodes: dict[str, dict[str, Any]] = {}
+    edges: list[dict[str, Any]] = []
+    containers: dict[str, dict[str, Any]] = {}
+    warnings: list[str] = []
+    container_stack: list[str] = []
+    ref_file = diagram.origin_file or diagram.source_file or f"{diagram.id}.mmd"
+
+    def current_container() -> str:
+        return container_stack[-1] if container_stack else ""
+
+    def upsert_node(endpoint: str, source_ref: str) -> str:
+        node_id, label, shape_kind = parse_mermaid_endpoint(endpoint)
+        if not node_id:
+            fallback_id = f"N{len(nodes) + 1:03d}"
+            warnings.append(f"Could not parse node endpoint '{endpoint}' at {source_ref}; assigned {fallback_id}.")
+            node_id, label, shape_kind = fallback_id, endpoint.strip(), "process"
+        if node_id not in nodes:
+            nodes[node_id] = {
+                "id": node_id,
+                "label": label or node_id,
+                "shape_kind": shape_kind,
+                "container": current_container(),
+                "metadata": {"source_ref": source_ref},
+            }
+        else:
+            if label and nodes[node_id]["label"] == node_id:
+                nodes[node_id]["label"] = label
+            if shape_kind != "process":
+                nodes[node_id]["shape_kind"] = shape_kind
+            if current_container() and not nodes[node_id].get("container"):
+                nodes[node_id]["container"] = current_container()
+        return node_id
+
+    for offset, raw_line in enumerate(lines, start=diagram.line_offset):
+        for statement in split_mermaid_statements(raw_line):
+            stripped = strip_mermaid_comment(statement).strip()
+            if not stripped:
+                continue
+            if re.match(r"^(flowchart|graph)\b", stripped, re.IGNORECASE):
+                continue
+            source_ref = f"{ref_file}:{offset}"
+            lower = stripped.lower()
+            if lower.startswith("subgraph "):
+                container_id, container_label = parse_subgraph(stripped)
+                container_stack.append(container_id)
+                containers[container_id] = {"id": container_id, "label": container_label, "kind": "swimlane"}
+                continue
+            if lower == "end":
+                if container_stack:
+                    container_stack.pop()
+                else:
+                    warnings.append(f"Unexpected Mermaid subgraph end at {source_ref}.")
+                continue
+            if lower.startswith(("classdef ", "class ", "style ", "linkstyle ", "click ")):
+                warnings.append(f"Skipped Mermaid styling/directive at {source_ref}: {stripped}")
+                continue
+
+            edge = parse_mermaid_edge(stripped)
+            if edge:
+                src_id = upsert_node(edge["src"], source_ref)
+                dst_id = upsert_node(edge["dst"], source_ref)
+                edges.append(
+                    {
+                        "id": f"E{len(edges) + 1:03d}",
+                        "from": src_id,
+                        "to": dst_id,
+                        "label": edge.get("label", ""),
+                        "kind": "dynamic_connector",
+                        "metadata": {"source_ref": source_ref, "mermaid_arrow": edge.get("arrow", "-->")},
+                    }
+                )
+                if looks_like_chained_endpoint(edge["dst"]):
+                    warnings.append(f"Chained edge may require manual review at {source_ref}: {stripped}")
+                continue
+
+            node_id, _, _ = parse_mermaid_endpoint(stripped)
+            if node_id:
+                upsert_node(stripped, source_ref)
+            else:
+                warnings.append(f"Skipped unsupported Mermaid statement at {source_ref}: {stripped}")
+
+    if container_stack:
+        warnings.append("One or more Mermaid subgraphs were not closed with `end`.")
+    if not nodes:
+        warnings.append("No nodes were recognized in the Mermaid flowchart.")
+    if not edges:
+        warnings.append("No edges were recognized in the Mermaid flowchart.")
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "id": diagram.id,
+        "title": diagram.title,
+        "diagram_type": "flowchart",
+        "orientation": orientation,
+        "pages": [{"id": "page-001", "title": diagram.title, "size": "Letter Landscape"}],
+        "nodes": list(nodes.values()),
+        "edges": edges,
+        "containers": list(containers.values()),
+        "warnings": list(dict.fromkeys(diagram.warnings + warnings)),
+    }
+
+
+def split_mermaid_statements(line: str) -> list[str]:
+    stripped = line.strip()
+    if not stripped:
+        return []
+    return [part for part in stripped.split(";") if part.strip()]
+
+
+def strip_mermaid_comment(line: str) -> str:
+    stripped = line.strip()
+    if stripped.startswith("%%"):
+        return ""
+    if "%%" in line:
+        return line.split("%%", 1)[0]
+    return line
+
+
+def parse_subgraph(statement: str) -> tuple[str, str]:
+    rest = statement.split(None, 1)[1].strip()
+    bracket_match = re.match(r"(?P<id>[A-Za-z0-9_.$:/-]+)?\s*\[(?P<label>.+)\]$", rest)
+    if bracket_match:
+        label = clean_label(bracket_match.group("label"))
+        raw_id = bracket_match.group("id") or label
+        return sanitize_id(raw_id), label
+    return sanitize_id(rest), clean_label(rest)
+
+
+def parse_mermaid_edge(statement: str) -> dict[str, str] | None:
+    patterns = [
+        (r"^(?P<src>.+?)\s*-->\|(?P<label>.*?)\|\s*(?P<dst>.+)$", "-->"),
+        (r"^(?P<src>.+?)\s*--\s*(?P<label>.*?)\s*-->\s*(?P<dst>.+)$", "-->"),
+        (r"^(?P<src>.+?)\s*-->\s*(?P<dst>.+)$", "-->"),
+        (r"^(?P<src>.+?)\s*---\|(?P<label>.*?)\|\s*(?P<dst>.+)$", "---"),
+        (r"^(?P<src>.+?)\s*---\s*(?P<dst>.+)$", "---"),
+        (r"^(?P<src>.+?)\s*==>\|(?P<label>.*?)\|\s*(?P<dst>.+)$", "==>"),
+        (r"^(?P<src>.+?)\s*==\s*(?P<label>.*?)\s*==>\s*(?P<dst>.+)$", "==>"),
+        (r"^(?P<src>.+?)\s*==>\s*(?P<dst>.+)$", "==>"),
+        (r"^(?P<src>.+?)\s*-\.\->\|(?P<label>.*?)\|\s*(?P<dst>.+)$", "-.->"),
+        (r"^(?P<src>.+?)\s*-\.\s*(?P<label>.*?)\s*-\.\->\s*(?P<dst>.+)$", "-.->"),
+        (r"^(?P<src>.+?)\s*-\.\->\s*(?P<dst>.+)$", "-.->"),
+    ]
+    for pattern, arrow in patterns:
+        match = re.match(pattern, statement)
+        if match:
+            return {
+                "src": match.group("src").strip(),
+                "dst": match.group("dst").strip(),
+                "label": clean_label(match.groupdict().get("label", "") or ""),
+                "arrow": arrow,
+            }
+    return None
+
+
+def looks_like_chained_endpoint(endpoint: str) -> bool:
+    return any(token in endpoint for token in (" --> ", "-->", " --- ", "---", "==>", "-.->"))
+
+
+def parse_mermaid_endpoint(endpoint: str) -> tuple[str, str, str]:
+    token = endpoint.strip()
+    token = re.sub(r"\s*:::[A-Za-z0-9_-]+$", "", token)
+    token = token.strip()
+    node_id = r"(?P<id>[A-Za-z0-9_.$:/-]+)"
+    patterns = [
+        (rf"^{node_id}\s*\(\[(?P<label>.+)\]\)$", "terminator"),
+        (rf"^{node_id}\s*\[\((?P<label>.+)\)\]$", "database"),
+        (rf"^{node_id}\s*\[\[(?P<label>.+)\]\]$", "subprocess"),
+        (rf"^{node_id}\s*\[/(?P<label>.+)/\]$", "data_io"),
+        (rf"^{node_id}\s*\[\\(?P<label>.+)\\\]$", "data_io"),
+        (rf"^{node_id}\s*\{{\{{(?P<label>.+)\}}\}}$", "decision"),
+        (rf"^{node_id}\s*\{{(?P<label>.+)\}}$", "decision"),
+        (rf"^{node_id}\s*\(\((?P<label>.+)\)\)$", "circle"),
+        (rf"^{node_id}\s*\((?P<label>.+)\)$", "rounded"),
+        (rf"^{node_id}\s*>\s*(?P<label>.+)\]$", "document"),
+        (rf"^{node_id}\s*\[(?P<label>.+)\]$", "process"),
+    ]
+    for pattern, shape_kind in patterns:
+        match = re.match(pattern, token)
+        if match:
+            return match.group("id"), clean_label(match.group("label")), shape_kind
+    if re.match(r"^[A-Za-z0-9_.$:/-]+$", token):
+        return token, token, "process"
+    return "", clean_label(token), "process"
+
+
+def clean_label(label: str) -> str:
+    label = label.strip()
+    if (label.startswith('"') and label.endswith('"')) or (label.startswith("'") and label.endswith("'")):
+        label = label[1:-1]
+    return html.unescape(label.replace("<br/>", " ").replace("<br>", " ").strip())
+
+
+def sanitize_id(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9_.-]+", "_", clean_label(value)).strip("_")
+    return cleaned or "container"
+
+
+def is_flowchart_ir(ir: dict[str, Any]) -> bool:
+    return ir.get("diagram_type") == "flowchart" and bool(ir.get("nodes"))
+

spolvero/models.py

@@ -0,0 +1,19 @@
+"""Data models used across package generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DiagramSource:
+    id: str
+    title: str
+    language: str
+    source_type: str
+    text: str
+    line_offset: int = 1
+    source_file: str = ""
+    origin_file: str = ""
+    warnings: list[str] = field(default_factory=list)
+