termrender 0.1.0__py3-none-any.whl

termrender/__init__.py

@@ -0,0 +1,43 @@
+"""termrender — render Markdown to ANSI terminal output."""
+
+import os
+import shutil
+from termrender.parser import parse
+from termrender.layout import layout
+from termrender.emit import emit
+
+
+class TerminalError(Exception):
+    """Raised when the terminal does not support required capabilities."""
+
+
+def render(source: str, width: int | None = None, color: bool = True) -> str:
+    """Render directive-flavored markdown to ANSI terminal output.
+
+    Args:
+        source: Markdown string with optional directives
+        width: Terminal width in columns (auto-detected if None)
+        color: Enable ANSI color codes (respects NO_COLOR env var)
+
+    Returns:
+        Rendered string with ANSI escape sequences
+
+    Raises:
+        TerminalError: If terminal is unsupported (TERM=dumb)
+    """
+    # REQ-011: Check terminal capability
+    if os.environ.get("TERM") == "dumb":
+        raise TerminalError("Terminal type 'dumb' does not support Unicode rendering")
+
+    # Respect NO_COLOR convention (https://no-color.org/)
+    if os.environ.get("NO_COLOR") is not None:
+        color = False
+
+    # Auto-detect width
+    if width is None:
+        width = shutil.get_terminal_size().columns
+
+    # Pipeline: parse → layout → emit
+    doc = parse(source)
+    layout(doc, width)
+    return emit(doc, color)

termrender/__main__.py

