xg-cli 1.0__py3-none-any.whl

xg/tui/diagrams/__init__.py

@@ -0,0 +1,22 @@
+"""Dependency-free Mermaid flowchart support for the TUI."""
+
+from xg.tui.diagrams.markdown import MermaidBlock, split_mermaid_blocks
+from xg.tui.diagrams.layout import FlowchartLayout, LayoutNode, layout_flowchart
+from xg.tui.diagrams.model import FlowchartEdge, FlowchartModel, FlowchartNode
+from xg.tui.diagrams.parser import FlowchartParseError, parse_flowchart
+from xg.tui.diagrams.renderer import DiagramRender, render_flowchart
+
+__all__ = [
+    "FlowchartEdge",
+    "FlowchartLayout",
+    "FlowchartModel",
+    "FlowchartNode",
+    "DiagramRender",
+    "FlowchartParseError",
+    "LayoutNode",
+    "MermaidBlock",
+    "parse_flowchart",
+    "layout_flowchart",
+    "render_flowchart",
+    "split_mermaid_blocks",
+]

xg/tui/diagrams/layout.py

@@ -0,0 +1,110 @@
+"""Stable, bounded layout for the supported Mermaid flowchart model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from xg.tui.diagrams.model import FlowchartModel
+
+
+@dataclass(frozen=True)
+class LayoutNode:
+    """A node position in a rank/row layout."""
+
+    node_id: str
+    rank: int
+    order: int
+
+
+@dataclass(frozen=True)
+class FlowchartLayout:
+    """Deterministic placement metadata used by the text renderer."""
+
+    nodes: tuple[LayoutNode, ...]
+    ranks: tuple[tuple[str, ...], ...]
+    cyclic: bool = False
+
+    def position(self, node_id: str) -> LayoutNode:
+        for node in self.nodes:
+            if node.node_id == node_id:
+                return node
+        raise KeyError(node_id)
+
+
+def layout_flowchart(
+    model: FlowchartModel,
+    *,
+    max_iterations: int | None = None,
+    rank_by_node: dict[str, int] | None = None,
+) -> FlowchartLayout:
+    """Assign nodes to stable layers without an unbounded graph traversal.
+
+    DAGs use the longest known predecessor rank.  For cyclic graphs the same
+    relaxation is capped at ``node_count`` iterations and the remaining nodes
+    keep their stable source order.  This is deliberately small and
+    predictable rather than a full Mermaid-compatible layout engine.
+    """
+    node_ids = [node.id for node in model.nodes]
+    index = {node_id: i for i, node_id in enumerate(node_ids)}
+    incoming: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
+    for edge in model.edges:
+        if edge.source in incoming and edge.target in incoming:
+            incoming[edge.target].append(edge.source)
+
+    limit = max_iterations if max_iterations is not None else max(1, len(node_ids))
+    ranks = {node_id: 0 for node_id in node_ids}
+    if rank_by_node is not None:
+        # Callers such as Plan already have a business-level batch partition.
+        # Honor it while retaining a safe default for omitted nodes.
+        ranks.update({node_id: rank for node_id, rank in rank_by_node.items() if node_id in ranks and rank >= 0})
+        grouped: dict[int, list[str]] = {}
+        for node_id in node_ids:
+            grouped.setdefault(ranks[node_id], []).append(node_id)
+        ordered_ranks = sorted(grouped)
+        if model.direction in ("BT", "RL"):
+            ordered_ranks.reverse()
+        rank_lists = [tuple(grouped[rank]) for rank in ordered_ranks]
+        positions = tuple(
+            LayoutNode(node_id=node_id, rank=rank_no, order=order)
+            for rank_no, rank_nodes in enumerate(rank_lists)
+            for order, node_id in enumerate(rank_nodes)
+        )
+        return FlowchartLayout(nodes=positions, ranks=tuple(rank_lists), cyclic=False)
+
+    changed = False
+    for _ in range(limit):
+        changed = False
+        for node_id in node_ids:
+            predecessors = incoming[node_id]
+            if not predecessors:
+                continue
+            candidate = max(ranks[pred] + 1 for pred in predecessors)
+            if candidate > ranks[node_id]:
+                ranks[node_id] = candidate
+                changed = True
+        if not changed:
+            break
+
+    cyclic = changed
+    # A cycle can make the relaxation increase every rank on every pass. Keep
+    # it bounded and collapse the inflated ranks to a useful stable layout.
+    if cyclic:
+        ranks = {node_id: 0 for node_id in node_ids}
+        for node_id in node_ids:
+            predecessors = [p for p in incoming[node_id] if index[p] < index[node_id]]
+            ranks[node_id] = min(1, max((ranks[p] + 1 for p in predecessors), default=0))
+
+    grouped: dict[int, list[str]] = {}
+    for node_id in node_ids:
+        grouped.setdefault(ranks[node_id], []).append(node_id)
+    ordered_ranks = sorted(grouped)
+    if model.direction in ("BT", "RL"):
+        ordered_ranks.reverse()
+
+    rank_lists = [tuple(grouped[rank]) for rank in ordered_ranks]
+    positions = tuple(
+        LayoutNode(node_id=node_id, rank=rank_no, order=order)
+        for rank_no, rank_nodes in enumerate(rank_lists)
+        for order, node_id in enumerate(rank_nodes)
+    )
+    return FlowchartLayout(nodes=positions, ranks=tuple(rank_lists), cyclic=cyclic)

xg/tui/diagrams/markdown.py

@@ -0,0 +1,39 @@
+"""Recognize complete Mermaid fenced blocks without parsing Markdown globally."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MermaidBlock:
+    source: str
+    start: int
+    end: int
+
+
+_FENCE_RE = re.compile(
+    r"```[ \t]*mermaid[ \t]*\r?\n(?P<body>.*?)(?P<fence>```)[ \t]*(?:\r?\n|$)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def split_mermaid_blocks(text: str) -> list[tuple[str, MermaidBlock | None]]:
+    """Split text into ``("text", None)`` and complete Mermaid blocks.
+
+    An unclosed fence is deliberately returned as ordinary text.  This keeps
+    streaming assistant output visible as source until the fence is complete.
+    """
+    parts: list[tuple[str, MermaidBlock | None]] = []
+    cursor = 0
+    for match in _FENCE_RE.finditer(text):
+        if match.start() > cursor:
+            parts.append((text[cursor : match.start()], None))
+        parts.append((match.group("body"), MermaidBlock(
+            source=match.group("body"), start=match.start(), end=match.end()
+        )))
+        cursor = match.end()
+    if cursor < len(text):
+        parts.append((text[cursor:], None))
+    return parts or [(text, None)]

xg/tui/diagrams/model.py

@@ -0,0 +1,36 @@
+"""Pure data structures for the supported Mermaid flowchart subset."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+Direction = Literal["TD", "TB", "BT", "LR", "RL"]
+NodeShape = Literal["rect", "round", "diamond", "circle"]
+EdgeStyle = Literal["solid", "dotted", "thick"]
+
+
+@dataclass
+class FlowchartNode:
+    id: str
+    label: str
+    shape: NodeShape = "rect"
+
+
+@dataclass
+class FlowchartEdge:
+    source: str
+    target: str
+    label: str = ""
+    style: EdgeStyle = "solid"
+    arrow: bool = True
+
+
+@dataclass
+class FlowchartModel:
+    direction: Direction = "TD"
+    nodes: list[FlowchartNode] = field(default_factory=list)
+    edges: list[FlowchartEdge] = field(default_factory=list)
+    source: str = ""
+    warnings: list[str] = field(default_factory=list)

xg/tui/diagrams/parser.py

@@ -0,0 +1,119 @@
+"""Small, safe parser for the common Mermaid flowchart syntax."""
+
+from __future__ import annotations
+
+import html
+import re
+
+from xg.tui.diagrams.model import FlowchartEdge, FlowchartModel, FlowchartNode
+
+
+class FlowchartParseError(ValueError):
+    """The source is not a supported flowchart subset."""
+
+
+_HEADER_RE = re.compile(r"^(?:flowchart|graph)(?:\s+(TD|TB|BT|LR|RL))?\s*$", re.IGNORECASE)
+_NODE_RE = re.compile(
+    r"\s*(?P<id>[A-Za-z_][\w-]*)"
+    r"(?P<body>\(\([^\n()]*\)\)|\[[^\n\]]*\]|\([^\n()]*\)|\{[^\n}]*\}|>[^\n\]]*\])?"
+)
+_PIPE_LABEL_RE = re.compile(r"\|(?P<label>[^|]*)\|")
+_EDGE_OPS = ("-.->", "==>", "-->", "---")
+
+
+def _clean_label(value: str) -> str:
+    value = html.unescape(value.replace("<br/>", "\n").replace("<br>", "\n"))
+    value = re.sub(r"<[^>]+>", "", value)
+    return value.strip()
+
+
+def _node_parts(node_id: str, body: str | None) -> tuple[str, str]:
+    if not body:
+        return node_id, "rect"
+    if body.startswith("(("):
+        return _clean_label(body[2:-2]) or node_id, "circle"
+    if body.startswith("["):
+        return _clean_label(body[1:-1]) or node_id, "rect"
+    if body.startswith("("):
+        return _clean_label(body[1:-1]) or node_id, "round"
+    if body.startswith("{"):
+        return _clean_label(body[1:-1]) or node_id, "diamond"
+    if body.startswith(">"):  # Mermaid flag shape: >label]
+        return _clean_label(body[1:-1]) or node_id, "rect"
+    return node_id, "rect"
+
+
+def parse_flowchart(source: str, *, max_nodes: int = 80, max_edges: int = 160, max_label_chars: int = 120) -> FlowchartModel:
+    """Parse a bounded subset of ``flowchart`` / ``graph`` Mermaid syntax."""
+    lines = [line.strip() for line in source.splitlines() if line.strip() and not line.lstrip().startswith("%%")]
+    if not lines:
+        raise FlowchartParseError("flowchart 内容为空")
+    header = _HEADER_RE.fullmatch(lines[0])
+    if not header:
+        raise FlowchartParseError("只支持 flowchart/graph 语法及 TD/TB/BT/LR/RL 方向")
+    direction = (header.group(1) or "TD").upper()
+    model = FlowchartModel(direction=direction, source=source)
+    nodes: dict[str, FlowchartNode] = {}
+
+    def ensure_node(node_id: str, body: str | None) -> None:
+        label, shape = _node_parts(node_id, body)
+        if len(label) > max_label_chars:
+            label = label[:max_label_chars] + "…"
+            model.warnings.append(f"节点 {node_id} 标签已截断")
+        existing = nodes.get(node_id)
+        if existing is None:
+            if len(nodes) >= max_nodes:
+                raise FlowchartParseError(f"节点数超过上限 {max_nodes}")
+            nodes[node_id] = FlowchartNode(id=node_id, label=label, shape=shape)  # type: ignore[arg-type]
+        elif body:
+            existing.label = label
+            existing.shape = shape  # type: ignore[assignment]
+
+    def parse_node(text: str, pos: int) -> tuple[str, str | None, int]:
+        match = _NODE_RE.match(text, pos)
+        if not match:
+            raise FlowchartParseError(f"无法解析节点：{text[pos:].strip()[:80]}")
+        return match.group("id"), match.group("body"), match.end()
+
+    for line_no, line in enumerate(lines[1:], 2):
+        if line.lower().startswith("subgraph") or line.lower().startswith("end"):
+            raise FlowchartParseError(f"第 {line_no} 行不支持 subgraph")
+        for statement in (part.strip() for part in line.split(";") if part.strip()):
+            pos = 0
+            source_id, source_body, pos = parse_node(statement, pos)
+            ensure_node(source_id, source_body)
+            while pos < len(statement):
+                rest = statement[pos:].lstrip()
+                pos = len(statement) - len(rest)
+                label = ""
+                style = "solid"
+                op = next((candidate for candidate in _EDGE_OPS if rest.startswith(candidate)), None)
+                if op is not None:
+                    pos += len(op)
+                    style = "dotted" if op == "-.->" else "thick" if op == "==>" else "solid"
+                    label_match = _PIPE_LABEL_RE.match(statement, pos)
+                    if label_match:
+                        label = _clean_label(label_match.group("label"))
+                        pos = label_match.end()
+                elif rest.startswith("--"):
+                    # Support the readable form: A -- label --> B.
+                    end = rest.find("-->", 2)
+                    if end < 0:
+                        raise FlowchartParseError(f"第 {line_no} 行的连线不完整")
+                    label = _clean_label(rest[2:end])
+                    pos += end + 3
+                else:
+                    raise FlowchartParseError(f"第 {line_no} 行存在不支持的语法：{rest[:80]}")
+                target_id, target_body, pos = parse_node(statement, pos)
+                ensure_node(target_id, target_body)
+                if len(model.edges) >= max_edges:
+                    raise FlowchartParseError(f"连线数超过上限 {max_edges}")
+                model.edges.append(FlowchartEdge(
+                    source=source_id, target=target_id, label=label,
+                    style=style, arrow=True,  # type: ignore[arg-type]
+                ))
+                source_id = target_id
+    model.nodes = list(nodes.values())
+    if not model.nodes:
+        raise FlowchartParseError("没有找到节点")
+    return model