etassia 0.1.0

data/lib/etassia/parser/builders/xy_chart.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for XY Chart diagrams
+      class XyChart < Parslet::Transform
+        # Transform title (from grammar: {:title=>{:string=>"..."}} )
+        rule(title: { string: simple(:title) }) do
+          { type: :title, title: title.to_s }
+        end
+
+        # Transform values - keep as-is for now, will determine numeric vs
+        # categorical later
+        rule(value: simple(:v)) do
+          # Try to convert to number if it looks numeric, otherwise keep as
+          # string
+          str = v.to_s
+          if str.match?(/^\d+(\.\d+)?$/)
+            str.to_f
+          else
+            str
+          end
+        end
+
+        # Transform X-axis with label
+        rule(x_label: { string: simple(:label) }, x_values: subtree(:values)) do
+          {
+            type: :x_axis,
+            label: label.to_s,
+            values: Array(values),
+          }
+        end
+
+        rule(x_values: subtree(:values)) do
+          {
+            type: :x_axis,
+            label: nil,
+            values: Array(values),
+          }
+        end
+
+        # Transform Y-axis with label
+        rule(
+          y_label: { string: simple(:label) },
+          y_min: simple(:min),
+          y_max: simple(:max),
+        ) do
+          {
+            type: :y_axis,
+            label: label.to_s,
+            min: min.to_s.to_f,
+            max: max.to_s.to_f,
+          }
+        end
+
+        rule(y_min: simple(:min), y_max: simple(:max)) do
+          {
+            type: :y_axis,
+            label: nil,
+            min: min.to_s.to_f,
+            max: max.to_s.to_f,
+          }
+        end
+
+        # Transform line dataset
+        rule(line_values: subtree(:values)) do
+          {
+            type: :dataset,
+            chart_type: :line,
+            label: "Line",
+            values: Array(values),
+          }
+        end
+
+        # Transform bar dataset
+        rule(bar_values: subtree(:values)) do
+          {
+            type: :dataset,
+            chart_type: :bar,
+            label: "Bar",
+            values: Array(values),
+          }
+        end
+
+        # Transform named dataset
+        rule(
+          dataset_label: { string: simple(:label) },
+          dataset_values: subtree(:values),
+        ) do
+          {
+            type: :dataset,
+            chart_type: :line,
+            label: label.to_s,
+            values: Array(values),
+          }
+        end
+
+        # Transform the entire diagram
+        rule(statements: subtree(:statements)) do
+          XyChart.build(statements)
+        end
+
+        def self.build(statements)
+          result = {
+            title: nil,
+            x_axis: nil,
+            y_axis: nil,
+            datasets: [],
+          }
+          Array(statements).grep(Hash).each do |statement|
+            apply_statement(result, statement)
+          end
+          result
+        end
+
+        def self.apply_statement(result, statement)
+          case statement[:type]
+          when :title
+            result[:title] = statement[:title]
+          when :x_axis
+            result[:x_axis] = axis_values(statement, :values)
+          when :y_axis
+            result[:y_axis] = axis_values(statement, :min, :max)
+          when :dataset
+            result[:datasets] << dataset(statement)
+          end
+        end
+
+        def self.axis_values(statement, *keys)
+          keys.each_with_object(label: statement[:label]) do |key, values|
+            values[key] = statement[key]
+          end
+        end
+
+        def self.dataset(statement)
+          {
+            chart_type: statement[:chart_type],
+            label: statement[:label],
+            values: statement[:values],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/c4.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/c4"
+require_relative "builders/c4"
+require_relative "native/builders/c4"
+require_relative "../diagram/c4"
+
+module Etassia
+  module Parser
+    # C4 parser for Mermaid C4 diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle C4 diagram syntax including
+    # elements, relationships, and boundaries.
+    #
+    # Parses C4 diagrams with support for:
+    # - Multiple C4 levels (Context, Container, Component, Dynamic, Deployment)
+    # - Person, System, Container, Component elements
+    # - External variants (_Ext suffix)
+    # - Database and Queue variants (SystemDb, ContainerQueue, etc.)
+    # - Relationships (Rel, BiRel)
+    # - Boundaries (Enterprise_Boundary, System_Boundary, Boundary)
+    # - Nested boundaries
+    # - Element attributes (sprite, link, tags)
+    # - Layout configuration
+    #
+    # @example Parse a simple C4 Context diagram
+    #   parser = C4.new
+    #   source = "C4Context\ntitle My System\nPerson(user, \"User\")"
+    #   diagram = parser.parse(source)
+    class C4 < Base
+      grammar Grammars::C4
+      builder Builders::C4
+      native :c4, builder: Native::Builders::C4
+    end
+  end
+end

data/lib/etassia/parser/class_diagram.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/class_diagram"
+require_relative "builders/class_diagram"
+require_relative "class_notes"
+require_relative "class_namespaces"
+require_relative "native/builders/class_diagram"
+require_relative "../diagram/class_diagram"
+
+module Etassia
+  module Parser
+    # Class diagram parser for Mermaid class diagram syntax.
+    #
+    # Parses class diagrams with support for:
+    # - Class declarations with stereotypes
+    # - Attributes with visibility modifiers
+    # - Methods with parameters and return types
+    # - Relationships (inheritance, composition, aggregation, association)
+    # - Generic types (e.g., List~String~)
+    # - Namespaces
+    # - Cardinality labels
+    #
+    # @example Parse a simple class diagram
+    #   parser = ClassDiagram.new
+    #   diagram = parser.parse("classDiagram\nAnimal <|-- Dog")
+    class ClassDiagram < Base
+      native :class_diagram, builder: Native::Builders::ClassDiagram
+
+      # Parses class diagram source into a ClassDiagram model.
+      #
+      # @param source [String] the Mermaid class diagram source
+      # @return [Diagram::ClassDiagram] the parsed class diagram
+      # @raise [ParseError] if syntax is invalid
+      def parse(source)
+        native_diagram(source) || ruby_diagram(source)
+      end
+
+      private
+
+      def ruby_diagram(source)
+        tree = parse_with_grammar(Grammars::ClassDiagram.new, source)
+        diagram = Builders::ClassDiagram.new.apply(tree, source)
+        diagram.notes = ClassNotes.collect(tree, diagram)
+        diagram.namespaces = ClassNamespaces.collect(tree, diagram)
+        diagram
+      end
+
+      # The native builder also collects the notes and namespaces, and
+      # reads member text back from the source.
+      def native_diagram(source)
+        entry, builder = self.class.native
+        tree = Native.parse(entry, source)
+        tree && builder.new.apply(tree, source)
+      end
+    end
+  end
+end

data/lib/etassia/parser/class_namespaces.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../diagram/class_namespace"
+
+module Etassia
+  module Parser
+    # Collects the `namespace Name { ... }` blocks of a class diagram parse
+    # tree, with the ids of the classes the builder created inside each.
+    class ClassNamespaces
+      ID_KEYS = %i[class_id from_id to_id].freeze
+
+      # @param tree [Array<Hash>] the class diagram parse tree
+      # @param diagram [Diagram::ClassDiagram] the built diagram
+      # @return [Array<Diagram::ClassNamespace>] one per distinct name, in
+      #   source order
+      def self.collect(tree, diagram)
+        new(diagram).collect(tree)
+      end
+
+      def initialize(diagram)
+        @ids = diagram.entities.map(&:id)
+      end
+
+      def collect(tree)
+        blocks = Array(tree).select do |item|
+          item.is_a?(Hash) && item[:namespace_keyword]
+        end
+        grouped = blocks.group_by { |block| block[:namespace_name].to_s }
+        claim_last(grouped.map { |name, group| namespace(name, group) })
+      end
+
+      private
+
+      def namespace(name, blocks)
+        ids = blocks.flat_map { |block| member_ids(block) }
+        Diagram::ClassNamespace.new(name: name, class_ids: ids.uniq)
+      end
+
+      def member_ids(block)
+        Array(block[:namespace_body]).flat_map do |statement|
+          ID_KEYS.filter_map { |key| known(statement[key]) }
+        end
+      end
+
+      def known(slice)
+        return unless slice
+
+        id = slice.to_s.delete("`")
+        id if @ids.include?(id)
+      end
+
+      # mmdc gives a class one parent: the last namespace that lists it.
+      def claim_last(namespaces)
+        namespaces.reverse_each.with_object([]) do |item, claimed|
+          item.class_ids -= claimed
+          claimed.concat(item.class_ids)
+        end
+        namespaces
+      end
+    end
+  end
+end

data/lib/etassia/parser/class_notes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../diagram/class_note"
+
+module Etassia
+  module Parser
+    # Collects the `note` statements of a class diagram parse tree.
+    #
+    # The class builder drops them, so they are read from the tree beside it.
+    class ClassNotes
+      LINE_BREAK = %r{<br\s*/?>}i
+
+      # @param tree [Array<Hash>] the class diagram parse tree
+      # @param diagram [Diagram::ClassDiagram] the built diagram, for the
+      #   ids a `note for` can point at
+      # @return [Array<Diagram::ClassNote>] the notes in source order
+      def self.collect(tree, diagram)
+        new(diagram).collect(tree)
+      end
+
+      def initialize(diagram)
+        @ids = diagram.entities.map(&:id)
+      end
+
+      def collect(tree)
+        Array(tree).filter_map do |statement|
+          next unless statement.is_a?(Hash) && statement[:note_text]
+
+          Diagram::ClassNote.new(text: note_text(statement[:note_text]),
+                                 target_id: target(statement[:note_for]))
+        end
+      end
+
+      private
+
+      # mmdc renders the text as HTML: a <br> starts a new line and any
+      # other tag shows as its content. A literal backslash-n stays text.
+      def note_text(slice)
+        text = slice.to_s.strip.sub(/\A"(.*)"\z/m, '\1')
+        text.gsub(LINE_BREAK, "\n").gsub(/<[^>]*>/, "")
+      end
+
+      def target(slice)
+        return unless slice
+
+        name = slice.to_s.delete("`")
+        return name if @ids.include?(name)
+
+        matches = @ids.select { |id| id.end_with?(".#{name}") }
+        matches.first if matches.one?
+      end
+    end
+  end
+end

data/lib/etassia/parser/er_diagram.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../diagram/er_diagram"
+require_relative "grammars/er_diagram"
+require_relative "builders/er_diagram"
+require_relative "native/builders/er_diagram"
+
+module Etassia
+  module Parser
+    # ER diagram parser for Mermaid ER diagram syntax.
+    #
+    # Parses ER diagrams with support for:
+    # - Entity declarations with attributes
+    # - Attribute types and key markers (PK, FK, UK)
+    # - Relationships with cardinality notation
+    # - Identifying and non-identifying relationships
+    #
+    # @example Parse a simple ER diagram
+    #   parser = ErDiagram.new
+    #   diagram = parser.parse("erDiagram\nCUSTOMER ||--o{ ORDER : places")
+    class ErDiagram < Base
+      grammar Grammars::ErDiagram
+      builder Builders::ErDiagram
+      native :er_diagram, builder: Native::Builders::ErDiagram
+    end
+  end
+end

data/lib/etassia/parser/error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/error"
+require_relative "builders/error"
+require_relative "../diagram/error"
+
+module Etassia
+  module Parser
+    # Error diagram parser for Mermaid error diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle simple error diagrams.
+    #
+    # Parses error diagrams with support for:
+    # - Basic error keyword
+    # - Optional error message text
+    #
+    # @example Parse a simple error diagram
+    #   parser = Error.new
+    #   diagram = parser.parse("error")
+    #
+    # @example Parse error diagram with message
+    #   parser = Error.new
+    #   diagram = parser.parse("Error Diagrams")
+    class Error < Base
+      grammar Grammars::Error
+      builder Builders::Error
+    end
+  end
+end

data/lib/etassia/parser/flowchart.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/flowchart"
+require_relative "builders/flowchart"
+require_relative "native/builders/flowchart"
+require_relative "../diagram/flowchart"
+
+module Etassia
+  module Parser
+    # Flowchart parser for Mermaid flowchart syntax.
+    #
+    # Parses flowchart diagrams with support for:
+    # - Multiple node shapes (rectangle, rounded, rhombus, circle, etc.)
+    # - Multiple edge types (arrow, line, dotted, etc.)
+    # - Node labels with special characters
+    # - Edge chaining (A --> B --> C)
+    # - Subgraphs
+    # - Styling directives
+    # - Direction specification (TD, LR, etc.)
+    #
+    # @example Parse a simple flowchart
+    #   parser = Flowchart.new
+    #   diagram = parser.parse("graph TD\nA[Start]-->B[End]")
+    class Flowchart < Base
+      native :flowchart, builder: Native::Builders::Flowchart
+
+      # Parses flowchart source into a Flowchart diagram model.
+      #
+      # @param source [String] the Mermaid flowchart source
+      # @return [Diagram::Flowchart] the parsed flowchart
+      # @raise [ParseError] if syntax is invalid
+      def parse(source)
+        # A lone CR is folded before the grammar sees it; the shared
+        # helper owns the parse and the failure message.
+        source = normalize_line_ends(source)
+        native_diagram(source) ||
+          Builders::Flowchart.new.apply(parse_tree(source))
+      end
+
+      private
+
+      # The native engine recurses per nested box as well and can run
+      # out of stack before the Parslet grammar does. The Ruby path then
+      # answers, with its own "nests too deeply" error.
+      def native_diagram(source)
+        super
+      rescue SystemStackError
+        nil
+      end
+
+      # A deeply nested diagram runs the grammar past the stack. mmdc
+      # renders 220 nested subgraphs and we refuse them, which is a gap —
+      # but letting a StackError out of a parse is not a gap, it is a
+      # crash in whatever called us.
+      #
+      # Only the grammar is wrapped. Both halves recurse, but the grammar
+      # spends far more stack per nested box, so on a source anyone can
+      # write it is the one that gives out first — measured here just
+      # under 190 nested boxes, a tree the transform then walks without
+      # trouble. A runaway recursion in the transform therefore stays
+      # visible instead of being reported as a diagram that nests too
+      # deeply. The depth moves with the stack the process was given, and
+      # a tree built by hand rather than parsed can still outrun the
+      # transform; neither changes which one a real source reaches first.
+      #
+      # @param source [String] the source with line ends already folded
+      # @return [Hash, Array] the parse tree
+      def parse_tree(source)
+        parse_with_grammar(Grammars::Flowchart.new, source)
+      rescue SystemStackError
+        raise ParseError, "Diagram nests too deeply to parse."
+      end
+
+      # mermaid folds a CRLF and a lone CR into a newline before it reads
+      # anything, so a bare `\r` ends a line, a comment and an accTitle's
+      # text. The grammar's `newline` knows `\n` and `\r\n` only, and a
+      # lone `\r` used to throw away a diagram mmdc draws.
+      #
+      # @param source [String] the Mermaid flowchart source
+      # @return [String] the source with every line end as `\n`
+      def normalize_line_ends(source)
+        source.gsub(/\r\n?/, "\n")
+      end
+    end
+  end
+end

data/lib/etassia/parser/gantt.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/gantt"
+require_relative "builders/gantt"
+require_relative "native/builders/gantt"
+require_relative "../diagram/gantt"
+
+module Etassia
+  module Parser
+    # Gantt chart parser for Mermaid gantt diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle Gantt chart syntax
+    # with sections, tasks, dependencies, and timeline configuration.
+    #
+    # Parses Gantt charts with support for:
+    # - Title and date format declarations
+    # - Axis formatting and tick intervals
+    # - Excludes (weekends, weekdays, specific dates)
+    # - Section grouping
+    # - Tasks with dates, durations, and dependencies
+    # - Task status tags (done, active, crit, milestone)
+    # - Click handlers for interactivity
+    # - Accessibility features (accTitle, accDescr)
+    # - Comments
+    #
+    # @example Parse a simple Gantt chart
+    #   parser = Gantt.new
+    #   diagram = parser.parse(<<~GANTT)
+    #     gantt
+    #       title Project Timeline
+    #       dateFormat YYYY-MM-DD
+    #       section Planning
+    #       Task 1 :a1, 2024-01-01, 30d
+    #       Task 2 :after a1, 20d
+    #   GANTT
+    class Gantt < Base
+      grammar Grammars::Gantt
+      builder Builders::Gantt
+      native :gantt, builder: Native::Builders::Gantt
+    end
+  end
+end

data/lib/etassia/parser/git_graph.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/git_graph"
+require_relative "builders/git_graph"
+require_relative "native/builders/gitgraph"
+require_relative "../diagram/git_graph"
+
+module Etassia
+  module Parser
+    # Git Graph parser for Mermaid gitGraph diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle git graph syntax
+    # with commits, branches, merges, and cherry-picks.
+    #
+    # Parses git graphs with support for:
+    # - Commit declarations with id, type, and tag
+    # - Branch creation with optional order
+    # - Checkout/switch operations
+    # - Merge operations
+    # - Cherry-pick operations
+    # - Commit types (NORMAL, REVERSE, HIGHLIGHT)
+    #
+    # @example Parse a simple git graph
+    #   parser = GitGraph.new
+    #   source = <<~MERMAID
+    #     gitGraph
+    #       commit id: "Initial"
+    #       branch develop
+    #       checkout develop
+    #       commit id: "Feature"
+    #       checkout main
+    #       merge develop
+    #   MERMAID
+    #   diagram = parser.parse(source)
+    class GitGraph < Base
+      native :gitgraph, builder: Native::Builders::GitGraph
+
+      COMMIT_ATTRIBUTES = %i[
+        id message type tag tags branch_name parent_ids is_merge merge_branch
+        is_cherry_pick cherry_pick_parent
+      ].freeze
+      BRANCH_ATTRIBUTES = %i[
+        name order parent_branch created_at_commit
+      ].freeze
+
+      # Parses git graph diagram source into a GitGraph model.
+      #
+      # @param source [String] the Mermaid git graph diagram source
+      # @return [Diagram::GitGraph] the parsed git graph diagram
+      # @raise [ParseError] if syntax is invalid
+      def parse(source, main_branch_name: "main")
+        result, orientation =
+          native_result(source, main_branch_name) ||
+          ruby_result(source, main_branch_name)
+        create_diagram(result, orientation)
+      end
+
+      private
+
+      # The native path's graph data and orientation, or nil when it
+      # declines.
+      def native_result(source, main_branch_name)
+        entry, builder = self.class.native
+        tree = Native.parse(entry, source)
+        tree && builder.new.apply(tree, main_branch_name: main_branch_name)
+      end
+
+      def ruby_result(source, main_branch_name)
+        tree = parse_with_grammar(Grammars::GitGraph.new, source)
+        result = Builders::GitGraph.build(
+          tree[:statements], main_branch_name: main_branch_name
+        )
+        [result, tree.fetch(:direction, "LR").to_s]
+      end
+
+      def create_diagram(result, orientation)
+        diagram = Diagram::GitGraph.new(
+          orientation: orientation,
+          main_branch_name: result[:main_branch_name],
+          acc_title: result[:acc_title],
+          acc_description: result[:acc_description],
+        )
+        append_commits(diagram, result[:commits])
+        append_branches(diagram, result[:branches])
+        diagram
+      end
+
+      def append_commits(diagram, commits)
+        commits.each { |data| diagram.commits << build_commit(data) }
+      end
+
+      def build_commit(data)
+        Diagram::GitGraph::Commit.new(**data.slice(*COMMIT_ATTRIBUTES))
+      end
+
+      def append_branches(diagram, branches)
+        branches.each { |data| diagram.branches << build_branch(data) }
+      end
+
+      def build_branch(data)
+        Diagram::GitGraph::Branch.new(**data.slice(*BRANCH_ATTRIBUTES))
+      end
+    end
+  end
+end