@@ -0,0 +1,46 @@
+"""CLI entry point for termrender."""
+
+import argparse
+import sys
+
+from termrender import render, TerminalError
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="termrender",
+        description="Render Markdown to ANSI terminal output",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        type=argparse.FileType("r"),
+        default=sys.stdin,
+        help="Markdown file to render (reads stdin if omitted)",
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        default=None,
+        help="Terminal width in columns (auto-detected if omitted)",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI color output",
+    )
+    args = parser.parse_args()
+
+    source = args.file.read()
+
+    try:
+        output = render(source, width=args.width, color=not args.no_color)
+    except TerminalError as e:
+        print(f"termrender: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    sys.stdout.write(output)
+
+
+if __name__ == "__main__":
+    main()

termrender/blocks.py

@@ -0,0 +1,48 @@
+"""Core block data model for termrender."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class BlockType(Enum):
+    """Types of renderable blocks."""
+
+    DOCUMENT = "document"
+    PARAGRAPH = "paragraph"
+    HEADING = "heading"
+    PANEL = "panel"
+    COLUMNS = "columns"
+    COL = "col"
+    TREE = "tree"
+    CALLOUT = "callout"
+    QUOTE = "quote"
+    CODE = "code"
+    DIVIDER = "divider"
+    MERMAID = "mermaid"
+    LIST = "list"
+    LIST_ITEM = "list_item"
+
+
+@dataclass
+class InlineSpan:
+    """A span of inline text with optional formatting."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    code: bool = False
+
+
+@dataclass
+class Block:
+    """A renderable block element with optional children and inline text."""
+
+    type: BlockType
+    children: list[Block] = field(default_factory=list)
+    text: list[InlineSpan] = field(default_factory=list)
+    attrs: dict[str, Any] = field(default_factory=dict)
+    width: int | None = None
+    height: int | None = None

termrender/emit.py

@@ -0,0 +1,52 @@
+"""AST walker that dispatches laid-out blocks to renderers."""
+
+from __future__ import annotations
+
+from termrender.blocks import Block, BlockType
+from termrender.renderers import panel, columns, tree, code, text, divider, quote, mermaid
+
+
+def emit_block(block: Block, color: bool) -> list[str]:
+    """Render a single block and its children, returning output lines."""
+    match block.type:
+        case BlockType.DOCUMENT | BlockType.COL:
+            lines: list[str] = []
+            for child in block.children:
+                lines.extend(emit_block(child, color))
+            return lines
+
+        case BlockType.PANEL:
+            return panel.render(block, color, render_child=emit_block)
+
+        case BlockType.CALLOUT:
+            return panel.render_callout(block, color, render_child=emit_block)
+
+        case BlockType.COLUMNS:
+            return columns.render(block, color, render_child=emit_block)
+
+        case BlockType.QUOTE:
+            return quote.render(block, color, render_child=emit_block)
+
+        case BlockType.CODE:
+            return code.render(block, color, render_child=emit_block)
+
+        case BlockType.PARAGRAPH | BlockType.HEADING | BlockType.LIST | BlockType.LIST_ITEM:
+            return text.render(block, color)
+
+        case BlockType.TREE:
+            return tree.render(block, color)
+
+        case BlockType.MERMAID:
+            return mermaid.render(block, color)
+
+        case BlockType.DIVIDER:
+            return divider.render(block, color)
+
+        case _:
+            return []
+
+
+def emit(doc: Block, color: bool) -> str:
+    """Walk the block tree and return the fully rendered string."""
+    lines = emit_block(doc, color)
+    return "\n".join(lines)

termrender/layout.py

@@ -0,0 +1,134 @@
+"""Two-pass layout engine: resolve widths top-down, heights bottom-up."""
+
+from __future__ import annotations
+
+import subprocess
+
+from termrender.blocks import Block, BlockType
+from termrender.style import wrap_text
+
+
+def _plain_text(spans: list) -> str:
+    return "".join(s.text for s in spans)
+
+
+def resolve_width(block: Block, available: int) -> None:
+    block.width = available
+
+    bt = block.type
+    if bt in (BlockType.PANEL, BlockType.CALLOUT, BlockType.CODE, BlockType.QUOTE):
+        inner = max(available - 4, 1)
+        for child in block.children:
+            resolve_width(child, inner)
+
+    elif bt == BlockType.COLUMNS:
+        n = len(block.children)
+        if n == 0:
+            return
+        gaps = n - 1
+        inner = available
+
+        # Separate children into explicit-width and auto-width
+        explicit: dict[int, int] = {}
+        for i, col in enumerate(block.children):
+            w = col.attrs.get("width")
+            if w is not None:
+                w_str = str(w)
+                try:
+                    if w_str.endswith("%"):
+                        explicit[i] = max(int(inner * float(w_str[:-1]) / 100), 1)
+                    else:
+                        explicit[i] = max(int(w_str), 1)
+                except ValueError:
+                    pass
+
+        used = sum(explicit.values()) + gaps
+        remaining = max(inner - used, 0)
+        auto_count = n - len(explicit)
+
+        for i, col in enumerate(block.children):
+            if i in explicit:
+                col_w = explicit[i]
+            elif auto_count > 0:
+                col_w = max(remaining // auto_count, 1)
+            else:
+                col_w = 1
+            resolve_width(col, col_w)
+
+    else:
+        for child in block.children:
+            resolve_width(child, available)
+
+
+def resolve_height(block: Block) -> None:
+    # Recurse children first (bottom-up)
+    for child in block.children:
+        resolve_height(child)
+
+    bt = block.type
+    width = block.width or 1
+
+    if bt == BlockType.PARAGRAPH:
+        text = _plain_text(block.text)
+        lines = wrap_text(text, width)
+        block.height = len(lines)
+
+    elif bt == BlockType.HEADING:
+        block.height = 1
+
+    elif bt == BlockType.DIVIDER:
+        block.height = 1
+
+    elif bt in (BlockType.PANEL, BlockType.CALLOUT):
+        block.height = sum(c.height or 0 for c in block.children) + 2
+
+    elif bt == BlockType.CODE:
+        source = block.attrs.get("source") or _plain_text(block.text)
+        code_lines = source.split("\n") if source else [""]
+        block.height = len(code_lines) + 2
+
+    elif bt == BlockType.COLUMNS:
+        block.height = max((c.height or 0 for c in block.children), default=0)
+
+    elif bt in (BlockType.COL, BlockType.DOCUMENT, BlockType.LIST):
+        block.height = sum(c.height or 0 for c in block.children)
+
+    elif bt == BlockType.LIST_ITEM:
+        text_height = 0
+        if block.text:
+            text_lines = wrap_text(_plain_text(block.text), max(width - 2, 1))
+            text_height = len(text_lines)
+        block.height = text_height + sum(c.height or 0 for c in block.children)
+
+    elif bt == BlockType.TREE:
+        source = block.attrs.get("source", "")
+        block.height = len(source.split("\n")) if source else 1
+
+    elif bt == BlockType.MERMAID:
+        source = block.attrs.get("source", "") or _plain_text(block.text)
+        rendered = source  # fallback
+        try:
+            result = subprocess.run(
+                ["mermaid-ascii", "-f", "-"],
+                input=source,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=30,
+            )
+            rendered = result.stdout
+        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+        block.attrs["_rendered"] = rendered
+        block.height = len(rendered.split("\n")) if rendered else 1
+
+    elif bt == BlockType.QUOTE:
+        block.height = sum(c.height or 0 for c in block.children) + (1 if block.attrs.get("by") else 0)
+
+    else:
+        block.height = sum(c.height or 0 for c in block.children)
+
+
+def layout(doc: Block, width: int) -> None:
+    resolve_width(doc, width)
+    resolve_height(doc)

termrender/parser.py

@@ -0,0 +1,322 @@
+"""Two-pass markdown+directive parser for termrender.
+
+Pass 1 (directive pass): Scans raw source for :::name{attrs} directives using
+a stack-based depth tracker. Segments between directives are plain markdown.
+
+Pass 2 (mistune pass): Parses plain markdown segments via mistune v3 AST mode,
+then converts the dict-based AST into our Block tree.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import mistune
+
+from termrender.blocks import Block, BlockType, InlineSpan
+
+# Matches ANSI escape sequences that are NOT SGR (Select Graphic Rendition).
+# SGR sequences have the form \x1b[...m — we keep those.
+# Strip OSC (\x1b]), screen control (\x1b[...J, \x1b[...H, etc.), and others.
+_UNSAFE_ANSI_RE = re.compile(
+    r'\x1b'           # ESC
+    r'(?!'             # negative lookahead: don't match SGR
+    r'\[[0-9;]*m'      # SGR pattern
+    r')'
+    r'[\x20-\x7e]*'   # match the rest of the sequence
+)
+
+
+def _sanitize_text(text: str) -> str:
+    """Strip non-SGR ANSI escape sequences from text."""
+    return _UNSAFE_ANSI_RE.sub('', text)
+
+# Directive opener: :::name or :::name{attrs}
+_DIRECTIVE_OPEN = re.compile(
+    r"^:::(\w+)(?:\{([^}]*)\})?\s*$"
+)
+# Directive closer: exactly ::: on its own line
+_DIRECTIVE_CLOSE = re.compile(r"^:::\s*$")
+
+# Attribute parser: key=value or key="quoted value"
+_ATTR_PAIR = re.compile(
+    r"""(\w+)\s*=\s*(?:"([^"]*?)"|(\S+))"""
+)
+
+_DIRECTIVE_TO_BLOCK: dict[str, BlockType] = {
+    "panel": BlockType.PANEL,
+    "columns": BlockType.COLUMNS,
+    "col": BlockType.COL,
+    "tree": BlockType.TREE,
+    "callout": BlockType.CALLOUT,
+    "quote": BlockType.QUOTE,
+    "code": BlockType.CODE,
+    "divider": BlockType.DIVIDER,
+}
+
+_mistune_md = mistune.create_markdown(renderer="ast")
+
+
+def _parse_attrs(raw: str | None) -> dict[str, Any]:
+    """Parse directive attributes from {key=value key2="quoted"} string."""
+    if not raw:
+        return {}
+    attrs: dict[str, Any] = {}
+    for m in _ATTR_PAIR.finditer(raw):
+        key = m.group(1)
+        value = m.group(2) if m.group(2) is not None else m.group(3)
+        attrs[key] = value
+    return attrs
+
+
+def _convert_inline(nodes: list[dict]) -> list[InlineSpan]:
+    """Convert mistune inline AST nodes to InlineSpan list."""
+    spans: list[InlineSpan] = []
+    for node in nodes:
+        ntype = node["type"]
+        if ntype == "text":
+            spans.append(InlineSpan(text=_sanitize_text(node["raw"])))
+        elif ntype == "codespan":
+            spans.append(InlineSpan(text=node["raw"], code=True))
+        elif ntype == "strong":
+            for child in _convert_inline(node.get("children", [])):
+                spans.append(InlineSpan(text=child.text, bold=True, italic=child.italic, code=child.code))
+        elif ntype == "emphasis":
+            for child in _convert_inline(node.get("children", [])):
+                spans.append(InlineSpan(text=child.text, italic=True, bold=child.bold, code=child.code))
+        elif ntype == "softbreak":
+            spans.append(InlineSpan(text=" "))
+        elif ntype == "linebreak":
+            spans.append(InlineSpan(text="\n"))
+        else:
+            # Fallback: try raw text
+            if "raw" in node:
+                spans.append(InlineSpan(text=node["raw"]))
+            elif "children" in node:
+                spans.extend(_convert_inline(node["children"]))
+    return spans
+
+
+def _convert_ast(nodes: list[dict]) -> list[Block]:
+    """Convert mistune AST nodes into Block tree."""
+    blocks: list[Block] = []
+    for node in nodes:
+        ntype = node["type"]
+
+        if ntype == "blank_line":
+            continue
+
+        if ntype == "heading":
+            level = node.get("attrs", {}).get("level", 1)
+            text = _convert_inline(node.get("children", []))
+            blocks.append(Block(
+                type=BlockType.HEADING,
+                text=text,
+                attrs={"level": level},
+            ))
+
+        elif ntype == "paragraph":
+            text = _convert_inline(node.get("children", []))
+            blocks.append(Block(type=BlockType.PARAGRAPH, text=text))
+
+        elif ntype == "block_code":
+            raw = node.get("raw", "")
+            info = node.get("attrs", {}).get("info", "")
+            if info == "mermaid":
+                blocks.append(Block(
+                    type=BlockType.MERMAID,
+                    attrs={"source": raw},
+                ))
+            else:
+                blocks.append(Block(
+                    type=BlockType.CODE,
+                    attrs={"lang": info, "source": raw},
+                ))
+
+        elif ntype == "list":
+            ordered = node.get("attrs", {}).get("ordered", False)
+            items: list[Block] = []
+            for item_node in node.get("children", []):
+                if item_node["type"] == "list_item":
+                    item_children = item_node.get("children", [])
+                    # list_item contains block_text nodes
+                    item_spans: list[InlineSpan] = []
+                    sub_blocks: list[Block] = []
+                    for child in item_children:
+                        if child["type"] == "block_text":
+                            item_spans.extend(_convert_inline(child.get("children", [])))
+                        else:
+                            sub_blocks.extend(_convert_ast([child]))
+                    items.append(Block(
+                        type=BlockType.LIST_ITEM,
+                        text=item_spans,
+                        children=sub_blocks,
+                    ))
+            blocks.append(Block(
+                type=BlockType.LIST,
+                children=items,
+                attrs={"ordered": ordered},
+            ))
+
+        elif ntype == "thematic_break":
+            blocks.append(Block(type=BlockType.DIVIDER))
+
+        elif ntype == "block_quote":
+            children = _convert_ast(node.get("children", []))
+            blocks.append(Block(type=BlockType.QUOTE, children=children))
+
+        else:
+            # Unknown block type - try to extract any content
+            if "children" in node:
+                blocks.extend(_convert_ast(node["children"]))
+
+    return blocks
+
+
+def _parse_markdown(source: str) -> list[Block]:
+    """Parse a markdown string via mistune and convert to Block list."""
+    if not source.strip():
+        return []
+    ast_nodes = _mistune_md(source)
+    return _convert_ast(ast_nodes)
+
+
+def _split_directives(source: str) -> list[dict]:
+    """Split source into directive and markdown segments.
+
+    Returns a list of segments, each being either:
+      {"type": "markdown", "content": str}
+      {"type": "directive", "name": str, "attrs": dict, "body": str}
+    """
+    lines = source.split("\n")
+    segments: list[dict] = []
+    current_md_lines: list[str] = []
+    stack: list[dict] = []  # stack of open directives
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Check for directive opener
+        m_open = _DIRECTIVE_OPEN.match(line)
+        if m_open:
+            if not stack:
+                # Top-level directive opening — flush accumulated markdown
+                if current_md_lines:
+                    segments.append({
+                        "type": "markdown",
+                        "content": "\n".join(current_md_lines),
+                    })
+                    current_md_lines = []
+                entry = {
+                    "name": m_open.group(1),
+                    "attrs_raw": m_open.group(2),
+                    "body_lines": [],
+                    "depth": 1,
+                }
+                # Self-closing directives (no body content expected)
+                if entry["name"] in ("divider",):
+                    segments.append({
+                        "type": "directive",
+                        "name": entry["name"],
+                        "attrs": _parse_attrs(entry["attrs_raw"]),
+                        "body": "",
+                    })
+                else:
+                    stack.append(entry)
+            else:
+                # Nested directive — track depth and include line in body
+                stack[-1]["depth"] += 1
+                stack[-1]["body_lines"].append(line)
+            i += 1
+            continue
+
+        # Check for directive closer
+        m_close = _DIRECTIVE_CLOSE.match(line)
+        if m_close and stack:
+            if stack[-1]["depth"] > 1:
+                # Closing a nested directive
+                stack[-1]["depth"] -= 1
+                stack[-1]["body_lines"].append(line)
+            else:
+                # Closing the top-level directive
+                entry = stack.pop()
+                segments.append({
+                    "type": "directive",
+                    "name": entry["name"],
+                    "attrs": _parse_attrs(entry["attrs_raw"]),
+                    "body": "\n".join(entry["body_lines"]),
+                })
+            i += 1
+            continue
+
+        # Regular line
+        if stack:
+            stack[-1]["body_lines"].append(line)
+        else:
+            current_md_lines.append(line)
+        i += 1
+
+    # Flush remaining markdown
+    if current_md_lines:
+        segments.append({
+            "type": "markdown",
+            "content": "\n".join(current_md_lines),
+        })
+
+    # If stack is not empty, treat unclosed directives as markdown
+    for entry in stack:
+        body = "\n".join(entry["body_lines"])
+        segments.append({
+            "type": "markdown",
+            "content": f":::{entry['name']}\n{body}",
+        })
+
+    return segments
+
+
+_MAX_PARSE_DEPTH = 50
+
+
+def _directive_to_block(name: str, attrs: dict[str, Any], body: str, _depth: int = 0) -> Block:
+    """Convert a parsed directive into a Block."""
+    block_type = _DIRECTIVE_TO_BLOCK.get(name, BlockType.PANEL)
+
+    # Tree and Code directives: store raw body, don't parse as markdown
+    if block_type in (BlockType.TREE, BlockType.CODE):
+        attrs["source"] = body
+        return Block(type=block_type, attrs=attrs)
+
+    # Divider: no children
+    if block_type == BlockType.DIVIDER:
+        return Block(type=BlockType.DIVIDER, attrs=attrs)
+
+    # Recursively parse the body through the full two-pass pipeline
+    body_doc = parse(body, _depth=_depth + 1)
+    return Block(
+        type=block_type,
+        children=body_doc.children,
+        attrs=attrs,
+    )
+
+
+def parse(source: str, _depth: int = 0) -> Block:
+    """Parse markdown+directive source into a Block tree.
+
+    Returns a Block with type=DOCUMENT as root.
+    """
+    if _depth > _MAX_PARSE_DEPTH:
+        raise ValueError(f"Maximum directive nesting depth ({_MAX_PARSE_DEPTH}) exceeded")
+    segments = _split_directives(source)
+    children: list[Block] = []
+
+    for seg in segments:
+        if seg["type"] == "markdown":
+            children.extend(_parse_markdown(seg["content"]))
+        else:
+            children.append(_directive_to_block(
+                seg["name"], seg["attrs"], seg["body"], _depth=_depth,
+            ))
+
+    return Block(type=BlockType.DOCUMENT, children=children)

termrender/renderers/__init__.py

@@ -0,0 +1 @@
+"""Block-type renderers for termrender."""