etassia 0.1.0

data/lib/etassia/parser/grammars/state_diagram.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+require_relative "common"
+
+module Etassia
+  module Parser
+    module Grammars
+      # Parslet grammar for State diagrams.
+      #
+      # Handles State diagram syntax including states, transitions,
+      # composite states, special state markers (choice, fork, join),
+      # and concurrent states.
+      class StateDiagram < Common
+        root(:diagram)
+
+        # Main diagram structure
+        rule(:diagram) do
+          ws? >>
+            header >>
+            header_line_direction.absent? >>
+            ws? >>
+            statements.maybe >>
+            ws?
+        end
+
+        # A direction is only a direction BELOW the header. Measured against
+        # mmdc 11.12.0: `stateDiagram-v2 direction LR` exits 1 and writes no
+        # output, while `stateDiagram-v2 A --> B` and a `direction LR` on its
+        # own line both render. So the header's line bars the direction
+        # statement and nothing else -- other statements stay legal there.
+        rule(:header_line_direction) do
+          space.repeat >> direction_statement
+        end
+
+        # Nothing on the keyword's line is a direction: mmdc 11.12.0 draws
+        # `stateDiagram-v2 LR` as a state called LR, not as a left-to-right
+        # diagram. Direction is a statement of its own.
+        rule(:header) do
+          (str("stateDiagram-v2") | str("stateDiagram")).as(:header)
+        end
+
+        rule(:statements) do
+          (statement >> ws?).repeat(1)
+        end
+
+        rule(:spaces) { space.repeat(1) }
+
+        # Keyword forms are listed first for readability, not for
+        # correctness: parslet backtracks out of a failed alternative, so
+        # `state Foo` still reaches `state_declaration` even when
+        # `standalone_state` is tried first — it takes `state` as an id and
+        # then fails on the rest of the line. Reordering this list was
+        # measured against the suite and changed nothing.
+        #
+        # What actually keeps `note`, `style`, and `state` from being read as
+        # state ids is `reserved_name.absent?`, in `standalone_state` and in
+        # `transition_end`. Remove that and the suite goes red.
+        rule(:statement) do
+          direction_statement |
+            style_statement |
+            empty_state_statement |
+            state_declaration |
+            note_block |
+            floating_note |
+            note_statement |
+            transition |
+            standalone_state
+        end
+
+        # Mermaid lexes a bare `state` as an empty statement. Capturing the
+        # keyword lets the transform drop it like any declaration without an
+        # id, while `reserved_name` keeps it out of state and transition ids.
+        rule(:empty_state_statement) do
+          str("state").as(:keyword) >> line_end
+        end
+
+        # State declaration with description, marker, or composite body
+        rule(:state_declaration) do
+          str("state").as(:keyword) >> spaces >>
+            (
+              marker_declaration |
+              (state_target >> space? >>
+                (
+                  state_description |
+                  composite_body.as(:composite)
+                ).maybe)
+            ) >>
+            line_end
+        end
+
+        # Marker declarations do not use the alias syntax. Mermaid takes
+        # everything before the marker as its literal id, including quotes and
+        # `as`: `state "X" as Y <<choice>>` identifies `"X" as Y`.
+        rule(:marker_declaration) do
+          marker_state_target.as(:state_id) >> space? >>
+            state_marker.as(:marker)
+        end
+
+        rule(:marker_state_target) do
+          (
+            (space? >> state_marker >> line_end).absent? >> line_char
+          ).repeat(1)
+        end
+
+        # `state "Idle mode" as Idle` names the state Idle and labels it
+        # "Idle mode". mmdc 11.12.0 refuses every other shape of this: the
+        # reverse order (`state Idle as "Idle mode"`), a single-quoted label
+        # and an empty one. It does accept a quoted id after `as`.
+        rule(:state_target) do
+          (
+            str('""').absent? >> state_label_string.as(:state_label) >>
+              spaces >> str("as") >> spaces >>
+              (quoted_state_id | state_name).as(:state_id)
+          ) |
+            state_id.as(:state_id)
+        end
+
+        # Alias labels do not recognize backslash-escaped quotes. Keep this
+        # local: other quoted state syntax has different escape behavior.
+        rule(:state_label_string) do
+          str('"') >> (str('"').absent? >> any).repeat.as(:string) >> str('"')
+        end
+
+        # Unlike ordinary quoted state names, an id declared after `as` keeps
+        # its delimiters as part of its identity in Mermaid's StateDB.
+        rule(:quoted_state_id) do
+          (
+            str('"') >>
+              ((str("\\") >> any) | (str('"').absent? >> any)).repeat >>
+              str('"')
+          ) |
+            (
+              str("'") >>
+                ((str("\\") >> any) | (str("'").absent? >> any)).repeat >>
+                str("'")
+            )
+        end
+
+        # Direction on a line of its own. mmdc 11.12.0 knows TB, BT, LR and
+        # RL here and nothing else: `direction TD` draws two states called
+        # `direction` and `TD`, which this grammar has no shape for.
+        rule(:direction_statement) do
+          str("direction") >> spaces >> direction.as(:direction) >> line_end
+        end
+
+        rule(:direction) do
+          (str("TB") | str("BT") | str("LR") | str("RL")).as(:dir_value)
+        end
+
+        # Styling directive, parsed and dropped the way the flowchart
+        # grammar treats `style`. mmdc 11.12.0 takes a bare `style A` with
+        # no properties at all, so the property list is optional.
+        rule(:style_statement) do
+          str("style").as(:style_keyword) >> spaces >>
+            style_targets.as(:style_targets) >>
+            (spaces >> style_properties.as(:style_props)).maybe >>
+            line_end
+        end
+
+        # Unquoted, and keywords are ordinary names here: mmdc 11.12.0
+        # renders `style note fill:red` and refuses `style "A" fill:red`.
+        rule(:style_targets) do
+          state_name >> (comma >> space? >> state_name).repeat
+        end
+
+        # The whole rest of the line, dropped by the transform. Unlike the
+        # flowchart's `style`, a `;` splits nothing here: mmdc 11.12.0 draws
+        # the same picture for `style A fill:red` and for
+        # `style A fill:red;stroke:blue`.
+        rule(:style_properties) do
+          line_char.repeat(1)
+        end
+
+        # Transition between states
+        rule(:transition) do
+          transition_end.as(:from) >> space? >>
+            arrow >>
+            space? >>
+            transition_end.as(:to) >>
+            transition_label.maybe.as(:label) >>
+            (
+              space? >> arrow >> space? >> transition_end.as(:chain_to)
+            ).repeat.as(:chain) >>
+            line_end
+        end
+
+        # Single-line note. The colon is not optional: once a note names a
+        # target and no colon follows, mmdc 11.12.0 is reading a note body
+        # and refuses the file if no `end note` closes it.
+        rule(:note_statement) do
+          note_head >> colon >> space? >> note_text.as(:note_text) >> line_end
+        end
+
+        # `note right of X` ... `end note` spans lines. The single-line form
+        # cannot swallow the opening line ahead of it, because the colon
+        # there is mandatory and a block opener carries none — so the two
+        # forms are disjoint and either order parses the same.
+        rule(:note_block) do
+          note_head >> newline >>
+            note_body.as(:note_text) >>
+            note_block_end
+        end
+
+        rule(:note_head) do
+          str("note").as(:note_keyword) >> spaces >>
+            note_position.as(:position) >> space >>
+            str("of") >> spaces >>
+            state_id.as(:note_target) >> space?
+        end
+
+        # Everything up to the line that closes the note. An empty body is
+        # legal: mmdc 11.12.0 renders `note right of A` / `end note`.
+        rule(:note_body) do
+          (
+            note_block_end.absent? >>
+              (newline.absent? >> any).repeat >> newline
+          ).repeat
+        end
+
+        # `end note` closes the note only when the line ends there. mmdc
+        # 11.12.0 keeps `say end notes here` as note text, and keeps a body
+        # line ending in `;` or holding a `%%` comment.
+        rule(:note_block_end) { space? >> str("end note") >> line_end }
+
+        # A floating note names itself instead of a target. mmdc 11.12.0
+        # parses it, draws nothing for it, and takes a non-empty
+        # double-quoted text only.
+        rule(:floating_note) do
+          str("note").as(:note_keyword) >> spaces >>
+            str('""').absent? >> quoted_string.as(:note_text) >> spaces >>
+            str("as") >> spaces >>
+            state_id.as(:note_id) >> line_end
+        end
+
+        # A state on a line of its own, with an optional `: description`.
+        # mmdc 11.12.0 refuses `note` and `style` in both shapes, the same
+        # way it refuses them at a transition end.
+        rule(:standalone_state) do
+          reserved_name.absent? >> state_id.as(:state_id) >>
+            (space? >> bare_state_description).maybe >>
+            line_end
+        end
+
+        # Either end of a transition. `[*]` is the start or end marker.
+        rule(:transition_end) do
+          start_end_marker | (reserved_name.absent? >> state_id)
+        end
+
+        # Start/end marker [*]
+        rule(:start_end_marker) do
+          lbracket >> asterisk >> rbracket
+        end
+
+        # State ID (name or quoted string). Keywords are ordinary names
+        # here: mmdc 11.12.0 renders `state note` and `state "Label" as
+        # note`, and takes `note` as a note's target.
+        rule(:state_id) { string | state_name }
+
+        # The names mmdc 11.12.0 lexes as keywords wherever a statement or a
+        # transition end may start. Measured against the real binary, one
+        # source per word: `A --> class`, `A --> classDef`, `A --> click`,
+        # `A --> href`, `A --> scale`, `A --> default`, `A --> note`,
+        # `A --> state` and `A --> style` each exit 1 with no output.
+        # `direction`, `end`, `as`, `notes` and `styles` all render, and the
+        # trailing guard is what keeps them out: `classroom` is a legal id
+        # because a word character follows the keyword.
+        #
+        # A bare `state` stays an empty statement; only its use as an ID is
+        # refused here.
+        RESERVED_WORDS = %w[
+          class classDef click href scale default note state style
+        ].freeze
+
+        # Longest first, and that ordering is load-bearing. Parslet alternation
+        # is ordered choice, so with `class` ahead of `classDef` the shorter
+        # word matches, the trailing guard then fails on the `D`, and the whole
+        # rule gives up — leaving `A --> classDef` accepted. Measured: sorting
+        # by length is what turns that from RENDERS into a refusal.
+        rule(:reserved_name) do
+          RESERVED_WORDS.sort_by { |word| -word.length }
+            .map { |word| word_ci(word) }
+            .reduce(:|) >>
+            match["a-zA-Z0-9_"].absent?
+        end
+
+        # Case matters and this bundle of parslet has no `stri`. The house
+        # pattern in pie.rb (`match['Pp'] >> str('ie')`) varies only the first
+        # letter, which is not enough: mmdc refuses `CLASS`, `Class` and
+        # `clAsS` alike, so every letter has to vary.
+        def word_ci(word)
+          word.each_char
+            .map { |ch| match["#{ch.downcase}#{ch.upcase}"] }
+            .reduce(:>>)
+        end
+
+        # A bare state name. A superset of `identifier`, which is
+        # `[a-zA-Z_][a-zA-Z0-9_]*` and so refuses a leading digit: mmdc
+        # 11.12.0 draws `55` as a state called 55.
+        rule(:state_name) do
+          match["a-zA-Z0-9_"].repeat(1)
+        end
+
+        # State description on a `state` statement. The brace is out: it
+        # opens the composite body instead.
+        rule(:state_description) do
+          colon >> space? >>
+            (lbrace.absent? >> line_char).repeat(1).as(:description)
+        end
+
+        # The bare `id : text` form has no composite body to open, and mmdc
+        # 11.12.0 draws a state labelled `text {` for `A : text {` while
+        # refusing `state A : text {`. It also requires at least one physical
+        # character after the colon, although that character may be padding.
+        rule(:bare_state_description) do
+          colon >> (newline | eof).absent? >> space? >>
+            (bare_description_end.absent? >> any)
+              .repeat(1).as(:description).maybe
+        end
+
+        # A bare description treats comments and semicolons as text, ending
+        # only at the physical line boundary. Horizontal padding stays outside
+        # the captured description.
+        rule(:bare_description_end) { space? >> (newline | eof) }
+
+        # One character that is not the end of the line.
+        rule(:line_char) { line_end.absent? >> any }
+
+        # State marker: <<choice>>, <<fork>>, <<join>>
+        rule(:state_marker) do
+          str("<<") >>
+            (str("choice") | str("fork") | str("join")).as(:marker_type) >>
+            str(">>")
+        end
+
+        # Composite state body with nested statements
+        rule(:composite_body) do
+          lbrace >> ws? >>
+            composite_statements.maybe >>
+            ws? >> rbrace
+        end
+
+        # Statements within composite state
+        rule(:composite_statements) do
+          (composite_statement >> ws?).repeat(1)
+        end
+
+        rule(:composite_statement) do
+          concurrent_separator | statement
+        end
+
+        # Concurrent state separator
+        rule(:concurrent_separator) do
+          str("--").as(:concurrent_sep) >> line_end
+        end
+
+        # Arrow for transitions
+        rule(:arrow) do
+          str("-->").as(:arrow)
+        end
+
+        # Transition label (after colon)
+        rule(:transition_label) do
+          space? >> colon >> space? >>
+            (arrow.absent? >> line_char).repeat(1).as(:label_text)
+        end
+
+        # Note position
+        rule(:note_position) do
+          str("left") | str("right")
+        end
+
+        # Note text
+        rule(:note_text) { line_char.repeat(1) }
+
+        # Line terminators for State diagrams
+        rule(:line_end) do
+          semicolon.maybe >> space? >> ((comment.maybe >> newline) | eof)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/grammars/timeline.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "common"
+
+module Etassia
+  module Parser
+    module Grammars
+      # Parslet grammar for timeline diagrams.
+      #
+      # Handles timeline syntax including title, sections, events with
+      # timestamps and descriptions, and accessibility features.
+      #
+      # @example Simple timeline
+      #   timeline
+      #     title History of Social Media
+      #     2002 : LinkedIn
+      #     2004 : Facebook : Google
+      #     2005 : YouTube
+      #
+      # @example Timeline with sections
+      #   timeline
+      #     section 20th Century
+      #       1903 : Wright Brothers flight
+      #     section 21st Century
+      #       2007 : iPhone released
+      class Timeline < Common
+        root(:diagram)
+
+        # mmdc's timeline lexer gives ";" no meaning, so it stays in text.
+        rule(:line_end) do
+          space? >> ((comment.maybe >> newline) | eof)
+        end
+
+        # Main diagram structure
+        rule(:diagram) do
+          ws? >>
+            header >>
+            ws? >>
+            statements.maybe >>
+            ws?
+        end
+
+        # Header: timeline
+        rule(:header) do
+          str("timeline").as(:header) >> ws?
+        end
+
+        # Statements (title, sections, events, tasks)
+        rule(:statements) do
+          (statement >> ws?).repeat(1)
+        end
+
+        rule(:statement) do
+          acc_title_declaration |
+            acc_descr_declaration |
+            title_declaration |
+            section_declaration |
+            event_entry |
+            task_entry |
+            (comment >> line_end)
+        end
+
+        # Title
+        rule(:title_declaration) do
+          str("title") >> space.repeat(1) >>
+            (line_end.absent? >> any).repeat(1).as(:title) >>
+            line_end
+        end
+
+        # Accessibility title
+        rule(:acc_title_declaration) do
+          str("accTitle") >> space? >> colon >> space? >>
+            (line_end.absent? >> any).repeat.as(:acc_title) >>
+            line_end
+        end
+
+        # Accessibility description (single or multi-line)
+        rule(:acc_descr_declaration) do
+          acc_descr_single_line | acc_descr_multi_line
+        end
+
+        rule(:acc_descr_single_line) do
+          str("accDescr") >> space? >> colon >> space? >>
+            (line_end.absent? >> any).repeat.as(:acc_descr) >>
+            line_end
+        end
+
+        rule(:acc_descr_multi_line) do
+          str("accDescr") >> space? >> lbrace >> ws? >>
+            (rbrace.absent? >> any).repeat.as(:acc_descr) >>
+            ws? >> rbrace >> line_end
+        end
+
+        # Section declaration
+        rule(:section_declaration) do
+          str("section") >> space.repeat(1) >>
+            (line_end.absent? >> any).repeat(1).as(:section) >>
+            line_end
+        end
+
+        # Event entry: time : description(s)
+        # Can have multiple descriptions separated by colons
+        # Example: 2004 : Facebook : Google
+        rule(:event_entry) do
+          (space? >> event_time.as(:time) >>
+            space? >> colon >>
+            event_descriptions.as(:descriptions) >>
+            line_end).as(:event_entry) |
+            (space? >> colon >>
+              event_descriptions.as(:descriptions) >>
+              line_end).as(:continuation_entry)
+        end
+
+        # Event time (year, date, task name, or any time identifier)
+        # Can include spaces, alphanumeric, and common punctuation
+        rule(:event_time) do
+          (colon.absent? >> line_end.absent? >> any).repeat(1)
+        end
+
+        # Event descriptions (one or more, separated by colons)
+        rule(:event_descriptions) do
+          event_description.as(:desc) >>
+            (space? >> colon >> space? >> event_description.as(:desc)).repeat
+        end
+
+        # Single event description (can include HTML tags like <br>).
+        # A colon only separates descriptions when whitespace follows it,
+        # so "http://example.com" stays whole as in mmdc.
+        rule(:event_description) do
+          space? >> description_char.repeat(1) >> space?
+        end
+
+        rule(:description_char) do
+          separator_colon.absent? >> line_end.absent? >> any
+        end
+
+        rule(:separator_colon) { colon >> match("\\s") }
+
+        # Task entry (plain text without colon, for sections)
+        rule(:task_entry) do
+          (colon.absent? >>
+            str("section").absent? >>
+            str("title").absent? >>
+            str("accTitle").absent? >>
+            str("accDescr").absent? >>
+            line_end.absent? >>
+            any).repeat(1).as(:task) >>
+            line_end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/grammars/treemap.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "../atoms/greedy_run"
+
+module Etassia
+  module Parser
+    module Grammars
+      # Parslet grammar for treemap diagrams
+      class Treemap < Parslet::Parser
+        rule(:space) { match[' \t'] }
+        rule(:space?) { space.maybe }
+        rule(:spaces) { space.repeat(1) }
+        rule(:spaces?) { space.repeat }
+        rule(:newline) { str("\n") | str("\r\n") }
+        rule(:newlines) { newline.repeat(1) }
+        rule(:newlines?) { newline.repeat }
+        rule(:eof) { any.absent? }
+
+        # Comments
+        # Same rule and reasoning as `Common#comment`.
+        rule(:comment) { str("%%") >> Atoms::GreedyRun.new('[^\n]', min: 0) }
+
+        # Numbers
+        rule(:number) do
+          (match["-"].maybe >> match["0-9"].repeat(1) >>
+           (str(".") >> match["0-9"].repeat(1)).maybe).as(:number)
+        end
+
+        # Quoted strings
+        rule(:quoted_string) do
+          str('"') >> (
+            (str("\\") >> any) |
+            (str('"').absent? >> any)
+          ).repeat.as(:string) >> str('"')
+        end
+
+        # Identifiers
+        rule(:identifier) do
+          (match["a-zA-Z_"] >> match["a-zA-Z0-9_-"].repeat).as(:identifier)
+        end
+
+        # Keywords
+        rule(:treemap_keyword) do
+          (str("treemap-beta") | str("treemap")).as(:keyword)
+        end
+
+        # Title declaration
+        rule(:title_decl) do
+          str("title") >> spaces >>
+            (newline.absent? >> any).repeat(1).as(:title)
+        end
+
+        # Accessibility declarations
+        rule(:acc_title) do
+          str("accTitle:") >> spaces? >>
+            (newline.absent? >> any).repeat(1).as(:acc_title)
+        end
+
+        rule(:acc_descr) do
+          str("accDescr") >> spaces? >> str(":").maybe >> spaces? >>
+            (newline.absent? >> any).repeat(1).as(:acc_descr)
+        end
+
+        # CSS class reference
+        rule(:css_class) do
+          str(":::") >> identifier.as(:css_class)
+        end
+
+        # Value separator (: or ,) with optional spaces before and after
+        rule(:value_separator) { spaces? >> (str(":") | str(",")) >> spaces? }
+
+        # Node with optional value and CSS class
+        rule(:node_value) do
+          quoted_string.as(:label) >>
+            (value_separator >> number.as(:value)).maybe >>
+            css_class.maybe
+        end
+
+        # Capture leading spaces as a string to count indentation
+        rule(:indent_str) do
+          match[" "].repeat.as(:indent)
+        end
+
+        # Node line (with indentation captured)
+        rule(:node_line) do
+          indent_str >> node_value >> spaces? >>
+            (comment.maybe >> (newline | eof))
+        end
+
+        # Class definition
+        rule(:class_def) do
+          str("classDef") >> spaces >>
+            identifier.as(:class_name) >> spaces >>
+            (str(";").absent? >> any).repeat(1).as(:class_styles) >>
+            str(";").maybe
+        end
+
+        # Statement (title, acc, node, or class def)
+        rule(:statement) do
+          (title_decl >> spaces?) |
+            (acc_title >> spaces?) |
+            (acc_descr >> spaces?) |
+            (class_def.as(:class_def) >> spaces?) |
+            node_line.as(:node) |
+            (comment >> spaces?) |
+            (spaces? >> newline)
+        end
+
+        # Main diagram
+        rule(:diagram) do
+          treemap_keyword >>
+            spaces? >> newline >>
+            statement.repeat.as(:statements) >>
+            spaces? >> eof
+        end
+
+        root(:diagram)
+      end
+    end
+  end
+end