termrender 4.6.0__tar.gz → 4.6.1__tar.gz

{termrender-4.6.0 → termrender-4.6.1}/CHANGELOG.md

@@ -1,6 +1,48 @@
 # CHANGELOG
 
 
+## v4.6.1 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid-flow**: Parse chained edges and bracket-aware tokenization
+  ([`5040b96`](https://github.com/crouton-labs/termrender/commit/5040b967bbe75c70c6d03d57930742ba020e3333))
+
+- Unify edge parsing behind one bracket-depth-aware connector scanner (_scan_connectors) shared with
+  & fan-out splitting and ; statement splitting, replacing the single-connector _EDGE_RE. -
+  CRITICAL: chained edge statements (A-->B-->C) now parse as a sequence of node groups separated by
+  connectors, emitting one edge per adjacent triple instead of dropping the tail after the first
+  connector. - MAJOR: connector-looking text inside [], (), {} labels (A[Go --> Fast]) is no longer
+  mistaken for an edge connector. - MINOR: semicolons inside labels (A[Check; validate]) no longer
+  split the statement.
+
+Adds structural tests for 2/3-link chains, mixed-style chains, chain with inline label,
+  connector-in-label for all three connector families, and semicolon-in-label. Adds a chained-form
+  golden for the labeled back-edge cycle proving identical render to the separate-line form.
+
+### Testing
+
+- Add flowchart golden corpus and go-binary parity harness
+  ([`2a5a00a`](https://github.com/crouton-labs/termrender/commit/2a5a00aba18195eac987bc8c202a80724d6e43c9))
+
+- tests/test_mermaid_flow_corpus.py: 26 golden-output tests pinning exact render_flowchart() lines
+  across all 9 node shapes, every edge style (solid/dotted/thick/headless/bidirectional), both label
+  forms, & fan-out, a multi-parent DAG, a labeled-back-edge cycle (the case the vendored Go binary
+  panics/mis-parses on), LR vs TD, subgraph + nested subgraph, a long label vs a tight width budget,
+  and the two degradation paths. - scripts/mermaid_flow_parity.py: standalone parity harness (not a
+  pytest dependency) that invokes the vendored Go binary the way termrender's real dispatch path
+  does (preprocess_mermaid_for_ascii + fix_mermaid_encoding) and the native renderer side by side
+  across 14 representative inputs, writing the comparison to the orchestrator's shared context dir.
+  Confirms parity-or-better plus two Go failure modes the native renderer avoids: a self-loop panic
+  (index out of range) and labeled-back-edge mis-parsing (label text swallowed into a phantom node
+  instead of a back-edge). - fix: mermaid_flow.py's module docstring described a stale prior phase
+  ("every shape renders as a plain rectangle", "subgraphs parse but aren't drawn as frames") — both
+  are false now; corrected to describe actual current behavior (distinct shape borders, framed
+  subgraphs with contiguous-membership flattening).
+
+463 tests green (437 pre-existing + 26 new corpus).
+
+
 ## v4.6.0 (2026-07-06)
 
 ### Features

{termrender-4.6.0 → termrender-4.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.6.0
+Version: 4.6.1
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender

termrender-4.6.1/scripts/mermaid_flow_parity.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Standalone parity harness: native flowchart renderer vs. the vendored Go
+binary, for a curated set of representative mermaid flowchart sources.
+
+Not a pytest test and not imported by the test suite — the corpus tests must
+not depend on the vendored ``mermaid-ascii`` binary being present on disk.
+Run this once (locally, wherever the vendored binary for the host platform
+exists) to (re)generate the side-by-side comparison artifact:
+
+    .venv/bin/python scripts/mermaid_flow_parity.py
+
+Invokes the Go binary exactly the way termrender's real dispatch path does
+(``mermaid.py::_render_via_binary``): run ``preprocess_mermaid_for_ascii``
+(flowchart shape normalization) on the source, shell out to
+``mermaid_ascii_bin()`` with ``-f - -y 1``, and undo its Latin-1
+double-encoding via ``fix_mermaid_encoding`` — so the comparison is fair
+(same preprocessing termrender actually applies before falling back to the
+binary today).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from termrender._mermaid_bin import mermaid_ascii_bin
+from termrender.renderers.mermaid import fix_mermaid_encoding, preprocess_mermaid_for_ascii
+from termrender.renderers.mermaid_flow import render_flowchart
+
+OUTPUT_PATH = Path(
+    "/Users/silasrhyneer/.crouter/canvas/nodes/mr9swads-0f62d05c/context/flow-parity-sample.md"
+)
+
+WIDTH = 60
+
+CASES: list[tuple[str, str]] = [
+    (
+        "Simple forward DAG",
+        "graph TD\nA-->B\nA-->C\n",
+    ),
+    (
+        "Multi-parent DAG",
+        "graph TD\nA-->C\nB-->C\n",
+    ),
+    (
+        "Headless edge (`---`)",
+        "graph TD\nA---B\n",
+    ),
+    (
+        "Pipe-labeled edge",
+        "graph TD\nA-->|hi|B\n",
+    ),
+    (
+        "Inline-labeled edge",
+        "graph TD\nA -- go now --> B\n",
+    ),
+    (
+        "`&` fan-out",
+        "graph TD\nA & B --> C & D\n",
+    ),
+    (
+        "Non-rect shapes (diamond, circle, cylinder)",
+        "graph TD\nA{Decision}-->B((Circle))\nB-->C[(DB)]\n",
+    ),
+    (
+        "LR direction",
+        "graph LR\nA-->B\nA-->C\n",
+    ),
+    (
+        "Subgraph frame",
+        "graph TD\nsubgraph zone[Zone]\nA-->B\nend\n",
+    ),
+    (
+        "Plain 3-cycle (no label)",
+        "graph TD\nA-->B\nB-->C\nC-->A\n",
+    ),
+    (
+        "Self-loop (Go binary PANICS: index out of range in drawLine)",
+        "graph TD\nA-->A\n",
+    ),
+    (
+        "Cycle with a LABELED back-edge (Go binary mis-parses the label as "
+        "a phantom node — wrong topology; this is the case the requirements "
+        "doc calls out as the one the Go binary cannot handle)",
+        "graph TD\nA-->B\nB-->C\nC-->|retry|A\n",
+    ),
+    (
+        "Same labeled-back-edge cycle, spaced arrows (Go binary still "
+        "fabricates a phantom 4th node '|retry| A' instead of a back-edge "
+        "into A — the label-parsing bug is not a whitespace quirk)",
+        "graph TD\nA --> B\nB --> C\nC --> |retry| A\n",
+    ),
+    (
+        "Simple forward DAG, spaced arrows (Go binary's own preferred "
+        "form — included so the unspaced cases above are judged fairly "
+        "against Go's best case, not just its worst case)",
+        "graph TD\nA --> B\nA --> C\n",
+    ),
+]
+
+
+def render_via_go_binary(source: str) -> tuple[str, bool]:
+    """Return (rendered_text, panicked). Mirrors mermaid.py::_render_via_binary
+    but surfaces panic/failure explicitly instead of silently echoing source
+    (the harness wants to *show* the failure, not hide it)."""
+    try:
+        result = subprocess.run(
+            [mermaid_ascii_bin(), "-f", "-", "-y", "1"],
+            input=preprocess_mermaid_for_ascii(source),
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as exc:
+        return f"[harness error invoking binary: {exc}]", True
+
+    if result.returncode != 0:
+        stderr_tail = "\n".join(result.stderr.strip().splitlines()[:4])
+        return f"PANIC (exit {result.returncode}):\n{stderr_tail}", True
+
+    return fix_mermaid_encoding(result.stdout), False
+
+
+def main() -> None:
+    sections: list[str] = [
+        "# Native flowchart renderer vs. Go `mermaid-ascii` — parity sample",
+        "",
+        "Generated by `scripts/mermaid_flow_parity.py`. The Go binary is",
+        "invoked exactly the way termrender's real dispatch path does today",
+        "(`mermaid.py::_render_via_binary`): flowchart shape normalization via",
+        "`preprocess_mermaid_for_ascii`, then `mermaid-ascii -f - -y 1`, then",
+        "`fix_mermaid_encoding` on the output.",
+        "",
+    ]
+
+    for title, source in CASES:
+        go_text, panicked = render_via_go_binary(source)
+        our_lines = render_flowchart(source, WIDTH)
+        our_text = "\n".join(our_lines)
+
+        sections.append(f"## {title}")
+        sections.append("")
+        sections.append("Mermaid source:")
+        sections.append("```")
+        sections.append(source.rstrip("\n"))
+        sections.append("```")
+        sections.append("")
+        sections.append(f"Go binary output{' (PANIC/failure)' if panicked else ''}:")
+        sections.append("```")
+        sections.append(go_text if go_text.strip() else "(empty)")
+        sections.append("```")
+        sections.append("")
+        sections.append("Native `render_flowchart` output:")
+        sections.append("```")
+        sections.append(our_text if our_text.strip() else "(empty)")
+        sections.append("```")
+        sections.append("")
+
+    OUTPUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT_PATH.write_text("\n".join(sections) + "\n")
+    print(f"wrote {OUTPUT_PATH}")
+
+
+if __name__ == "__main__":
+    main()

{termrender-4.6.0 → termrender-4.6.1}/src/termrender/renderers/mermaid_flow.py

@@ -25,19 +25,25 @@ Grammar supported
 Header: ``graph``/``flowchart`` + direction (``TD``/``TB``/``LR``/``RL``/
 ``BT``). Node shapes: ``[rect]``, ``(round)``, ``([stadium])``,
 ``[(cylinder)]``, ``((circle))``, ``{diamond}``, ``{{hexagon}}``,
-``[[subroutine]]``, ``[/parallelogram/]`` — this phase renders every shape
-as a plain rectangle (distinct shape borders are a later phase; only the
-label text is load-bearing here). Edges: ``-->``, ``---``, ``-.->``, ``==>``
-(and bidirectional forms), with ``|label|`` and inline ``A -- text --> B``
-labels, and ``&`` fan-out. ``subgraph ... end`` blocks parse but are not yet
-rendered as frames (nodes inside them still place and render normally).
-``class``/``classDef``/``style``/``click``/``linkStyle`` lines are ignored.
+``[[subroutine]]``, ``[/parallelogram/]`` — each renders with a distinct
+shape-specific border (diamond/parallelogram slant tapers, round/stadium/
+circle rounded corners, a cylinder's rounded cap over a square base, a
+hexagon's cut corners, a subroutine's double-bar sides); only a shape whose
+box is too small for its own drawer falls back to the plain rectangle
+border. Edges: ``-->``, ``---``, ``-.->``, ``==>`` (and bidirectional
+forms), with ``|label|`` and inline ``A -- text --> B`` labels, and ``&``
+fan-out. ``subgraph ... end`` blocks (including nested subgraphs) render as
+enclosing frames with a left-anchored title when their members place
+contiguously enough for a clean rect; otherwise a block flattens (no frame,
+members still placed and drawn) rather than draw a frame that would
+visually claim a non-member node. ``class``/``classDef``/``style``/
+``click``/``linkStyle`` lines are ignored.
 
 Known degradations (by design, not bugs)
 -----------------------------------------
-- Node shapes other than a plain rectangle border are not yet visually
-  distinct (Phase 4 of this renderer's build).
-- Subgraph blocks parse but are not yet drawn as enclosing frames (Phase 4).
+- A subgraph whose members aren't placed contiguously enough for a clean
+  enclosing rect flattens (drops its frame and title) rather than draw a
+  frame that visually claims a non-member node.
 - See ``mermaid_flow_layout.py``'s module docstring for the edge-routing
   degradations (dense-graph crossings, label-lane overlap, CJK wrapping,
   minimum-box-size self-loop cosmetics).

{termrender-4.6.0 → termrender-4.6.1}/src/termrender/renderers/mermaid_flow_parser.py

@@ -27,9 +27,17 @@ Grammar covered
   pipe form and the inline ``A -- text --> B`` / ``A -. text .-> B`` /
   ``A == text ==> B`` form. ``&`` fan-out (``A & B --> C & D``) expands to
   the full cartesian product of edges, each carrying the shared style/
-  label/arrow flags; the ``&`` splitter is bracket-depth-aware so a literal
-  ``&`` inside a node label (``A[Foo & Bar]``) is not mistaken for fan-out.
-  Empty-string labels (``A -->|| B``) are stored as ``None``.
+  label/arrow flags. A statement may chain any number of connectors
+  (``A-->B-->C``) — this is parsed as a sequence of node groups separated
+  by connectors, emitting one edge per adjacent (group, connector, group)
+  triple, with each connector's own style/label/arrows applied only to the
+  edge it introduces. Connector scanning, ``&`` fan-out splitting, and
+  ``;`` statement splitting are all bracket-depth-aware: a token that looks
+  like a connector, ``&``, or ``;`` but sits inside ``[...]``/``(...)``/
+  ``{...}`` (part of a node label, e.g. ``A[Go --> Fast]`` or
+  ``A[Check; validate]``) is left untouched rather than mistaken for
+  statement structure. Empty-string labels (``A -->|| B``) are stored as
+  ``None``.
 - ``subgraph <id>[ title] ... end``: ``id[title]`` splits into graph key and
   display title; a bare ``subgraph Sub1`` (no brackets) uses the token as
   both id and title. Nesting is a stack: a node declared while a subgraph is
@@ -112,20 +120,19 @@ _SHAPE_PATTERNS: list[tuple[NodeShape, re.Pattern[str]]] = [
     (NodeShape.DIAMOND, re.compile(r"^\{(.*)\}$")),
 ]
 
-# One statement is `left <connector> right`, where <connector> is either the
-# inline dash-label form (odelim ... label ... cdelim) or a bare/pipe-label
-# connector token. `left` is non-greedy so the connector alternation is tried
-# at the earliest position that yields an overall match.
-_EDGE_RE = re.compile(
-    r"^(?P<left>.+?)\s*"
-    r"(?:"
+# A single connector token: either the inline dash-label form
+# (odelim ... label ... cdelim) or a bare/pipe-label connector. This is
+# matched repeatedly (via `_scan_connectors`) against a whole statement to
+# find every TOP-LEVEL occurrence — an edge statement is a sequence of node
+# groups separated by these connectors, so `A-->B-->C` yields two matches
+# and three groups (`A`, `B`, `C`), not one match with a malformed right
+# side.
+_CONNECTOR_RE = re.compile(
     r"(?P<lhead1><)?(?P<odelim>--|-\.|==)\s+(?P<label>.+?)\s+"
     r"(?P<cdelim>-->|---|\.->|\.-|==>|===)"
     r"|"
     r"(?P<lhead2><)?(?P<conn>-\.+->|-\.+-|={2,}>|={3,}|-{2,}>|-{2,})"
     r"(?:\s*\|(?P<plabel>[^|]*)\|)?"
-    r")"
-    r"\s*(?P<right>.+)$"
 )
 
 _OPENERS = set("([{")
@@ -144,9 +151,29 @@ def _norm_label(text: str | None) -> str | None:
     return stripped or None
 
 
-def _split_amp(text: str) -> list[str]:
-    """Split on top-level ``&`` only — a ``&`` nested inside ``[...]``/
-    ``(...)``/``{...}`` (part of a node label) is left untouched."""
+def _bracket_depths(text: str) -> list[int]:
+    """``depths[i]`` = bracket depth immediately before ``text[i]``
+    (``depths[len(text)]`` = depth at end of string). Shared by every
+    top-level scanner below (connector matching, ``&`` splitting, ``;``
+    splitting) to decide whether a candidate token sits inside a node
+    label's ``[...]``/``(...)``/``{...}`` delimiters and should therefore
+    be ignored rather than treated as statement structure."""
+    depths = [0] * (len(text) + 1)
+    depth = 0
+    for i, ch in enumerate(text):
+        depths[i] = depth
+        if ch in _OPENERS:
+            depth += 1
+        elif ch in _CLOSERS:
+            depth = max(0, depth - 1)
+    depths[len(text)] = depth
+    return depths
+
+
+def _split_top_level(text: str, sep: str) -> list[str]:
+    """Split ``text`` on top-level occurrences of the single-character
+    ``sep`` only — a ``sep`` nested inside ``[...]``/``(...)``/``{...}``
+    (part of a node label) is left untouched."""
     parts: list[str] = []
     buf: list[str] = []
     depth = 0
@@ -157,20 +184,49 @@ def _split_amp(text: str) -> list[str]:
         elif ch in _CLOSERS:
             depth = max(0, depth - 1)
             buf.append(ch)
-        elif ch == "&" and depth == 0:
-            parts.append("".join(buf).strip())
+        elif ch == sep and depth == 0:
+            parts.append("".join(buf))
             buf = []
         else:
             buf.append(ch)
-    if buf:
-        parts.append("".join(buf).strip())
-    return [p for p in parts if p]
+    parts.append("".join(buf))
+    return parts
+
+
+def _split_amp(text: str) -> list[str]:
+    """Split on top-level ``&`` only — a ``&`` nested inside ``[...]``/
+    ``(...)``/``{...}`` (part of a node label) is left untouched."""
+    return [p.strip() for p in _split_top_level(text, "&") if p.strip()]
+
+
+def _scan_connectors(text: str) -> list[re.Match[str]]:
+    """Find every top-level (bracket-depth-0) connector match in ``text``,
+    left to right. A candidate match that starts inside ``[...]``/
+    ``(...)``/``{...}`` (i.e. part of a node label such as
+    ``A[Go --> Fast]``) is skipped rather than accepted, and the scan
+    resumes one character past the skipped match's start so a real
+    top-level connector later in the same text is still found."""
+    depths = _bracket_depths(text)
+    matches: list[re.Match[str]] = []
+    pos = 0
+    while pos <= len(text):
+        m = _CONNECTOR_RE.search(text, pos)
+        if not m:
+            break
+        if depths[m.start()] == 0:
+            matches.append(m)
+            pos = m.end()
+        else:
+            pos = m.start() + 1
+    return matches
 
 
 def _iter_statements(lines: list[str]) -> Iterator[str]:
-    """Flatten source lines into ``;``-and-newline-separated statements."""
+    """Flatten source lines into ``;``-and-newline-separated statements,
+    bracket-depth-aware so a ``;`` inside a node label (``A[Check; x]``)
+    does not split the statement in two."""
     for raw in lines:
-        for part in raw.split(";"):
+        for part in _split_top_level(raw, ";"):
             part = part.strip()
             if part:
                 yield part
@@ -263,46 +319,59 @@ def _try_edge(
     edges: list[FlowEdge],
     stack: list[Subgraph],
 ) -> bool:
-    m = _EDGE_RE.match(stmt)
-    if not m:
+    """Parse ``stmt`` as an edge statement: a sequence of node groups
+    separated by top-level connectors (one group for a plain edge, three
+    or more for a chain like ``A-->B-->C``). Emits one (fan-out-expanded)
+    edge per adjacent (group, connector, group) triple, each carrying its
+    own connector's style/label/arrows."""
+    connectors = _scan_connectors(stmt)
+    if not connectors:
         return False
-    gd = m.groupdict()
-
-    if gd.get("odelim") is not None:
-        style = {
-            "--": EdgeStyle.SOLID,
-            "-.": EdgeStyle.DOTTED,
-            "==": EdgeStyle.THICK,
-        }[gd["odelim"]]
-        dst_arrow = gd["cdelim"].endswith(">")
-        src_arrow = gd.get("lhead1") is not None
-        label = _norm_label(gd.get("label"))
-    else:
-        conn = gd["conn"] or ""
-        if "." in conn:
-            style = EdgeStyle.DOTTED
-        elif conn.startswith("="):
-            style = EdgeStyle.THICK
+
+    groups: list[str] = []
+    prev_end = 0
+    for m in connectors:
+        groups.append(stmt[prev_end : m.start()])
+        prev_end = m.end()
+    groups.append(stmt[prev_end:])
+
+    resolved = [_resolve_nodes(group, nodes, stack) for group in groups]
+
+    for i, m in enumerate(connectors):
+        gd = m.groupdict()
+        if gd.get("odelim") is not None:
+            style = {
+                "--": EdgeStyle.SOLID,
+                "-.": EdgeStyle.DOTTED,
+                "==": EdgeStyle.THICK,
+            }[gd["odelim"]]
+            dst_arrow = gd["cdelim"].endswith(">")
+            src_arrow = gd.get("lhead1") is not None
+            label = _norm_label(gd.get("label"))
         else:
-            style = EdgeStyle.SOLID
-        dst_arrow = conn.endswith(">")
-        src_arrow = gd.get("lhead2") is not None
-        label = _norm_label(gd.get("plabel"))
-
-    left_ids = _resolve_nodes(gd["left"], nodes, stack)
-    right_ids = _resolve_nodes(gd["right"], nodes, stack)
-    for src in left_ids:
-        for dst in right_ids:
-            edges.append(
-                FlowEdge(
-                    src=src,
-                    dst=dst,
-                    style=style,
-                    label=label,
-                    dst_arrow=dst_arrow,
-                    src_arrow=src_arrow,
+            conn = gd["conn"] or ""
+            if "." in conn:
+                style = EdgeStyle.DOTTED
+            elif conn.startswith("="):
+                style = EdgeStyle.THICK
+            else:
+                style = EdgeStyle.SOLID
+            dst_arrow = conn.endswith(">")
+            src_arrow = gd.get("lhead2") is not None
+            label = _norm_label(gd.get("plabel"))
+
+        for src in resolved[i]:
+            for dst in resolved[i + 1]:
+                edges.append(
+                    FlowEdge(
+                        src=src,
+                        dst=dst,
+                        style=style,
+                        label=label,
+                        dst_arrow=dst_arrow,
+                        src_arrow=src_arrow,
+                    )
                 )
-            )
     return True