termrender 4.6.2__tar.gz → 4.7.0__tar.gz

{termrender-4.6.2 → termrender-4.7.0}/CHANGELOG.md

@@ -1,6 +1,54 @@
 # CHANGELOG
 
 
+## v4.7.0 (2026-07-07)
+
+### Features
+
+- **mermaid-class**: Native classDiagram renderer
+  ([`32d6c8c`](https://github.com/crouton-labs/termrender/commit/32d6c8cda0e654120ac2647fe2613f2b06fbb07d))
+
+render_class(source, width) -> list[str] in mermaid_class.py, unwired (not imported by mermaid.py's
+  dispatcher). Standalone module matching mermaid_sequence.py/mermaid_flow.py's shape: own parser,
+  own tests, no Block/pipeline dependency.
+
+Parses classDiagram source (class blocks with member lines, member-association form, bare
+  declarations, <<stereotype>> annotations, ~T~ generics, direction) into the shared
+  FlowGraph/FlowNode/FlowEdge model and hands it to the flowchart engine's layout_flowgraph, using
+  the new compartments and arrow-kind extensions. Covers all six UML relationship kinds
+  (inheritance, composition, aggregation, association, dependency, realization) plus the two
+  headless link forms, both marker-writing directions (<|-- / --|>), quoted cardinalities combined
+  with edge labels, and never-crash raw-echo degradation (missing header, empty body, malformed
+  input, literal box-glyph sanitization).
+
+24 new golden/topology tests in tests/test_mermaid_class.py; full suite (503 tests) green.
+
+- **mermaid-flow**: Support compartmented nodes and UML arrow-kind glyphs
+  ([`2b1441c`](https://github.com/crouton-labs/termrender/commit/2b1441cd707621870651c0c391f603c60f8d3529))
+
+Extend the flowchart engine with two opt-in, backward-compatible hooks so UML-flavored renderers
+  (mermaid classDiagram) can reuse grandalf layout + rasterization + orthogonal routing without
+  duplicating it:
+
+- FlowNode.compartments: list[list[str]] | None draws a multi-line box with a horizontal separator
+  row between compartments (UML name/ fields/methods bands) instead of the single wrapped label.
+  None (the default) is byte-for-byte the original single-label path. -
+  FlowEdge.dst_arrow_kind/src_arrow_kind (default "default") select an arrowhead glyph family
+  independent of style/line weight: triangle_hollow (inheritance/realization), diamond_filled
+  (composition), diamond_hollow (aggregation) — layered on top of the existing direction-computed
+  \u25bc\u25b2\u25b6\u25c0 selection.
+
+All 479 pre-existing tests pass unmodified; every new field defaults to the prior behavior.
+
+
+## v4.6.3 (2026-07-07)
+
+### Bug Fixes
+
+- Commit uv.lock resolution for grandalf runtime dependency
+  ([`0b2a39e`](https://github.com/crouton-labs/termrender/commit/0b2a39ee4440a907c309328920062e543fd5e47e))
+
+
 ## v4.6.2 (2026-07-07)
 
 ### Bug Fixes

{termrender-4.6.2 → termrender-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.6.2
+Version: 4.7.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-4.7.0/src/termrender/renderers/mermaid_class.py

@@ -0,0 +1,410 @@
+"""Native renderer for mermaid ``classDiagram`` sources.
+
+Standalone module: exposes a single pure function, :func:`render_class`.
+Not wired into ``mermaid.py``'s dispatcher (a later, orchestrator-owned
+phase) — nothing in this package imports it. Own parser, own tests, no
+dependency on ``Block`` or the render pipeline, matching the shape of
+``mermaid_sequence.py`` and ``mermaid_flow.py``.
+
+This module does no layout or rasterization of its own. It parses mermaid
+``classDiagram`` source into the *same* :class:`~termrender.renderers.
+mermaid_flow_model.FlowGraph` the native flowchart engine consumes — each
+UML class becomes a :class:`~termrender.renderers.mermaid_flow_model.
+FlowNode` (a compartmented box when the class has a body/annotation, a
+plain single-label box otherwise) and each UML relationship becomes a
+:class:`~termrender.renderers.mermaid_flow_model.FlowEdge` (arrow-kind
+glyphs picked per the UML relation vocabulary) — then hands the graph to
+:func:`~termrender.renderers.mermaid_flow_layout.layout_flowgraph`, which
+owns grandalf layout, box rasterization, and orthogonal edge routing. See
+that module's docstring, and its "UML extension points" section
+specifically, for how compartments and arrow kinds render.
+
+Grammar supported
+------------------
+- Header: ``classDiagram`` / ``classDiagram-v2``. Optional ``direction
+  TB``/``TD``/``LR``/``RL``/``BT`` statement (``TD`` normalizes to ``TB``);
+  defaults to ``TB``.
+- Class blocks: ``class Name { ... }``, either as a single line
+  (``class Name { +field type; +method() }``, ``;``-separated members) or
+  spanning multiple lines up to a standalone ``}``. A member line with a
+  literal ``(`` is a method, otherwise a field — mermaid's own convention
+  (``+String owner`` is a field, ``+deposit(amount) bool`` is a method).
+  Visibility markers (``+ - # ~``) are kept verbatim as typed; no semantic
+  meaning is attached to them beyond display. A ``<<Stereotype>>`` line
+  inside the block is an annotation (rendered ``«Stereotype»`` above the
+  class name), not a member.
+- Member association: ``Name : +method()`` — appends one member to a class
+  without an explicit block (same field/method classification as inside a
+  block).
+- Bare class declaration: ``class Name`` (no body) and standalone
+  annotation: ``<<Interface>> Name``.
+- Generics: ``List~T~`` (anywhere — class name or member text) renders as
+  ``List<T>``.
+- Relationships, both writing directions accepted (``<|--`` / ``--|>`` mean
+  the same thing, marker on whichever side): inheritance (``<|--``/``--|>``,
+  hollow triangle, solid line), realization (``<|..``/``..|>``, hollow
+  triangle, dashed line), composition (``*--``/``--*``, filled diamond),
+  aggregation (``o--``/``--o``, hollow diamond), association (``-->``/
+  ``<--``, filled arrow), dependency (``..>``/``<..``, dashed filled
+  arrow), plus the two headless forms (``--`` solid link, ``..`` dashed
+  link). Optional quoted cardinalities on either side
+  (``A "1" --> "many" B``) and a trailing ``: label`` combine into one
+  edge label (``"1 label many"``, extra-empty parts dropped) — the engine
+  centers this single combined label on the edge's longest straight run;
+  the UML convention of a cardinality glyph pinned at each endpoint
+  separately isn't supported (see *Known degradations*).
+- ``%%`` comments are dropped.
+
+Never crashes: any unparseable input (missing header, or a parse/layout
+exception) degrades to a **raw echo** of the source lines with no
+box-drawing/geometric glyphs (same contract, same glyph ranges, as
+``mermaid_flow.py`` — see that module's docstring for why this exact
+degradation matters to the crouter attach viewer).
+
+Known degradations (by design, not bugs)
+-----------------------------------------
+- Cardinalities and a relation label are combined into a single label
+  string centered on the edge, not three independently-placed annotations
+  (per-endpoint cardinality glyphs, common in dedicated UML tools) — the
+  underlying engine places one label per edge.
+- ``note`` statements, `<<...>>` generic constraints beyond the ``~T~``
+  substitution, and class-diagram namespaces are not recognized — lines
+  using them are silently dropped (best-effort parsing, never raised).
+- A relation's *source*-side marker (inheritance/composition/aggregation's
+  glyph on the "whole"/parent class) is drawn at that class's single
+  shared exit anchor for its rank-flow direction. When one class has
+  several outgoing relations that each carry a source-side marker (e.g. a
+  class that both composes one collaborator and aggregates another), all
+  of them exit through that same anchor cell and only the last-drawn
+  marker glyph survives there — topology and line routing stay correct
+  for every edge, but the specific marker glyph shown at that shared point
+  reflects only one of the colliding relations. Rare in small diagrams
+  (most classes have at most one source-marked outgoing relation);
+  accepted the same way the engine already accepts dense-graph line
+  crossings, rather than reworking shared anchor allocation across the
+  underlying flowchart engine.
+- See ``mermaid_flow_layout.py``'s docstring for the inherited engine
+  degradations (dense-graph crossings, CJK wrap width, minimum-box-size
+  cosmetics) — this renderer's output goes through the same rasterizer and
+  router as flowcharts.
+"""
+
+from __future__ import annotations
+
+import re
+
+from termrender.renderers.mermaid_flow_layout import layout_flowgraph
+from termrender.renderers.mermaid_flow_model import (
+    Direction,
+    EdgeStyle,
+    FlowEdge,
+    FlowGraph,
+    FlowNode,
+    NodeShape,
+)
+from termrender.renderers.mermaid_prelude import strip_prelude_lines
+
+__all__ = ["render_class", "ClassDiagramError"]
+
+
+class ClassDiagramError(Exception):
+    """Raised when source cannot be parsed as a mermaid class diagram at all."""
+
+
+# --------------------------------------------------------------------------
+# Grammar
+# --------------------------------------------------------------------------
+
+_HEADER_RE = re.compile(r"^classDiagram(?:-v2)?\b", re.IGNORECASE)
+_DIRECTION_RE = re.compile(r"^direction\s+(TB|TD|LR|RL|BT)\b", re.IGNORECASE)
+_COMMENT_RE = re.compile(r"^%%")
+
+_CLASS_OPEN_RE = re.compile(r"^class\s+(\S+)\s*\{(.*)$")
+_CLASS_BARE_RE = re.compile(r"^class\s+(\S+)\s*$")
+_ANNOTATION_STANDALONE_RE = re.compile(r"^<<(.+?)>>\s+(\S+)\s*$")
+_ANNOTATION_ONLY_RE = re.compile(r"^<<(.+?)>>\s*$")
+_MEMBER_ASSOC_RE = re.compile(r'^(?P<id>[^\s"]+)\s*:\s*(?P<member>.+)$')
+
+_GENERIC_RE = re.compile(r"~([^~]*)~")
+
+# Relation operator: an optional left head marker, a >=2-run dash/dot core
+# (dash = solid, dot = dashed), an optional right head marker. Searched
+# against a quote-masked copy of the line (see _mask_quotes) so a quoted
+# range cardinality like "0..1" is never mistaken for the operator itself.
+_OP_RE = re.compile(r"(?P<lhead><\||\*|o|<)?(?P<core>-{2,}|\.{2,})(?P<rhead>\|>|\*|o|>)?")
+_REL_LEFT_RE = re.compile(r'^\s*(?P<id>[^\s"]+)\s*(?:"(?P<card>[^"]*)")?\s*$')
+_REL_RIGHT_RE = re.compile(
+    r'^\s*(?:"(?P<card>[^"]*)")?\s*(?P<id>[^\s":]+)\s*(?::\s*(?P<label>.*))?$'
+)
+
+_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
+
+
+class _ClassDef:
+    """Mutable parse-time record for one UML class — converted to a
+    :class:`FlowNode` at the end of parsing (see :func:`_build_graph`)."""
+
+    __slots__ = ("id", "display_name", "annotations", "fields", "methods", "has_block")
+
+    def __init__(self, id_: str, display_name: str) -> None:
+        self.id = id_
+        self.display_name = display_name
+        self.annotations: list[str] = []
+        self.fields: list[str] = []
+        self.methods: list[str] = []
+        self.has_block = False
+
+
+def _format_generics(text: str) -> str:
+    """``List~T~`` -> ``List<T>`` (also handles multi-param ``Map~K, V~``)."""
+    return _GENERIC_RE.sub(r"<\1>", text)
+
+
+def _strip_generics_id(token: str) -> str:
+    """The graph-key id for a (possibly generic) class token: everything
+    before the first ``~``, so ``Stack~T~`` and a later bare ``Stack``
+    reference resolve to the same node."""
+    return token.split("~", 1)[0]
+
+
+def _mask_quotes(line: str) -> str:
+    """Replace every quoted span with same-length filler so a quoted range
+    cardinality (``"0..1"``) can never be mistaken for the relation
+    operator when searching for it (see ``_OP_RE``); positions in the
+    masked string stay valid indices into the original line."""
+    return re.sub(r'"[^"]*"', lambda m: "Q" * len(m.group(0)), line)
+
+
+def _get_or_create(classes: dict[str, _ClassDef], token: str) -> _ClassDef:
+    cid = _strip_generics_id(token)
+    cls = classes.get(cid)
+    if cls is None:
+        cls = _ClassDef(cid, _format_generics(token))
+        classes[cid] = cls
+    elif "~" in token:
+        cls.display_name = _format_generics(token)
+    return cls
+
+
+def _consume_members(cls: _ClassDef, text: str) -> None:
+    """Split ``text`` (one physical line, or the inline body of a
+    ``class Name { ... }`` opener/closer) on ``;`` into individual member/
+    annotation statements and file each into ``cls``."""
+    for part in text.split(";"):
+        part = part.strip()
+        if not part:
+            continue
+        am = _ANNOTATION_ONLY_RE.match(part)
+        if am:
+            cls.annotations.append(am.group(1).strip())
+            continue
+        formatted = _format_generics(part)
+        if "(" in formatted:
+            cls.methods.append(formatted)
+        else:
+            cls.fields.append(formatted)
+
+
+_ARROW_KIND = {
+    "<|": "triangle_hollow",
+    "|>": "triangle_hollow",
+    "*": "diamond_filled",
+    "o": "diamond_hollow",
+    "<": "default",
+    ">": "default",
+}
+
+
+def _try_relation(
+    line: str, classes: dict[str, _ClassDef], edges: list[FlowEdge]
+) -> bool:
+    masked = _mask_quotes(line)
+    m = _OP_RE.search(masked)
+    if not m or not (m.group("lhead") or m.group("rhead") or m.group("core")):
+        return False
+
+    left_text, right_text = line[: m.start()], line[m.end() :]
+    lm = _REL_LEFT_RE.match(left_text)
+    rm = _REL_RIGHT_RE.match(right_text)
+    if not lm or not rm:
+        return False
+
+    src_token, dst_token = lm.group("id"), rm.group("id")
+    src = _get_or_create(classes, src_token)
+    dst = _get_or_create(classes, dst_token)
+
+    style = EdgeStyle.DOTTED if m.group("core").startswith(".") else EdgeStyle.SOLID
+    lhead, rhead = m.group("lhead"), m.group("rhead")
+    src_arrow, dst_arrow = lhead is not None, rhead is not None
+    src_kind = _ARROW_KIND.get(lhead, "default")
+    dst_kind = _ARROW_KIND.get(rhead, "default")
+
+    # Cardinalities read src-side then dst-side, with the relation label
+    # (if any) sitting between them — combined into one string so a
+    # labeled+cardinalitied edge reads "1 contains many", not
+    # "1 many contains" (the underlying engine centers one label per edge).
+    src_card, dst_card = lm.group("card"), rm.group("card")
+    label_text = rm.group("label")
+    ordered = [p for p in (src_card, label_text, dst_card) if p]
+    label = " ".join(ordered) if ordered else None
+
+    edges.append(
+        FlowEdge(
+            src=src.id,
+            dst=dst.id,
+            style=style,
+            label=_format_generics(label) if label else None,
+            dst_arrow=dst_arrow,
+            src_arrow=src_arrow,
+            dst_arrow_kind=dst_kind,
+            src_arrow_kind=src_kind,
+        )
+    )
+    return True
+
+
+def _build_graph(source: str) -> FlowGraph:
+    lines = source.splitlines()
+    sniff_lines = strip_prelude_lines(lines)
+    first = next((line.strip() for line in sniff_lines if line.strip()), "")
+    if not _HEADER_RE.match(first):
+        raise ClassDiagramError(
+            "not a mermaid class diagram: source must start with 'classDiagram'"
+        )
+
+    direction = Direction.TB
+    classes: dict[str, _ClassDef] = {}
+    edges: list[FlowEdge] = []
+    seen_header = False
+    block_cls: _ClassDef | None = None
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        if block_cls is not None:
+            if line.endswith("}"):
+                _consume_members(block_cls, line[:-1])
+                block_cls = None
+            else:
+                _consume_members(block_cls, line)
+            continue
+
+        if not seen_header:
+            if _HEADER_RE.match(line):
+                seen_header = True
+            continue
+
+        if _COMMENT_RE.match(line):
+            continue
+
+        dm = _DIRECTION_RE.match(line)
+        if dm:
+            token = dm.group(1).upper()
+            direction = Direction.TB if token == "TD" else Direction(token)
+            continue
+
+        om = _CLASS_OPEN_RE.match(line)
+        if om:
+            name_token, inline_body = om.group(1), om.group(2)
+            cls = _get_or_create(classes, name_token)
+            cls.has_block = True
+            body = inline_body.rstrip()
+            if body.endswith("}"):
+                _consume_members(cls, body[:-1])
+            else:
+                _consume_members(cls, body)
+                block_cls = cls
+            continue
+
+        bm = _CLASS_BARE_RE.match(line)
+        if bm:
+            _get_or_create(classes, bm.group(1))
+            continue
+
+        am = _ANNOTATION_STANDALONE_RE.match(line)
+        if am:
+            cls = _get_or_create(classes, am.group(2))
+            cls.annotations.append(am.group(1).strip())
+            continue
+
+        if _try_relation(line, classes, edges):
+            continue
+
+        mm = _MEMBER_ASSOC_RE.match(line)
+        if mm:
+            cls = _get_or_create(classes, mm.group("id"))
+            cls.has_block = True
+            _consume_members(cls, mm.group("member"))
+            continue
+
+        # Unrecognized line: consumed silently, best-effort.
+
+    if not seen_header:
+        raise ClassDiagramError(
+            "not a mermaid class diagram: source must start with 'classDiagram'"
+        )
+
+    nodes: list[FlowNode] = []
+    for cls in classes.values():
+        name_lines = [f"\u00ab{a}\u00bb" for a in cls.annotations] + [cls.display_name]
+        if cls.has_block:
+            compartments = [name_lines, cls.fields or [""], cls.methods or [""]]
+        elif cls.annotations:
+            compartments = [name_lines]
+        else:
+            compartments = None
+        nodes.append(
+            FlowNode(
+                id=cls.id,
+                label=cls.display_name,
+                shape=NodeShape.RECT,
+                compartments=compartments,
+            )
+        )
+
+    return FlowGraph(direction=direction, nodes=nodes, edges=edges, subgraphs=[])
+
+
+def _raw_echo(source: str) -> list[str]:
+    return [
+        _GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()
+    ]
+
+
+def render_class(source: str, width: int) -> list[str]:
+    """Render a mermaid ``classDiagram`` source to unicode lines.
+
+    Pure and total: never raises. Degrades to a raw echo of ``source``
+    (see the module docstring's "Never crashes" note) when the source
+    isn't a class diagram at all, parses to zero classes, or an
+    unexpected exception escapes layout.
+
+    Args:
+        source: The mermaid fence body (with or without surrounding fence
+            markers — only the text between them).
+        width: Advisory terminal width — unused, like the flowchart and
+            sequence renderers; this function sizes to content.
+
+    Returns:
+        Rendered lines on success (guaranteed to contain box-drawing
+        glyphs), or a raw echo of ``source`` on any degradation path.
+    """
+    try:
+        graph = _build_graph(source)
+    except ClassDiagramError:
+        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