termrender 0.7.3__tar.gz → 0.8.0__tar.gz

{termrender-0.7.3 → termrender-0.8.0}/CHANGELOG.md

@@ -1,6 +1,20 @@
 # CHANGELOG
 
 
+## v0.8.0 (2026-04-18)
+
+### Features
+
+- **mermaid**: Preprocess sequence diagrams for mermaid-ascii compatibility
+  ([`a642576`](https://github.com/CaptainCrouton89/termrender/commit/a642576d41d5dbde372d7de2ab47745296a78e32))
+
+mermaid-ascii only parses ->> / -->> arrows, participants, and self-loops; every other common
+  sequence-diagram construct made it fail and fall back to raw source. Rewrite Note lines into
+  self-loops, map -> / -x / --x / -) / --) / -- > onto the supported arrow pair, drop block keywords
+  (loop/alt/activate/ autonumber/end/…), and flatten <br/> to ' / '. Non-sequence diagrams pass
+  through unchanged.
+
+
 ## v0.7.3 (2026-04-15)
 
 ### Bug Fixes

{termrender-0.7.3 → termrender-0.8.0}/PKG-INFO

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

{termrender-0.7.3 → termrender-0.8.0}/src/termrender/CLAUDE.md

@@ -8,7 +8,9 @@
 
 `layout.py:119–134` runs `mermaid-ascii` and caches the result in `block.attrs["_rendered"]`. The `mermaid` renderer (renderers/mermaid.py) reads this cache key; if it's absent, it runs the subprocess again. A failed layout subprocess (tool missing, timeout) silently stores the raw source diagram in `_rendered`, so the renderer falls back to printing source — no error is raised. Both sites have a 30s timeout.
 
-`layout.py` imports `fix_mermaid_encoding` from `renderers/mermaid.py` — the only reverse dependency from layout into renderers. Reorganizing `renderers/` must account for this import. The two subprocess call sites differ: layout uses `check=True` (non-zero exit raises `CalledProcessError` → caught → raw source fallback); the renderer omits `check` (non-zero exit silently reads `stdout`, which may be empty or partial). See `renderers/CLAUDE.md` for encoding-fix details.
+`layout.py` imports `fix_mermaid_encoding` and `preprocess_mermaid_for_ascii` from `renderers/mermaid.py` — the only reverse dependency from layout into renderers. Reorganizing `renderers/` must account for these imports. The two subprocess call sites differ: layout uses `check=True` (non-zero exit raises `CalledProcessError` → caught → raw source fallback); the renderer omits `check` (non-zero exit silently reads `stdout`, which may be empty or partial). See `renderers/CLAUDE.md` for encoding-fix details.
+
+`preprocess_mermaid_for_ascii` rewrites sequence diagrams into the subset `mermaid-ascii` parses (it only supports `->>` / `-->>` arrows, `participant`, and self-loops). `Note over|left of|right of X[,Y]: msg` becomes a self-loop `X->>X: 📝 msg`; `->`, `-x`, `--x`, `-)`, `--)`, and bare `-->` are mapped to `->>`/`-->>`; block keywords (`loop`/`alt`/`opt`/`par`/`critical`/`break`/`rect`/`activate`/`deactivate`/`autonumber`/`else`/`and`/`end`) are dropped so the inner arrow lines still render; `<br/>` is flattened to ` / `. Non-sequence diagrams (`flowchart`, `graph`, etc.) pass through unchanged. Semantics are lossy by design — `-x` (fail arrow) renders as a plain arrow, and block scoping is lost — but the flow diagram renders instead of silently degrading to raw source.
 
 ## Directive nesting: outer must have more colons than inner
 

{termrender-0.7.3 → termrender-0.8.0}/src/termrender/layout.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import subprocess
 
 from termrender.blocks import Block, BlockType
-from termrender.renderers.mermaid import fix_mermaid_encoding
+from termrender.renderers.mermaid import fix_mermaid_encoding, preprocess_mermaid_for_ascii
 from termrender.style import wrap_text, visual_len
 
 
