termrender 4.5.0__tar.gz → 4.6.1__tar.gz

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

@@ -1,6 +1,79 @@
 # 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
+
+- Add flowchart node shapes, subgraph frames, and direction rendering
+  ([`e872199`](https://github.com/crouton-labs/termrender/commit/e87219956294319feb0015d2cf4573b8cc60a0cb))
+
+Applies and hardens the salvaged decoration work for the native mermaid flowchart renderer's layout
+  engine:
+
+- Nine distinct node-shape borders (rect, round, stadium, cylinder, circle, diamond, hexagon,
+  subroutine, parallelogram), each reserving its full bounding box so the router treats every shape
+  as impassable. - Subgraph enclosure frames (left-anchored title, nested, flatten when members
+  aren't placed contiguously enough for a clean rect). - TB/BT/LR/RL direction handling via a
+  post-layout coordinate transform.
+
+Fixes found while hardening: - draw_frame now reserves the title text cells (not the whole border)
+  so a cross-boundary edge crossing a frame's top border can no longer clobber a letter of the
+  subgraph title. - Subgraph frame sizing is now computed bottom-up (_build_subgraph_frames): a
+  parent subgraph's extent is built from its children's *padded frame rects* (when they get a frame)
+  rather than raw member extents, so a nested subgraph whose members share the same column/row span
+  as its parent no longer produces an identically-sized frame that overwrites the parent's border —
+  nesting now always has real margin. - Corrected the module docstring's stale "every node renders
+  as a plain rectangle, frames not yet wired" description to match the shipped shape/frame drawers.
+
+Adds tests/test_mermaid_flow_shapes.py: real-geometry assertions for shape distinctness, a 9-shape
+  gallery, subgraph frame containment, nested-frame non-overlap, non-contiguous-subgraph flatten,
+  LR/RL/BT topology + arrowhead direction, LR same-rank spacing, and router avoidance of a diamond's
+  interior. Full suite: 437 passed (422 existing + 15 new), no regressions.
+
+
 ## v4.5.0 (2026-07-06)
 
 ### Features

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.5.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.5.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).