termrender 4.8.0__tar.gz → 4.9.0__tar.gz

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

@@ -1,6 +1,23 @@
 # CHANGELOG
 
 
+## 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.8.0
+Version: 4.9.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.9.0/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

termrender-4.9.0/tests/test_mermaid_er.py

@@ -0,0 +1,302 @@
+"""Golden-output tests for the native mermaid erDiagram renderer.
+
+Mirrors ``test_mermaid_class.py``'s methodology: real rendered geometry
+(exact line lists, or topology assertions on a full relation chain), not
+merely "no exception raised". ``render_er`` reuses the flowchart engine's
+grandalf layout + rasterizer + router (via the shared ``FlowGraph``/
+``FlowNode``/``FlowEdge`` model — see ``mermaid_er.py``'s module
+docstring), so these tests exercise the ER-specific parsing (attribute
+blocks, cardinality-to-text mapping, aliasing) end to end rather than
+re-testing the underlying engine (already covered by
+``test_mermaid_flow_corpus.py``/``test_mermaid_flow_shapes.py``).
+"""
+
+from __future__ import annotations
+
+import re
+
+from termrender.renderers.mermaid_er import render_er
+
+_BOX_GLYPH_RE = re.compile(r"[\u2500-\u259F\u25A0-\u25FF]")
+
+
+def _lines(source: str, width: int = 80) -> list[str]:
+    return render_er(source, width)
+
+
+def _has_box_glyphs(lines: list[str]) -> bool:
+    return any(_BOX_GLYPH_RE.search(line) for line in lines)
+
+
+def _row_col(lines: list[str], glyph: str) -> tuple[int, int]:
+    for r, line in enumerate(lines):
+        c = line.find(glyph)
+        if c != -1:
+            return r, c
+    raise AssertionError(f"glyph {glyph!r} not found in {lines!r}")
+
+
+# --------------------------------------------------------------------------
+# Compartmented entities
+# --------------------------------------------------------------------------
+
+
+def test_multiline_entity_block_compartments():
+    src = (
+        "erDiagram\n"
+        "CUSTOMER {\n"
+        "    string name\n"
+        "    string custNumber\n"
+        "    string sector\n"
+        "}\n"
+    )
+    assert _lines(src) == [
+        "┌───────────────────┐",
+        "│     CUSTOMER      │",
+        "├───────────────────┤",
+        "│ string name       │",
+        "│ string custNumber │",
+        "│ string sector     │",
+        "└───────────────────┘",
+    ]
+
+
+def test_oneline_semicolon_entity_block():
+    src = "erDiagram\nENTITY { string name PK; int qty }\n"
+    lines = _lines(src)
+    assert lines[0].startswith("┌")
+    assert any("name PK" in line for line in lines)
+    assert any("qty" in line for line in lines)
+    sep_rows = [i for i, l in enumerate(lines) if set(l.strip()) <= {"├", "─", "┤"}]
+    assert len(sep_rows) == 1
+
+
+def test_bare_entity_no_block_is_plain_box_not_compartmented():
+    assert _lines("erDiagram\nFOO\n") == [
+        "┌─────┐",
+        "│ FOO │",
+        "└─────┘",
+    ]
+
+
+def test_entity_referenced_only_in_relationship_is_plain_box():
+    lines = _lines("erDiagram\nA ||--o{ B : has\n")
+    # Neither A nor B ever got a `{ ... }` block -> both are plain boxes
+    # (no separator rows anywhere in the output).
+    sep_rows = [i for i, l in enumerate(lines) if set(l.strip()) <= {"├", "─", "┤"}]
+    assert sep_rows == []
+
+
+def test_entity_with_empty_block_still_shows_blank_attribute_row():
+    src = "erDiagram\nFOO {\n}\n"
+    lines = _lines(src)
+    sep_rows = [i for i, l in enumerate(lines) if set(l.strip()) <= {"├", "─", "┤"}]
+    assert len(sep_rows) == 1
+    assert any(l.strip("│ ") == "" for l in lines)
+
+
+def test_attribute_comment_is_dropped_but_does_not_corrupt_parse():
+    src = 'erDiagram\nFOO {\n  string code PK "a helpful comment"\n}\n'
+    lines = _lines(src)
+    assert any("code PK" in line for line in lines)
+    assert not any("helpful comment" in line for line in lines)
+
+
+# --------------------------------------------------------------------------
+# Aliases / quoted names
+# --------------------------------------------------------------------------
+
+
+def test_entity_alias_bracket_form_displays_alias_not_id():
+    lines = _lines("erDiagram\np[Person] {\n  string name\n}\n")
+    assert any("Person" in line for line in lines)
+    assert not any("p[Person]" in line for line in lines)
+
+
+def test_alias_declared_once_resolves_same_node_from_relation():
+    src = "erDiagram\np[Person] {\n  string name\n}\np ||--o{ CAR : owns\n"
+    lines = _lines(src)
+    assert sum(1 for line in lines if "Person" in line) == 1
+    assert any("CAR" in line for line in lines)
+
+
+def test_quoted_attribute_name_with_apostrophe():
+    src = 'erDiagram\nPERSON {\n  string "driver\'s license" UK\n}\n'
+    lines = _lines(src)
+    assert any("driver's license" in line for line in lines)
+    assert not any('"' in line for line in lines)
+
+
+def test_quoted_entity_name_with_alias():
+    src = 'erDiagram\n"Order Item"[OI] {\n  int qty\n}\n'
+    lines = _lines(src)
+    assert any("OI" in line for line in lines)
+    assert not any("Order Item" in line for line in lines)
+
+
+# --------------------------------------------------------------------------
+# Cardinality grammar (all four kinds, both writing directions) + line style
+# --------------------------------------------------------------------------
+
+
+def test_exactly_one_cardinality_both_sides():
+    lines = _lines("erDiagram\nA ||--|| B : rel\n")
+    assert any("1 rel 1" in line for line in lines)
+
+
+def test_zero_or_one_left_and_right_forms():
+    left = _lines("erDiagram\nA |o--|| B : rel\n")
+    right = _lines("erDiagram\nA ||--o| B : rel\n")
+    assert any("0..1 rel 1" in line for line in left)
+    assert any("1 rel 0..1" in line for line in right)
+
+
+def test_one_or_more_left_and_right_forms():
+    left = _lines("erDiagram\nA }|--|| B : rel\n")
+    right = _lines("erDiagram\nA ||--|{ B : rel\n")
+    assert any("1..* rel 1" in line for line in left)
+    assert any("1 rel 1..*" in line for line in right)
+
+
+def test_zero_or_more_left_and_right_forms():
+    left = _lines("erDiagram\nA }o--|| B : rel\n")
+    right = _lines("erDiagram\nA ||--o{ B : rel\n")
+    assert any("0..* rel 1" in line for line in left)
+    assert any("1 rel 0..*" in line for line in right)
+
+
+def test_cardinality_without_label():
+    lines = _lines("erDiagram\nCUSTOMER ||--o{ ORDER\n")
+    assert any("1 0..*" in line for line in lines)
+
+
+def test_identifying_relation_is_solid_line():
+    lines = _lines("erDiagram\nA ||--o{ B : has\n")
+    joined = "\n".join(lines)
+    assert "│" in joined
+    assert "╎" not in joined
+
+
+def test_non_identifying_relation_is_dashed_line():
+    lines = _lines("erDiagram\nA ||..o{ B : has\n")
+    joined = "\n".join(lines)
+    assert "╎" in joined
+
+
+def test_relationship_never_draws_an_arrowhead():
+    lines = _lines("erDiagram\nA ||--o{ B : has\n")
+    joined = "\n".join(lines)
+    for glyph in ("▲", "▼", "◀", "▶"):
+        assert glyph not in joined
+
+
+# --------------------------------------------------------------------------
+# Full topology: a small multi-entity chain
+# --------------------------------------------------------------------------
+
+
+def test_multi_entity_chain_topology():
+    src = "erDiagram\nA ||--o{ B : ab\nB ||--o{ C : bc\n"
+    lines = _lines(src)
+    assert _has_box_glyphs(lines)
+    for name in "ABC":
+        assert any(name == line.strip("│ ") for line in lines)
+    a_row, _ = _row_col(lines, "A")
+    b_row, _ = _row_col(lines, "B")
+    c_row, _ = _row_col(lines, "C")
+    assert a_row < b_row < c_row  # linear TB chain, declaration order
+
+
+# --------------------------------------------------------------------------
+# Golden corpus: mermaid docs' classic order example
+# --------------------------------------------------------------------------
+
+
+def test_order_example_golden_topology():
+    src = (
+        "erDiagram\n"
+        "    CUSTOMER ||--o{ ORDER : places\n"
+        "    ORDER ||--|{ LINE-ITEM : contains\n"
+        "    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses\n"
+        "\n"
+        "    CUSTOMER {\n"
+        "        string name\n"
+        "        string custNumber\n"
+        "        string sector\n"
+        "    }\n"
+        "    ORDER {\n"
+        "        int orderNumber\n"
+        "        string deliveryAddress\n"
+        "    }\n"
+        "    LINE-ITEM {\n"
+        "        string productCode\n"
+        "        int quantity\n"
+        "        float pricePerUnit\n"
+        "    }\n"
+    )
+    lines = _lines(src)
+    assert _has_box_glyphs(lines)
+    joined = "\n".join(lines)
+
+    for name in ("CUSTOMER", "ORDER", "LINE-ITEM", "DELIVERY-ADDRESS"):
+        assert name in joined
+
+    # DELIVERY-ADDRESS never got a block -> plain box; the other three did.
+    da_row, da_col = _row_col(lines, "DELIVERY-ADDRESS")
+    assert lines[da_row][da_col - 2] == "│"  # ` DELIVERY-ADDRESS ` inside a border
+
+    for attr in ("string name", "string custNumber", "string sector"):
+        assert attr in joined
+    for attr in ("int orderNumber", "string deliveryAddress"):
+        assert attr in joined
+    for attr in ("string productCode", "int quantity", "float pricePerUnit"):
+        assert attr in joined
+
+    assert "places" in joined
+    assert "contains" in joined
+    assert "uses" in joined
+
+    # Non-identifying relation (CUSTOMER }|..|{ DELIVERY-ADDRESS) is dashed.
+    assert "╎" in joined
+
+    cust_row, _ = _row_col(lines, "CUSTOMER")
+    order_row, _ = _row_col(lines, "ORDER")
+    line_item_row, _ = _row_col(lines, "LINE-ITEM")
+    assert cust_row < order_row < line_item_row
+
+
+# --------------------------------------------------------------------------
+# Degradation: malformed input, empty body, literal-glyph sanitization
+# --------------------------------------------------------------------------
+
+
+def test_non_er_diagram_source_degrades_to_raw_echo():
+    src = "graph TD\nA-->B\n"
+    lines = _lines(src)
+    assert lines == ["graph TD", "A-->B"]
+    assert not _has_box_glyphs(lines)
+
+
+def test_header_only_empty_body_degrades_to_raw_echo():
+    lines = _lines("erDiagram\n")
+    assert lines == ["erDiagram"]
+    assert not _has_box_glyphs(lines)
+
+
+def test_malformed_input_with_literal_box_glyph_is_sanitized():
+    src = "not an er diagram\nhas a \u2500 literal glyph\n"
+    lines = _lines(src)
+    assert lines == ["not an er diagram", "has a ? literal glyph"]
+    assert not _has_box_glyphs(lines)
+
+
+def test_render_er_never_raises_on_garbage():
+    for garbage in (
+        "",
+        "\n\n\n",
+        "erDiagram\nFOO {{{\n",
+        "erDiagram\n}}}}\n",
+        "erDiagram\nA ||-- B\n",  # missing right cardinality pair
+        'erDiagram\nA { string "unterminated PK\n',
+    ):
+        render_er(garbage, 80)  # must not raise