@@ -148,7 +148,7 @@ def resolve_height(block: Block) -> None:
         try:
             result = subprocess.run(
                 ["mermaid-ascii", "-f", "-", "-w", str(block.width or 80), "-y", "1"],
-                input=source,
+                input=preprocess_mermaid_for_ascii(source),
                 capture_output=True,
                 text=True,
                 check=True,

termrender-0.8.0/src/termrender/renderers/mermaid.py

@@ -0,0 +1,98 @@
+"""Mermaid diagram renderer for termrender."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+
+from termrender.blocks import Block
+from termrender.style import visual_ljust
+
+
+def fix_mermaid_encoding(text: str) -> str:
+    """Undo mermaid-ascii's double-encoding of UTF-8 characters.
+
+    mermaid-ascii misinterprets UTF-8 input bytes as Latin-1 and re-encodes
+    to UTF-8, corrupting multi-byte characters (e.g. → becomes â\\x86\\x92).
+    Reversing the process: encode back to Latin-1 to recover the original
+    UTF-8 bytes, then decode as UTF-8.
+    """
+    try:
+        return text.encode("latin-1").decode("utf-8")
+    except (UnicodeDecodeError, UnicodeEncodeError):
+        return text
+
+
+_NOTE_RE = re.compile(
+    r"^(\s*)[Nn]ote\s+(?:over|left\s+of|right\s+of)\s+([^:]+?)\s*:\s*(.*)$"
+)
+_BR_RE = re.compile(r"<br\s*/?>", re.IGNORECASE)
+_UNSUPPORTED_BLOCK_RE = re.compile(
+    r"^\s*(?:loop|alt|else|opt|par|and|critical|option|break|rect|"
+    r"activate|deactivate|autonumber|end)\b.*$",
+    re.IGNORECASE,
+)
+
+
+def preprocess_mermaid_for_ascii(source: str) -> str:
+    """Rewrite mermaid sequence diagrams into the subset mermaid-ascii supports.
+
+    mermaid-ascii only understands ``->>`` and ``-->>`` arrows plus ``participant``
+    declarations. This helper converts ``Note`` lines into self-loops, maps the
+    other arrow variants (``->``, ``-x``, ``--x``, ``-)``, ``--)``, ``-->``) to
+    the supported pair, drops block keywords (``loop``, ``alt``, ``activate``…),
+    and flattens ``<br/>`` tags. Non-sequence diagrams are returned unchanged.
+    """
+    lines = source.splitlines()
+    first = next((l.strip() for l in lines if l.strip()), "")
+    if not first.lower().startswith("sequencediagram"):
+        return source
+
+    out: list[str] = []
+    for line in lines:
+        m = _NOTE_RE.match(line)
+        if m:
+            indent, parts, msg = m.group(1), m.group(2), m.group(3)
+            first_p = parts.split(",")[0].strip()
+            msg = _BR_RE.sub(" / ", msg)
+            out.append(f"{indent}{first_p}->>{first_p}: 📝 {msg}")
+            continue
+
+        if _UNSUPPORTED_BLOCK_RE.match(line):
+            continue
+
+        line = _BR_RE.sub(" / ", line)
+        line = re.sub(r"--x(?=\s|\w|\()", "-->>", line)
+        line = re.sub(r"-x(?=\s|\w|\()", "->>", line)
+        line = re.sub(r"--\)(?=\s|\w|\()", "-->>", line)
+        line = re.sub(r"-\)(?=\s|\w|\()", "->>", line)
+        line = re.sub(r"-->(?!>)", "-->>", line)
+        line = re.sub(r"(?<!-)->(?!>)", "->>", line)
+        out.append(line)
+    return "\n".join(out)
+
+
+def render(block: Block, color: bool) -> list[str]:
+    """Render a mermaid diagram from pre-rendered or on-the-fly ASCII output."""
+    w = block.width
+    rendered = block.attrs.get("_rendered")
+
+    if rendered is None:
+        source = block.attrs.get("source", "")
+        try:
+            result = subprocess.run(
+                ["mermaid-ascii", "-f", "-", "-w", str(block.width or 80), "-y", "1"],
+                input=preprocess_mermaid_for_ascii(source),
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            rendered = fix_mermaid_encoding(result.stdout)
+        except Exception:
+            rendered = source
+
+    lines: list[str] = []
+    for raw_line in rendered.split("\n"):
+        lines.append(visual_ljust(raw_line, w))
+
+    return lines

termrender-0.8.0/tests/test_mermaid_compat.py

@@ -0,0 +1,115 @@
+import unittest
+
+from termrender.renderers.mermaid import preprocess_mermaid_for_ascii
+
+
+class TestMermaidPreprocessor(unittest.TestCase):
+
+    def test_non_sequence_diagrams_pass_through(self):
+        src = "flowchart TD\n    A-->B\n    B-->C"
+        self.assertEqual(preprocess_mermaid_for_ascii(src), src)
+
+    def test_note_over_becomes_self_loop(self):
+        src = "sequenceDiagram\n    participant A\n    participant B\n    Note over A: hello"
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("A->>A: 📝 hello", out)
+        self.assertNotIn("Note over", out)
+
+    def test_note_over_multi_participant_picks_first(self):
+        src = "sequenceDiagram\n    participant A\n    participant B\n    Note over A,B: shared"
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("A->>A: 📝 shared", out)
+
+    def test_note_left_and_right_of(self):
+        src = (
+            "sequenceDiagram\n"
+            "    participant X\n"
+            "    Note left of X: L\n"
+            "    Note right of X: R"
+        )
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("X->>X: 📝 L", out)
+        self.assertIn("X->>X: 📝 R", out)
+
+    def test_br_tags_flattened_in_note(self):
+        src = "sequenceDiagram\n    participant A\n    Note over A: line1<br/>line2"
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("A->>A: 📝 line1 / line2", out)
+
+    def test_br_tags_flattened_in_arrow_message(self):
+        src = "sequenceDiagram\n    participant A\n    participant B\n    A->>B: a<br/>b<br />c"
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("A->>B: a / b / c", out)
+
+    def test_arrow_variants_rewritten(self):
+        src = (
+            "sequenceDiagram\n"
+            "    participant A\n"
+            "    participant B\n"
+            "    A-xB: fail\n"
+            "    A--xB: dashed fail\n"
+            "    A-)B: async\n"
+            "    A--)B: dashed async\n"
+            "    A->B: single\n"
+            "    A-->B: dashed single\n"
+        )
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertNotIn("-x", out)
+        self.assertNotIn("-)", out)
+        # Each single-dash variant should be solid ->>
+        self.assertIn("A->>B: fail", out)
+        self.assertIn("A->>B: async", out)
+        self.assertIn("A->>B: single", out)
+        # Each double-dash variant should be dashed -->>
+        self.assertIn("A-->>B: dashed fail", out)
+        self.assertIn("A-->>B: dashed async", out)
+        self.assertIn("A-->>B: dashed single", out)
+
+    def test_existing_double_arrow_preserved(self):
+        src = "sequenceDiagram\n    participant A\n    participant B\n    A->>B: x\n    A-->>B: y"
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("A->>B: x", out)
+        self.assertIn("A-->>B: y", out)
+        # Should not have inflated to ->>>
+        self.assertNotIn("->>>", out)
+        self.assertNotIn("-->>>", out)
+
+    def test_block_keywords_dropped(self):
+        src = (
+            "sequenceDiagram\n"
+            "    participant A\n"
+            "    participant B\n"
+            "    activate A\n"
+            "    loop forever\n"
+            "    A->>B: x\n"
+            "    end\n"
+            "    deactivate A\n"
+            "    autonumber\n"
+            "    alt happy\n"
+            "    A->>B: y\n"
+            "    else sad\n"
+            "    A->>B: z\n"
+            "    end\n"
+        )
+        out = preprocess_mermaid_for_ascii(src)
+        for dropped in ("activate", "deactivate", "loop", "end", "alt ", "else ", "autonumber"):
+            self.assertNotIn(dropped, out.lower())
+        # But arrow lines survive
+        self.assertIn("A->>B: x", out)
+        self.assertIn("A->>B: y", out)
+        self.assertIn("A->>B: z", out)
+
+    def test_participant_aliases_with_parens_preserved(self):
+        src = (
+            "sequenceDiagram\n"
+            "    participant C1 as Core (PID 92348)\n"
+            "    participant C2 as Core (PID 93684)\n"
+            "    C1->>C2: x"
+        )
+        out = preprocess_mermaid_for_ascii(src)
+        self.assertIn("participant C1 as Core (PID 92348)", out)
+        self.assertIn("participant C2 as Core (PID 93684)", out)
+
+
+if __name__ == "__main__":
+    unittest.main()

termrender-0.7.3/src/termrender/renderers/mermaid.py

@@ -1,48 +0,0 @@
-"""Mermaid diagram renderer for termrender."""
-
-from __future__ import annotations
-
-import subprocess
-
-from termrender.blocks import Block
-from termrender.style import visual_ljust
-
-
-def fix_mermaid_encoding(text: str) -> str:
-    """Undo mermaid-ascii's double-encoding of UTF-8 characters.
-
-    mermaid-ascii misinterprets UTF-8 input bytes as Latin-1 and re-encodes
-    to UTF-8, corrupting multi-byte characters (e.g. → becomes â\\x86\\x92).
-    Reversing the process: encode back to Latin-1 to recover the original
-    UTF-8 bytes, then decode as UTF-8.
-    """
-    try:
-        return text.encode("latin-1").decode("utf-8")
-    except (UnicodeDecodeError, UnicodeEncodeError):
-        return text
-
-
-def render(block: Block, color: bool) -> list[str]:
-    """Render a mermaid diagram from pre-rendered or on-the-fly ASCII output."""
-    w = block.width
-    rendered = block.attrs.get("_rendered")
-
-    if rendered is None:
-        source = block.attrs.get("source", "")
-        try:
-            result = subprocess.run(
-                ["mermaid-ascii", "-f", "-", "-w", str(block.width or 80), "-y", "1"],
-                input=source,
-                capture_output=True,
-                text=True,
-                timeout=30,
-            )
-            rendered = fix_mermaid_encoding(result.stdout)
-        except Exception:
-            rendered = source
-
-    lines: list[str] = []
-    for raw_line in rendered.split("\n"):
-        lines.append(visual_ljust(raw_line, w))
-
-    return lines