merminal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbe165ab1447fb74478d15f529f288a7693359b49df68e981ace194c9a4d543f
+  data.tar.gz: d77e448ca8c2b4300c5468040c259ff7aeaf48b190ba35c66bac413feef88594
+SHA512:
+  metadata.gz: cd06fee96beec91b0eaee71c387811fac366844213f2e4fa635840b31d2986c27a8f12762410e27d48878867e936f52fb1a83a374d70272b805dca3e0bc195f0
+  data.tar.gz: 65b2310ad2a6d7576fb3bc9be2f4748a1db423f0f55e7bc07e2e73f9947d62b136ac569d201dca385b16ef8d006df323d1774c808a51c17f78d0e647a0a8fe93

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-22
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# merminal
+
+merminal is a pure Ruby terminal renderer for Mermaid diagrams. It runs without Node.js, a browser, external processes, or runtime gem dependencies. The Ruby API namespace is `Merminal`.
+
+## Install
+
+From this checkout:
+
+```sh
+gem build merminal.gemspec
+gem install ./merminal-0.1.0.gem
+```
+
+Ruby 3.3 or newer is required.
+
+## CLI
+
+```sh
+printf 'flowchart LR\nA[Start] --> B[Done]\n' | merminal
+merminal --ascii diagram.mmd
+merminal --check --strict diagram.mmd
+merminal --markdown README.md
+merminal --width 80 --theme solarized --color always diagram.mmd
+```
+
+`merminal --help` lists every option. When a requested width cannot hold the diagram, the CLI reports the actual width and keeps the full drawing.
+
+## Ruby API
+
+```ruby
+require "merminal"
+
+puts Merminal.render("flowchart LR\nA --> B")
+document = Merminal.parse("pie\n\"A\" : 3\n\"B\" : 7")
+warn document.diagnostics.map(&:to_s).join("\n")
+puts document.render(charset: :ascii)
+
+Merminal.markdown_blocks("```mermaid\ngraph LR\nA-->B\n```").each do |block|
+  puts block.line, block.render
+end
+```
+
+`Merminal.register` accepts a plugin with `diagram_type`, `keywords`, `parse(source)`, and `layout(ast, **options)` methods. `Document#scene` exposes immutable drawing primitives. The Scene and plugin interfaces are experimental.
+
+## Supported diagrams
+
+The parser accepts the Mermaid diagram declarations listed below. The core types
+have dedicated parsers and layouts; the additional syntax types also have
+diagram-specific semantic handling and terminal layouts. Core parser errors produce
+line numbered diagnostics; additional syntax follows the documented subset and ignores
+browser-only directives that have no terminal representation.
+
+| Diagram | Syntax |
+|---|---|
+| Flowchart | [Flowchart](docs/syntax/flowchart.md) |
+| Sequence | [Sequence](docs/syntax/sequence.md) |
+| State | [State](docs/syntax/state.md) |
+| Class | [Class](docs/syntax/class.md) |
+| ER | [ER](docs/syntax/er.md) |
+| Pie | [Pie](docs/syntax/pie.md) |
+| XY chart | [XY chart](docs/syntax/xychart.md) |
+| Gantt | [Gantt](docs/syntax/gantt.md) |
+| Timeline | [Timeline](docs/syntax/timeline.md) |
+| Mindmap | [Mindmap](docs/syntax/mindmap.md) |
+| Additional syntax diagrams | [Use case, requirement, journey, GitGraph, C4, quadrant, Sankey, block, packet, Kanban, architecture, radar, treemap, Venn, Ishikawa, Wardley, TreeView, Cynefin, swimlane, Event Modeling, Agentflow, ZenUML, Railroad syntax diagrams](docs/syntax/additional.md) |
+
+The [gallery](gallery.html) shows Unicode, ASCII, and the four color themes for every fixture.
+
+Pie charts appear as horizontal bars because cell based terminals communicate proportions more clearly that way. Unicode ambiguous width defaults to one cell; set `ambiguous_width: 2` for terminals that use two. Emoji ZWJ sequences use the first grapheme code point's width, so some terminal fonts may differ. ASCII mode replaces non ASCII labels with `?`.
+
+This is an independent implementation. Thanks to [termaid](https://github.com/fasouto/termaid), [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii), and [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) for showing what terminal Mermaid tools can offer. Mermaid syntax belongs to the [Mermaid project](https://mermaid.js.org/).
+
+## Known limitations
+
+Self loops use outside lanes, and dense edge labels can still cross lines. [The structural layout decision](docs/adr/003-layout.md) and [scene boundary](docs/adr/002-scene.md) describe the architecture. Scene and plugin interfaces are experimental.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec
+bundle exec rake gallery
+```
+
+`rake unicode:generate` accepts `EAW_FILE` and `UCD_FILE` paths to the official Unicode 17.0 files. It regenerates the checked in width and box drawing tables.

data/docs/adr/000-template.md

@@ -0,0 +1,24 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its compatibility, data,
+runtime, or component constraints. Operational workflow and release policy do
+not belong in this directory; see [the scope](README.md).
+
+Name the credible alternatives. If there was no meaningful alternative, record
+the behavior in reference documentation instead of creating an ADR.
+
+## Decision
+
+Describe the durable boundary or architecture choice. Leave command syntax,
+field-by-field formats, test evidence, benchmark results, and migration steps
+in their authoritative documents.
+
+## Consequences
+
+Describe the important positive and negative trade-offs, including what would
+make this decision worth revisiting.

data/docs/adr/001-runtime.md

@@ -0,0 +1,19 @@
+# ADR 001: Runtime baseline
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Terminal use should work in Ruby environments with limited package access. The
+implementation uses current Ruby language features and its standard library.
+
+## Decision
+
+Require CRuby 3.3 or newer and keep runtime gem dependencies at zero.
+
+## Consequences
+
+Users install no additional runtime gems. The implementation stays small by
+targeting one maintained Ruby baseline; other Ruby implementations are tested
+as best effort.

data/docs/adr/002-scene.md

@@ -0,0 +1,18 @@
+# ADR 002: Scene layer
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Diagram layout should not choose terminal border characters. Letting each
+diagram plugin render terminal cells would duplicate rasterization behavior.
+
+## Decision
+
+Pass immutable geometric Scene primitives to one shared rasterizer.
+
+## Consequences
+
+All diagrams share line joining, themes, width fitting, and ASCII fallback.
+Plugins remain independent of terminal cell representation.

data/docs/adr/003-layout.md

@@ -0,0 +1,20 @@
+# ADR 003: Structural diagram layout
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Flow, state, class, and ER diagrams need predictable placement and routing. A
+shared layout model avoids a separate strategy for each structural diagram.
+
+## Decision
+
+Use a deterministic layered layout with rank channels. Reserve space for long
+edges and labels before routing, keep nested subgraphs together, and route loops
+through outside lanes.
+
+## Consequences
+
+Structural diagrams share predictable placement and routing. The exact sweep,
+crossing, and rasterization algorithms remain implementation details.

data/docs/adr/004-parser.md

@@ -0,0 +1,19 @@
+# ADR 004: Parser diagnostics
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Real Mermaid files may contain unsupported statements. Rejecting an entire
+document would hide the parts that can still be rendered.
+
+## Decision
+
+Collect line-numbered diagnostics and render recognized statements. Raise in
+strict mode so callers can choose partial or validated parsing.
+
+## Consequences
+
+Partial diagrams remain useful while CI can enforce strict parsing. Syntax
+reference documents define the accepted subset.

data/docs/adr/005-public-api.md

@@ -0,0 +1,23 @@
+# ADR 005: Public API boundary
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+The documented render and parse calls need a stable contract. Scene primitives
+and plugin parsing methods expose layout internals that may change as more
+syntax is supported.
+
+## Decision
+
+The intended stable v1.0 API is the render, parse, Markdown extraction, diagram
+registration, and diagram type calls documented in the README and RBS. Their
+document and block result fields are stable as documented.
+
+Keep `Document#scene`, Scene primitives, and the plugin interface experimental at v1.0. Their names are available for advanced use, but their shape may change in later minor versions.
+
+## Consequences
+
+RBS describes the stable calls. Scene primitives and plugin interfaces remain
+experimental extension points.

data/docs/adr/README.md

@@ -0,0 +1,10 @@
+# Architecture Decision Records
+
+This directory records durable implementation choices that affect component or
+runtime boundaries and had credible alternatives. API reference, command syntax,
+field formats, test evidence, benchmark results, migrations, release policy, and
+operational workflow belong in their authoritative documentation instead.
+
+Copy [ADR 000](000-template.md) when recording a decision. Decision records use
+three-digit numbers starting at `001`, assigned without gaps. Keep accepted,
+rejected, and superseded records so later entries do not need renumbering.

data/docs/syntax/additional.md

@@ -0,0 +1,58 @@
+# Additional Mermaid syntax diagrams
+
+The parser recognizes the Mermaid syntax declarations below:
+
+`journey`, `quadrantChart`, `requirementDiagram`, `usecaseDiagram`,
+`usecase-beta`, `gitGraph`, `C4Context`, `C4Container`, `C4Component`,
+`C4Dynamic`, `C4Deployment`, `zenuml`, `sankey-beta`, `block-beta`,
+`packet-beta`, `kanban`, `architecture-beta`, `radar-beta`, `treemap-beta`,
+`venn-beta`, `ishikawa-beta`, `wardley-beta`, `treeView`, `treeView-beta`,
+`cynefin-beta`, `swimlane-beta`, `eventModeling`, `agentflow-beta`,
+`railroad-ebnf-beta`, `railroad-abnf-beta`, `railroad-peg-beta`, and
+`railroad-beta`.
+
+Each declaration has a diagram-specific terminal layout. Relationship diagrams
+use the shared layered routing engine where that matches their semantics;
+journeys, quadrants, packets, Kanban boards, radar charts, treemaps, Venn
+diagrams, Ishikawa causes, Wardley maps, swimlanes, and event models use their
+own terminal geometry. Ishikawa cause indentation and Treemap hierarchy are
+retained in the terminal layout.
+Railroad declarations render grammar rules with distinct terminal
+and non-terminal nodes. Mermaid directives that only affect browser layout or
+SVG styling are ignored.
+
+Kanban task metadata written as `@{ ... }` is shown with the task label. Wardley
+maps support `component`, `anchor`, their `inertia` and source-strategy
+decorators, links (including labels and reverse/dashed forms), `evolve`,
+`pipeline`, `evolution`, trends,
+positioned `note`, and numbered `annotation` statements. Event Modeling supports compact and relaxed time frames, reset
+frames (reset frames retain an `rf` marker), `->>` relations, and named `data` blocks; UI/processor,
+command/read model, and event aliases share their corresponding swimlanes.
+
+Railroad rules end with `;`: EBNF uses `=` or `::=`, ABNF uses `=`, and PEG
+uses `<-`. Quoted strings are terminal nodes, identifiers are non-terminal
+nodes, and top-level `|` or `/` alternatives become separate paths. The IR
+form (`railroad-beta`) accepts `terminal("text")`, `nonterminal("name")`,
+`special("text")`, `sequence(...)`, `choice(...)`, `optional(...)`,
+`zeroOrMore(...)`, and `oneOrMore(...)`. EBNF/PEG comments and ABNF trailing
+comments are ignored.
+
+An `agentflow-beta` flow with no nodes is rendered as a labeled terminal card;
+it does not fall back to the generic additional-syntax renderer.
+
+```mermaid
+railroad-ebnf-beta
+title "Letter"
+letter = "a" | "b" ;
+```
+
+```mermaid
+usecase-beta
+actor User
+User --> (Use system)
+```
+
+The core diagram types have dedicated syntax references in the neighboring
+files. This page keeps the additional declaration names and terminal subset in
+one place. Browser-only styling and interaction directives are intentionally
+ignored because they have no terminal equivalent.

data/docs/syntax/class.md

@@ -0,0 +1,3 @@
+# Class syntax
+
+`classDiagram` accepts `class Name`, bodies in `{ ... }`, attributes, operations, `Name : member`, and annotations such as `class Name <<interface>>` or `Name <<interface>>`. Classes have name, attribute, and operation compartments. Relations include inheritance `<|--`, realization `..|>`, composition `*--`, aggregation `o--`, dependency `..>`, association `-->`, plain `--`, and reverse forms. A label can follow `:`.

data/docs/syntax/er.md

@@ -0,0 +1,3 @@
+# ER syntax
+
+`erDiagram` accepts `ENTITY { ... }` attribute blocks and relation lines such as `CUSTOMER ||--o{ ORDER : places`. Solid and dotted relationships are rendered; cardinalities are written as `1`, `0..1`, `1..*`, and `0..*` in the relation label.

data/docs/syntax/flowchart.md

@@ -0,0 +1,16 @@
+# Flowchart syntax
+
+Headers: `graph`, `flowchart`, `flowchart-v2`, or `flowchart-elk`, followed by
+`TB`, `TD`, `BT`, `LR`, or `RL`.
+
+Nodes: `A`, `A[text]`, `A(text)`, `A([text])`, `A[[text]]`, `A((text))`, `A(((text)))`, `A{text}`, `A{{text}}`, `A[(text)]`, `A>text]`, `A[/text/]`, `A[/text\]`, and `A@{ shape: diamond }`. `<br>` and HTML entities in labels are accepted.
+
+Edges: `-->`, `---`, `-.->`, `==>`, `~~~`, longer variants, edge labels `-->|text|`, chains, and `&` groups. `subgraph ...` / `end` creates a frame. `direction` changes the top level orientation.
+
+```mermaid
+flowchart LR
+  A[Start] -->|yes| B{Ready?}
+  B --> C[Done]
+```
+
+`style`, `classDef`, `class`, `linkStyle`, and `:::` accept `fill`, `stroke`, and `color` hex values for ANSI output. `click` produces an information diagnostic and is ignored. Unknown statements produce errors, and valid statements continue rendering.

data/docs/syntax/gantt.md

@@ -0,0 +1,3 @@
+# Gantt syntax
+
+`gantt` accepts `title`, `dateFormat`, `section`, `excludes weekends`, and tasks like `Design :done, d1, 2026-01-01, 3d` or `Build :active, b1, after d1, 5d`. `done`, `active`, `crit`, and `milestone` states are accepted. Durations use days (`d`) or weeks (`w`).

data/docs/syntax/mindmap.md

@@ -0,0 +1,3 @@
+# Mindmap syntax
+
+`mindmap` accepts indented nodes. The first node is the root; indentation determines parentage. `id((label))`, `id(label)`, `id[label]`, and `id))label((` select circle, rounded, rectangle, and cloud frames. Other labels use a rectangle.

data/docs/syntax/pie.md

@@ -0,0 +1,3 @@
+# Pie syntax
+
+`pie` accepts `showData`, `title`, and quoted `"Label" : nonnegative-number` entries. Values are shown as horizontal proportional bars and percentages. `showData` adds the original values.

data/docs/syntax/sequence.md

@@ -0,0 +1,14 @@
+# Sequence syntax
+
+`sequenceDiagram` accepts `participant` and `actor` declarations, optional `as` labels, message operators `->`, `-->`, `->>`, `-->>`, `-x`, `--x`, `-)`, and `--)`, self messages, `Note left of` / `right of` / `over`, `activate`, `deactivate`, and `autonumber`. `+` or `-` before the recipient activates or deactivates a participant. `loop`, `alt` / `else`, `opt`, `par` / `and`, `critical`, `break`, and `rect` create frames.
+
+```mermaid
+sequenceDiagram
+  participant A as Alice
+  participant B as Bob
+  A->>+B: Request
+  B-->>-A: Response
+```
+
+Unsupported statements produce errors. Participant declaration order determines columns; undeclared participants use first appearance order.
+Pass `repeat_participants: true` to `render` to show participant boxes again at the bottom.

data/docs/syntax/state.md

@@ -0,0 +1,3 @@
+# State syntax
+
+`stateDiagram` and `stateDiagram-v2` accept `A --> B`, transition labels after `:`, `[*]` start and end, `state "Label" as ID`, `state ID <<choice>>`, `<<fork>>`, `<<join>>`, and `state ID { ... }` composite frames. `direction` accepts flowchart directions. `note left of ID` and `note right of ID` accept inline text after `:` or a block ending in `end note`.

data/docs/syntax/timeline.md

@@ -0,0 +1,3 @@
+# Timeline syntax
+
+`timeline` accepts `title`, `section`, and `period : event` lines. Events retain source order and appear as a vertical list.

data/docs/syntax/xychart.md

@@ -0,0 +1,3 @@
+# XY chart syntax
+
+`xychart-beta` or `xychart` accepts `title`, `x-axis [labels]`, numeric `y-axis min --> max`, `bar [values]`, and `line [values]`. Bars use eighth block characters, lines use braille pixels, and ASCII mode uses `#` and `*`. Add `horizontal` to the header for horizontal bars.

data/exe/merminal

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/merminal"
+require_relative "../lib/merminal/cli"
+
+exit Merminal::CLI.run

data/lib/merminal/cli.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Merminal
+  # Command line interface for files, pipes and Markdown fences.
+  module CLI
+    module_function
+
+    def run(argv = ARGV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      options = { charset: :unicode, color: :auto, theme: nil, rounded: true, crossings: :plain,
+                  fit: :compact, check: false, strict: false, markdown: false, compact: false }
+      parser = OptionParser.new do |p|
+        p.banner = "Usage: merminal [options] [FILE ...]"
+        p.on("-a", "--ascii", "Use printable ASCII") { options[:charset] = :ascii }
+        p.on("-t", "--theme NAME", "Color theme") { |name| options[:theme] = name.to_sym }
+        p.on("--list-themes", "List themes") { options[:list_themes] = true }
+        p.on("--color WHEN", %w[auto always never], "auto, always or never") { |value| options[:color] = value.to_sym }
+        p.on("-w", "--width N", Integer, "Target terminal width") { |value| options[:width] = value }
+        p.on("--no-fit", "Disable width fitting") { options[:fit] = nil }
+        p.on("--fit MODE", %w[compact rotate], "compact or rotate") { |value| options[:fit] = value.to_sym }
+        p.on("--compact", "Use compact spacing") { options[:compact] = true }
+        p.on("--sharp", "Use sharp corners") { options[:rounded] = false }
+        p.on("--crossings MODE", %w[plain bridge], "Crossing style") { |value| options[:crossings] = value.to_sym }
+        p.on("--markdown", "Read Mermaid fences") { options[:markdown] = true }
+        p.on("--check", "Check syntax without rendering") { options[:check] = true }
+        p.on("--strict", "Fail on parser errors") { options[:strict] = true }
+        p.on("-o", "--output FILE", "Write output to file") { |path| options[:output] = path }
+        p.on("-v", "--version", "Print version") { stdout.puts VERSION; return 0 }
+        p.on("-h", "--help", "Print help") { stdout.puts p; return 0 }
+      end
+      files = parser.parse(argv)
+      if options[:list_themes]
+        stdout.puts Output::THEMES.keys
+        return 0
+      end
+      raise OptionParser::InvalidArgument, "width must be positive" if options[:width] && !options[:width].positive?
+      raise OptionParser::InvalidArgument, "unknown theme" if options[:theme] && !Output::THEMES.key?(options[:theme])
+
+      parts = []
+      error_found = false
+      (files.empty? ? ["-"] : files).each do |path|
+        input = path == "-" ? stdin.read : File.read(path)
+        markdown = options[:markdown] || path.match?(/\.(?:md|markdown)\z/i)
+        blocks = markdown ? Merminal.markdown_blocks(input) : [MarkdownBlock.new(source: input, line: 1)]
+        blocks.each do |block|
+          document = Merminal.parse(block.source)
+          document.diagnostics.each do |diagnostic|
+            error_found ||= diagnostic.severity == :error
+            shifted = diagnostic.with(line: diagnostic.line + block.line - 1)
+            stderr.puts shifted.format(path, markdown ? input : block.source)
+          end
+          next if options[:check]
+
+          parts << fitted_render(document, options, stdout, stderr)
+        end
+      end
+      output = parts.join("\n\n")
+      options[:output] ? File.write(options[:output], output + (output.empty? ? "" : "\n")) : stdout.puts(output) unless options[:check]
+      error_found && (options[:strict] || options[:check]) ? 1 : 0
+    rescue UnsupportedDiagramError => e
+      stderr.puts e.message
+      3
+    rescue OptionParser::ParseError, Errno::ENOENT, Errno::EACCES, IOError, ArgumentError => e
+      stderr.puts e.message
+      2
+    end
+
+    def fitted_render(document, options, stdout, stderr)
+      width = options[:width] || (stdout.tty? ? terminal_width : nil)
+      rendered = document.render(width: width, fit: options[:fit], compact: options[:compact],
+                                 charset: options[:charset], color: options[:color], theme: options[:theme],
+                                 rounded: options[:rounded], crossings: options[:crossings])
+      if width && rendered.lines.any? { |line| Merminal::Text.width(line.gsub(/\e\[[\d;]*m/, "")) > width }
+        actual = rendered.lines.map { |line| Merminal::Text.width(line.gsub(/\e\[[\d;]*m/, "")) }.max
+        stderr.puts "diagram width #{actual} exceeds target #{width}"
+      end
+      rendered
+    end
+
+    def terminal_width
+      return ENV["COLUMNS"].to_i if ENV["COLUMNS"].to_i.positive?
+
+      begin
+        require "io/console"
+        width = IO.console&.winsize&.last
+        return width if width && width.positive?
+      rescue LoadError, Errno::ENOTTY, IOError
+        nil
+      end
+      80
+    end
+  end
+end