termrender 4.8.0__tar.gz → 4.9.1__tar.gz

{termrender-4.8.0 → termrender-4.9.1}/CHANGELOG.md

@@ -1,6 +1,66 @@
 # CHANGELOG
 
 
+## v4.9.1 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid-flow**: Stop dropping edge labels/markers on a shared exit anchor
+  ([`552d3d3`](https://github.com/crouton-labs/termrender/commit/552d3d3deef061e23c5b894852ae024065366eb8))
+
+When 2+ edges leave one node through the router's single fixed exit anchor (e.g. two forward edges
+  in LR/RL, or a diamond node's right side), two defects followed:
+
+- Label drop: the shared first segment of each edge's Z-path could tie in length with each edge's
+  own distinguishing segment further along - routine in LR/RL, where a node's fan-out run and its
+  branch runs often measure the same few cells. _longest_segment's old first-wins tie-break always
+  picked that shared segment for both edges' labels, so the second label landed on cells the first
+  already claimed and silently vanished. Fixed by breaking ties toward the *last* segment instead -
+  the segment nearest each edge's own destination, which is never shared. TB is unaffected (its
+  branch runs are typically much longer than the shared trunk, so no tie exists there to begin
+  with).
+
+- Marker drop: a source-side arrow-kind marker glyph (UML composition and aggregation diamonds)
+  drawn at the shared anchor cell survived only for the last-drawn edge. Fixed via a new pre-pass,
+  _allocate_edge_anchors, that spreads a group's exit points along the node's side - but only when
+  2+ of that group's edges actually carry a source-side marker. Plain, markerless fan-outs (by far
+  the common case) keep sharing one exit cell, since that's what makes draw_segment's junction
+  bitmask resolve into a single clean tee rather than two disjoint stubs - spreading those would
+  only change where the fan visually splits, not fix anything, and would break the existing
+  trunk-then-tee golden output for every unlabeled fan-out/merge case.
+
+Anchor spreading is shape-aware for NodeShape.DIAMOND (the only shape whose left/right sides aren't
+  straight across their full bounding-rect span) so a spread point never lands in the diamond's
+  tapered corner region.
+
+Removes the "known limitation" paragraph from mermaid_class.py's docstring now that the
+  composition/aggregation marker case it described is fixed.
+
+Goldens touched: added test_lr_fan_out_with_labels_both_present_golden (new - pins the fixed LR
+  output, previously buggy/missing) and test_two_source_side_markers_from_one_class_both_survive
+  (new). No existing golden was changed - the fan-out/merge goldens (test_fan_out_golden,
+  test_multi_parent_dag_golden, test_td_direction_golden, test_lr_direction_golden) are
+  byte-for-byte unchanged because none of their edges carry a source-side marker, so the new
+  anchor-spread never triggers for them.
+
+
+## v4.9.0 (2026-07-07)
+
+### Features
+
+- **mermaid-er**: Native erDiagram renderer
+  ([`caae993`](https://github.com/crouton-labs/termrender/commit/caae9930b6a996e33b401dc773c5a9aae01b1529))
+
+Parses mermaid erDiagram source (entity attribute blocks with PK/FK/UK markers and quoted comments,
+  bare entities, the full crow's-foot cardinality grammar in both writing directions, identifying/
+  non-identifying relationship lines, entity/attribute aliasing and quoted names) into the shared
+  FlowGraph model and hands it to the existing layout_flowgraph engine (compartmented boxes, edge
+  labels). Never crashes: unparseable input degrades to a raw echo with no box-drawing glyphs,
+  matching mermaid_class.py's contract.
+
+Not wired into mermaid.py's dispatcher (later phase). Read-only against mermaid_flow*.py.
+
+
 ## v4.8.0 (2026-07-07)
 
 ### Features

{termrender-4.8.0 → termrender-4.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.8.0
+Version: 4.9.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.8.0 → termrender-4.9.1}/src/termrender/renderers/mermaid_class.py

@@ -70,19 +70,6 @@ Known degradations (by design, not bugs)
 - ``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

termrender-4.9.1/src/termrender/renderers/mermaid_er.py

@@ -0,0 +1,388 @@
+"""Native renderer for mermaid ``erDiagram`` sources.
+
+Standalone module: exposes a single pure function, :func:`render_er`. 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_class.py`` and ``mermaid_flow.py``.
+
+This module does no layout or rasterization of its own. It parses mermaid
+``erDiagram`` source into the *same* :class:`~termrender.renderers.
+mermaid_flow_model.FlowGraph` the native flowchart engine consumes — each
+ER entity becomes a :class:`~termrender.renderers.mermaid_flow_model.
+FlowNode` (a compartmented box when the entity has an attribute block, a
+plain single-label box otherwise) and each ER relationship becomes a
+:class:`~termrender.renderers.mermaid_flow_model.FlowEdge` (a plain,
+headless line — ER cardinality is drawn as edge-label text, not an
+arrowhead glyph family) — 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 for how compartments render.
+
+Grammar supported
+------------------
+- Header: ``erDiagram``. Diagram direction is always top-to-bottom
+  (mermaid's erDiagram has no ``direction`` statement of its own, unlike
+  flowcharts/class diagrams).
+- Entity blocks: ``ENTITY { ... }``, either as a single line
+  (``CUSTOMER { string name PK }``) or spanning multiple lines up to a
+  standalone ``}``. Each attribute line is ``type name [PK|FK|UK[, ...]]
+  ["comment"]`` — type and name are required, the key marker(s) and the
+  trailing quoted comment are both optional. The comment is parsed (so it
+  doesn't corrupt the match) but dropped from the rendered row — see
+  *Known degradations*.
+- Bare entity declarations: ``ENTITY`` on its own line, and entities
+  referenced only from a relationship line (never given a block) — both
+  render as a plain single-label box (no compartments), matching
+  ``mermaid_class.py``'s bare-class handling.
+- Entity/attribute aliases: ``p[Person]`` (id ``p``, displayed as
+  ``Person``) and quoted names/ids containing spaces or punctuation
+  (``"driver's license"``, ``"Order Item"[OI]``) are recognized wherever
+  an entity token or an attribute name appears; the quotes are stripped
+  for display, the unquoted text is the graph key.
+- Relationships: ``ENTITY1 <left-card><line><right-card> ENTITY2 :
+  label``. ``<line>`` is ``--`` (identifying) or ``..`` (non-identifying);
+  identifying relationships render as a solid line, non-identifying as a
+  dashed line (:class:`EdgeStyle.DOTTED`, same glyphs the class-diagram
+  renderer uses for realization/dependency). ``<left-card>``/
+  ``<right-card>`` are mermaid's crow's-foot pairs read next to their
+  adjacent entity — ``||`` exactly one, ``o|``/``|o`` zero-or-one,
+  ``}|``/``|{`` one-or-more, ``}o``/``o{`` zero-or-more (both writing
+  directions accepted, per mermaid's own grammar) — translated to text
+  markers ``1``, ``0..1``, ``1..*``, ``0..*`` and combined with the
+  optional ``: label`` into one string (``"1 places 0..*"``), centered on
+  the edge by the engine. Relationship lines never draw an arrowhead
+  (``dst_arrow``/``src_arrow`` both ``False``) — ER cardinality is
+  conveyed entirely by the label text, not by a glyph family, since crow's
+  foot notation has no equivalent among the engine's existing arrow-kind
+  glyphs (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`` and ``mermaid_class.py`` — see those modules'
+docstrings for why this exact degradation matters to the crouter attach
+viewer).
+
+Known degradations (by design, not bugs)
+-----------------------------------------
+- Cardinality and the relation label are combined into a single string
+  centered on the edge (``"1 places 0..*"``), not three independently
+  placed annotations (one marker pinned at each endpoint plus a centered
+  label, the dedicated-ER-tool convention) — the underlying engine places
+  one label per edge, same limitation ``mermaid_class.py`` documents for
+  UML cardinalities.
+- No crow's-foot glyphs are drawn at the endpoints; cardinality is text
+  only. The engine's arrow-kind extension point supports UML triangle/
+  diamond families, not a crow's-foot family, and adding one is out of
+  scope for this renderer (an engine change, not a parser change).
+- Attribute comments (the trailing quoted string in an attribute line)
+  are parsed — so they don't break the match or leak into the name/key
+  columns — but dropped entirely from the rendered row rather than
+  wrapped or truncated onto a second line.
+- An entity declared with an empty block (``ENTITY { }``) still gets a
+  two-compartment box (title + a single blank attribute row) rather than
+  collapsing to a plain box — mirrors ``mermaid_class.py``'s
+  always-show-the-band-if-a-block-was-declared behavior for classes with
+  an empty fields/methods section.
+- 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 and class diagrams.
+"""
+
+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_er", "ERDiagramError"]
+
+
+class ERDiagramError(Exception):
+    """Raised when source cannot be parsed as a mermaid ER diagram at all."""
+
+
+# --------------------------------------------------------------------------
+# Grammar
+# --------------------------------------------------------------------------
+
+_HEADER_RE = re.compile(r"^erDiagram\b", re.IGNORECASE)
+_COMMENT_RE = re.compile(r"^%%")
+
+# An entity token: a quoted name (optionally aliased, `"Order Item"[OI]`),
+# or a bare run of non-space/non-brace characters (`CUSTOMER`, `p[Person]`,
+# `LINE-ITEM`). Used for bare declarations, block openers, and relationship
+# endpoints alike (see `_parse_entity_token`).
+_ENTITY_TOKEN = r'"[^"]*"(?:\[[^\]]*\])?|[^\s{]+'
+
+_ENTITY_TOKEN_RE = re.compile(r'^(?P<id>"[^"]*"|[^\[\s]+)(?:\[(?P<alias>[^\]]*)\])?$')
+_BLOCK_OPEN_RE = re.compile(rf"^(?P<idtok>{_ENTITY_TOKEN})\s*\{{(?P<inline>.*)$")
+_BARE_ENTITY_RE = re.compile(rf"^(?P<idtok>{_ENTITY_TOKEN})\s*$")
+
+# Attribute line: `type name [PK|FK|UK[, ...]] ["comment"]`. The comment is
+# matched (so it can't corrupt the name/keys columns) but never rendered.
+_ATTR_RE = re.compile(
+    r'^(?P<type>\S+)\s+(?P<name>"[^"]*"|\S+)'
+    r"(?:\s+(?P<keys>(?:PK|FK|UK)(?:\s*,\s*(?:PK|FK|UK))*))?"
+    r'(?:\s+"[^"]*")?\s*$',
+    re.IGNORECASE,
+)
+
+# Relationship operator: a left crow's-foot pair, a >=2-run dash/dot core
+# (dash = identifying/solid, dot = non-identifying/dashed), a right
+# crow's-foot pair. Searched against a quote-masked copy of the line (see
+# `_mask_quotes`) so a quoted entity/attribute name can never be mistaken
+# for the operator.
+_LEFT_CARD = r"\|o|\|\||\}o|\}\|"
+_RIGHT_CARD = r"o\||\|\||o\{|\|\{"
+_REL_OP_RE = re.compile(rf"(?P<left>{_LEFT_CARD})(?P<mid>--|\.\.)(?P<right>{_RIGHT_CARD})")
+_REL_LEFT_RE = re.compile(rf"^\s*(?P<idtok>{_ENTITY_TOKEN})\s*$")
+_REL_RIGHT_RE = re.compile(rf"^\s*(?P<idtok>{_ENTITY_TOKEN})\s*(?::\s*(?P<label>.*))?$")
+
+_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
+
+# Crow's-foot pair -> cardinality text, read from mermaid's own vocabulary
+# (both writing directions map to the same text on the side they sit next
+# to).
+_CARD_LEFT = {"|o": "0..1", "||": "1", "}o": "0..*", "}|": "1..*"}
+_CARD_RIGHT = {"o|": "0..1", "||": "1", "o{": "0..*", "|{": "1..*"}
+
+
+class _Entity:
+    """Mutable parse-time record for one ER entity — converted to a
+    :class:`FlowNode` at the end of parsing (see :func:`_build_graph`)."""
+
+    __slots__ = ("id", "display_name", "attrs", "has_block")
+
+    def __init__(self, id_: str, display_name: str) -> None:
+        self.id = id_
+        self.display_name = display_name
+        self.attrs: list[str] = []
+        self.has_block = False
+
+
+def _unquote(s: str) -> str:
+    if len(s) >= 2 and s[0] == '"' and s[-1] == '"':
+        return s[1:-1]
+    return s
+
+
+def _mask_quotes(line: str) -> str:
+    """Replace every quoted span with same-length filler so a quoted entity
+    or attribute name can never be mistaken for the relation operator when
+    searching for it (see `_REL_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 _parse_entity_token(token: str) -> tuple[str, str | None]:
+    """Split an entity token into its graph-key id and optional display
+    alias: ``CUSTOMER`` -> (``CUSTOMER``, None); ``p[Person]`` -> (``p``,
+    ``Person``); ``"Order Item"[OI]`` -> (``Order Item``, ``OI``)."""
+    m = _ENTITY_TOKEN_RE.match(token.strip())
+    if not m:
+        return _unquote(token.strip()), None
+    alias = m.group("alias")
+    return _unquote(m.group("id")), (alias.strip() if alias else None)
+
+
+def _get_or_create(entities: dict[str, _Entity], token: str) -> _Entity:
+    eid, alias = _parse_entity_token(token)
+    ent = entities.get(eid)
+    if ent is None:
+        ent = _Entity(eid, alias or eid)
+        entities[eid] = ent
+    elif alias:
+        ent.display_name = alias
+    return ent
+
+
+def _format_attr_row(m: re.Match[str]) -> str:
+    row = f"{m.group('type')} {_unquote(m.group('name'))}"
+    keys = m.group("keys")
+    if keys:
+        norm = re.sub(r"\s*,\s*", ", ", keys.strip()).upper()
+        row += f" {norm}"
+    return row
+
+
+def _consume_attrs(entity: _Entity, text: str) -> None:
+    """Split ``text`` (one physical line, or the inline body of an
+    ``ENTITY { ... }`` opener/closer) on ``;`` into individual attribute
+    statements and file each into ``entity``. An attribute that doesn't
+    match the ``type name [keys] [comment]`` grammar is dropped silently
+    (best-effort, never raised)."""
+    for part in text.split(";"):
+        part = part.strip()
+        if not part:
+            continue
+        m = _ATTR_RE.match(part)
+        if m:
+            entity.attrs.append(_format_attr_row(m))
+
+
+def _try_relation(
+    line: str, entities: dict[str, _Entity], edges: list[FlowEdge]
+) -> bool:
+    masked = _mask_quotes(line)
+    m = _REL_OP_RE.search(masked)
+    if not m:
+        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 = _get_or_create(entities, lm.group("idtok"))
+    dst = _get_or_create(entities, rm.group("idtok"))
+
+    style = EdgeStyle.DOTTED if m.group("mid") == ".." else EdgeStyle.SOLID
+    src_card = _CARD_LEFT.get(m.group("left"))
+    dst_card = _CARD_RIGHT.get(m.group("right"))
+    label_text = rm.group("label")
+    parts = [p for p in (src_card, label_text, dst_card) if p]
+    label = " ".join(parts) if parts else None
+
+    edges.append(
+        FlowEdge(
+            src=src.id,
+            dst=dst.id,
+            style=style,
+            label=label,
+            dst_arrow=False,
+            src_arrow=False,
+        )
+    )
+    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 ERDiagramError(
+            "not a mermaid ER diagram: source must start with 'erDiagram'"
+        )
+
+    entities: dict[str, _Entity] = {}
+    edges: list[FlowEdge] = []
+    seen_header = False
+    block_entity: _Entity | None = None
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        if block_entity is not None:
+            if line.endswith("}"):
+                _consume_attrs(block_entity, line[:-1])
+                block_entity = None
+            else:
+                _consume_attrs(block_entity, line)
+            continue
+
+        if not seen_header:
+            if _HEADER_RE.match(line):
+                seen_header = True
+            continue
+
+        if _COMMENT_RE.match(line):
+            continue
+
+        om = _BLOCK_OPEN_RE.match(line)
+        if om:
+            ent = _get_or_create(entities, om.group("idtok"))
+            ent.has_block = True
+            body = om.group("inline").rstrip()
+            if body.endswith("}"):
+                _consume_attrs(ent, body[:-1])
+            else:
+                _consume_attrs(ent, body)
+                block_entity = ent
+            continue
+
+        if _try_relation(line, entities, edges):
+            continue
+
+        bm = _BARE_ENTITY_RE.match(line)
+        if bm:
+            _get_or_create(entities, bm.group("idtok"))
+            continue
+
+        # Unrecognized line: consumed silently, best-effort.
+
+    if not seen_header:
+        raise ERDiagramError(
+            "not a mermaid ER diagram: source must start with 'erDiagram'"
+        )
+
+    nodes: list[FlowNode] = []
+    for ent in entities.values():
+        compartments = [[ent.display_name], ent.attrs or [""]] if ent.has_block else None
+        nodes.append(
+            FlowNode(
+                id=ent.id,
+                label=ent.display_name,
+                shape=NodeShape.RECT,
+                compartments=compartments,
+            )
+        )
+
+    return FlowGraph(direction=Direction.TB, 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_er(source: str, width: int) -> list[str]:
+    """Render a mermaid ``erDiagram`` 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 an ER diagram at all, parses to zero entities, 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
+            class-diagram 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 ERDiagramError:
+        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