termrender 4.3.2__tar.gz → 4.5.0__tar.gz

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

@@ -1,6 +1,39 @@
 # CHANGELOG
 
 
+## v4.5.0 (2026-07-06)
+
+### Features
+
+- Add flowchart edge router and public render_flowchart
+  ([`a1b46cf`](https://github.com/crouton-labs/termrender/commit/a1b46cf11607ec6b31ea8fe1b4d90b11aafff10f))
+
+- Replace the placeholder edge drawing in mermaid_flow_layout.py with the full orthogonal router:
+  rank-relative endpoint anchors (forward/same-rank/ back-edge), L/Z staircase paths for forward
+  edges, growing side-lane C-paths for back-edges so they never overlay forward edges, arrowheads
+  chosen from final-segment direction, edge labels centered on the longest straight run (shifting
+  off reserved cells), and self-loops modeled on the sequence renderer's self-message loop. - Add
+  mermaid_flow.py exposing the public, pure, never-raising render_flowchart(source, width) ->
+  list[str], wiring parse -> layout_flowgraph -> lines behind the three-case degradation contract
+  (no header, zero nodes, unexpected layout exception -> raw echo). - Add
+  tests/test_mermaid_flow.py: real end-to-end geometry/topology assertions, including the labeled
+  back-edge cycle that panics the Go binary, multi-parent attachment, headless edges, and echo
+  degradation.
+
+Unwired: nothing imports mermaid_flow yet (later phase's cutover).
+
+
+## v4.4.0 (2026-07-06)
+
+### Features
+
+- Add flowchart layout engine core (grandalf adapter + canvas rasterizer)
+  ([`23e26e9`](https://github.com/crouton-labs/termrender/commit/23e26e9c3228bfac302c270b4c0c5ffe880bfc20))
+
+- Add flowchart mermaid parser
+  ([`c9c80c3`](https://github.com/crouton-labs/termrender/commit/c9c80c30ed638c3532ef9464ce1cb7f4af4fa3ce))
+
+
 ## v4.3.2 (2026-07-06)
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.3.2
+Version: 4.5.0
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Terminals
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Requires-Python: >=3.10
+Requires-Dist: grandalf>=0.8
 Requires-Dist: mermaid-ascii>=1.2
 Requires-Dist: mistune>=3.0
 Requires-Dist: pygments>=2.0

{termrender-4.3.2 → termrender-4.5.0}/pyproject.toml

@@ -30,6 +30,7 @@ dependencies = [
     "mistune>=3.0",
     "mermaid-ascii>=1.2",
     "pygments>=2.0",
+    "grandalf>=0.8",
 ]
 
 [project.urls]

termrender-4.5.0/src/termrender/renderers/mermaid_flow.py

@@ -0,0 +1,110 @@
+"""Public entry point for the native mermaid flowchart/graph renderer.
+
+Standalone module: exposes a single pure function, :func:`render_flowchart`.
+Not yet wired into ``mermaid.py``'s dispatcher (a later, orchestrator-owned
+phase) — nothing in this package imports it. This module is a thin
+orchestrator over the parser and layout engine; it owns none of the grammar
+or layout logic itself, only header sniffing and the degradation contract.
+
+Layout model
+------------
+``render_flowchart`` is ``parse -> layout_flowgraph -> lines``, wrapped in a
+degradation guard (see *Degradation contract* below). :func:`~termrender.
+renderers.mermaid_flow_parser.parse` turns mermaid source into a
+:class:`~termrender.renderers.mermaid_flow_model.FlowGraph`;
+:func:`~termrender.renderers.mermaid_flow_layout.layout_flowgraph` lays it
+out with ``grandalf`` (pure-Python Sugiyama) and rasterizes it — bordered
+rectangle nodes, an orthogonal edge router (L/Z paths for forward edges,
+growing side lanes for back-edges/cycles, arrowheads, edge labels,
+self-loops) — onto a char grid. See ``mermaid_flow_parser.py`` and
+``mermaid_flow_layout.py``'s module docstrings for the full grammar and
+routing model; this module covers only the public contract.
+
+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.
+
+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).
+- 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).
+- ``width`` is advisory only: like the other native renderers in this
+  package, this renderer sizes to content and may overflow a narrow
+  terminal rather than truncate the diagram.
+"""
+
+from __future__ import annotations
+
+from termrender.renderers.mermaid_flow_layout import layout_flowgraph
+from termrender.renderers.mermaid_flow_parser import FlowchartError, parse
+
+__all__ = ["render_flowchart"]
+
+
+def render_flowchart(source: str, width: int) -> list[str]:
+    """Render a mermaid ``graph``/``flowchart`` source to unicode lines.
+
+    Pure and total: never raises. Degrades to a raw echo of ``source``
+    (each line ``\\n``-split and ``.rstrip()``-ed, containing no
+    box-drawing glyphs) exactly when:
+
+    1. The source isn't a flowchart at all (no ``graph``/``flowchart``
+       header on its first non-blank, post-prelude line) — :func:`parse`
+       raises :class:`FlowchartError`.
+    2. Parsing succeeds but yields zero nodes (an empty or comment-only
+       diagram body) — nothing to draw.
+    3. Any unexpected exception escapes :func:`layout_flowgraph` — a
+       defensive catch-all; this should never happen for well-typed input,
+       but the guarantee is "never crash, degrade" regardless.
+
+    Otherwise, returns the rendered diagram: guaranteed to contain unicode
+    box-drawing glyphs (every node is a bordered box), never ANSI escapes.
+    The distinction matters downstream — code that detects render success
+    by the *presence* of box-drawing glyphs relies on the echo path never
+    emitting any.
+
+    Args:
+        source: The mermaid fence body (with or without the surrounding
+            fence markers — only the text between them).
+        width: Advisory terminal width. See the module docstring's
+            "Known degradations" for why this is advisory rather than a
+            hard wrap.
+
+    Returns:
+        Rendered lines on success, or a raw-echo of ``source`` on any of
+        the three degradation conditions above.
+    """
+    try:
+        graph = parse(source)
+    except FlowchartError:
+        return _raw_echo(source)
+
+    if not graph.nodes:
+        return _raw_echo(source)
+
+    try:
+        lines = layout_flowgraph(graph, width)
+    except Exception:
+        return _raw_echo(source)
+
+    if not lines:
+        return _raw_echo(source)
+
+    return lines
+
+
+def _raw_echo(source: str) -> list[str]:
+    return [line.rstrip() for line in source.splitlines()]