etassia 0.1.0

data/lib/etassia/parser/native/text.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Parser
+    module Native
+      # Reads captures out of a native parse tree.
+      module Text
+        module_function
+
+        # An empty capture is an Array in the tree, like Parslet's.
+        #
+        # @return [String]
+        def of(capture)
+          capture.is_a?(Array) ? "" : capture.to_s
+        end
+
+        # @return [Boolean] whether the capture matched no characters
+        def empty?(capture)
+          of(capture).empty?
+        end
+
+        # The tree's statement list, whatever shape one statement gives.
+        #
+        # @return [Array<Hash>]
+        def items(tree)
+          [tree].flatten(1).grep(Hash)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/native.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Parser
+    # The native parse path: Mermaid grammars compiled from PARG
+    # (claricle/etassia-mermaid-parg) and run by the parsanol engine.
+    #
+    # It is strictly an accelerator. It answers only for input it accepts;
+    # on a missing engine, an unreadable encoding or any rejection it
+    # returns nil and the caller runs the Parslet grammar, which stays the
+    # source of every positioned ParseError.
+    module Native
+      ARTIFACT_PATH = File.expand_path("native/mermaid.json", __dir__)
+      ARTIFACT_VARIABLE = "ETASSIA_NATIVE_ARTIFACT"
+      DISABLE_VARIABLE = "ETASSIA_NATIVE_PARSER"
+      DISABLED_VALUES = %w[0 off false ruby].freeze
+      # The engine recurses on the machine stack once per nested block and
+      # a source that nests deeper than the stack allows kills the whole
+      # process (a segfault in the extension, not a SystemStackError): about
+      # 60 nested subgraphs on a 1 MB stack, Windows' main-thread size. Past
+      # this depth the Ruby grammar answers, as it does without the engine.
+      MAX_NESTING = 32
+      NESTING_OPEN = /\A\s*(?:subgraph|block:|alt|loop|opt|par|critical|break|
+                            rect|box)\b|\{\s*\z/ix
+      NESTING_CLOSE = /\A\s*(?:end\b|\})/i
+      private_constant :ARTIFACT_PATH, :ARTIFACT_VARIABLE, :DISABLE_VARIABLE,
+                       :DISABLED_VALUES, :MAX_NESTING, :NESTING_OPEN,
+                       :NESTING_CLOSE
+
+      class << self
+        # @return [Boolean] whether the parsanol engine and artifact loaded
+        def available?
+          !artifact.nil?
+        end
+
+        # Parses source with one entry of the Mermaid artifact.
+        #
+        # @param entry [Symbol] an entry of mermaid.parg
+        # @param source [String] Mermaid source
+        # @return [Hash, Array, Parsanol::Slice, nil] the parse tree, or
+        #   nil when the native path does not answer
+        def parse(entry, source)
+          return nil if disabled? || !readable?(source) || too_deep?(source)
+
+          artifact&.parse(entry.to_s, source)
+        rescue Parsanol::ParseFailed
+          nil
+        end
+
+        # Forgets the loaded artifact (specs swap the engine out).
+        def reset!
+          @artifact = nil
+          @loaded = false
+        end
+
+        private
+
+        def disabled?
+          DISABLED_VALUES.include?(ENV.fetch(DISABLE_VARIABLE, "").downcase)
+        end
+
+        def readable?(source)
+          source.encoding == Encoding::UTF_8 && source.valid_encoding?
+        end
+
+        # Whether blocks opened and not yet closed ever pass MAX_NESTING.
+        # A line that merely looks like an opener only sends the source to
+        # the Ruby grammar, which answers identically.
+        def too_deep?(source)
+          depth = 0
+          source.each_line do |line|
+            if line.match?(NESTING_OPEN)
+              depth += 1
+              return true if depth > MAX_NESTING
+            elsif line.match?(NESTING_CLOSE)
+              depth -= 1 if depth.positive?
+            end
+          end
+          false
+        end
+
+        def artifact
+          return @artifact if @loaded
+
+          @loaded = true
+          @artifact = load_artifact
+        end
+
+        def load_artifact
+          require "parsanol"
+          Parsanol::PARG::Artifact.load(ENV.fetch(ARTIFACT_VARIABLE,
+                                                  ARTIFACT_PATH))
+        rescue LoadError, StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/packet.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/packet"
+require_relative "builders/packet"
+require_relative "native/builders/packet"
+require_relative "../diagram/packet"
+
+module Etassia
+  module Parser
+    # Packet diagram parser for Mermaid packet-beta diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle packet diagram syntax
+    # with bit ranges and field labels.
+    #
+    # Parses packet diagrams with support for:
+    # - Title metadata
+    # - Field definitions with bit ranges
+    # - Field labels
+    #
+    # @example Parse a simple packet diagram
+    #   parser = Packet.new
+    #   source = <<~MERMAID
+    #     packet-beta
+    #       title Hello world
+    #       0-10: "hello"
+    #   MERMAID
+    #   diagram = parser.parse(source)
+    class Packet < Base
+      grammar Grammars::Packet
+      builder Builders::Packet
+      native :packet, builder: Native::Builders::Packet
+
+      private
+
+      def create_diagram(result)
+        diagram = Diagram::Packet.new
+        return diagram unless result.is_a?(Hash)
+
+        diagram.title = result[:title]
+        append_fields(diagram, result[:fields])
+        diagram
+      end
+
+      def append_fields(diagram, fields)
+        Array(fields).each { |data| diagram.add_field(build_field(data)) }
+      end
+
+      def build_field(data)
+        Diagram::PacketField.new(
+          data[:bit_start], data[:bit_end], data[:label]
+        )
+      end
+    end
+  end
+end

data/lib/etassia/parser/pie.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/pie"
+require_relative "builders/pie"
+require_relative "native/builders/pie"
+require_relative "../diagram/pie"
+
+module Etassia
+  module Parser
+    # Pie chart parser for Mermaid pie diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle pie chart syntax
+    # with labeled data entries and numeric values.
+    #
+    # Parses pie charts with support for:
+    # - Title declarations
+    # - showData flag for displaying values
+    # - Data entries with quoted labels and numeric values
+    # - Accessibility features (accTitle, accDescr)
+    # - Comments
+    #
+    # @example Parse a simple pie chart
+    #   parser = Pie.new
+    #   diagram = parser.parse("pie\n  \"Apples\" : 42\n  \"Oranges\" : 58")
+    class Pie < Base
+      grammar Grammars::Pie
+      builder Builders::Pie
+      native :pie, builder: Native::Builders::Pie
+    end
+  end
+end

data/lib/etassia/parser/quadrant.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/quadrant"
+require_relative "builders/quadrant"
+require_relative "native/builders/quadrant"
+require_relative "../diagram/quadrant"
+
+module Etassia
+  module Parser
+    # Quadrant chart parser for Mermaid quadrant diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle quadrant chart syntax
+    # with axis labels, quadrant labels, and data points.
+    #
+    # Parses quadrant charts with support for:
+    # - Title declarations
+    # - X-axis and Y-axis labels
+    # - Quadrant labels (1-4)
+    # - Data points with normalized coordinates
+    # - Point styling (radius, color, stroke)
+    # - Comments
+    #
+    # @example Parse a simple quadrant chart
+    #   parser = Quadrant.new
+    #   source = <<~MERMAID
+    #     quadrantChart
+    #       title Product Analysis
+    #       x-axis Low Cost --> High Cost
+    #       y-axis Low Value --> High Value
+    #       Product A: [0.3, 0.7]
+    #   MERMAID
+    #   diagram = parser.parse(source)
+    class Quadrant < Base
+      grammar Grammars::Quadrant
+      builder Builders::Quadrant
+      native :quadrant, builder: Native::Builders::Quadrant
+
+      CLASS_STYLE_KEYS = %w[radius color stroke-color stroke-width].freeze
+      private_constant :CLASS_STYLE_KEYS
+
+      # @raise [ParseError] when a classDef uses a style Mermaid rejects
+      def parse(source)
+        native_diagram(source) || ruby_quadrant(source)
+      end
+
+      # Mermaid rejects a classDef style outside CLASS_STYLE_KEYS; the
+      # native builder shares this check.
+      #
+      # @param tree [Array, Hash] statements carrying :class_style
+      # @raise [ParseError] for an unsupported style
+      def validate_class_styles(tree)
+        [tree].flatten.each do |item|
+          next unless item.is_a?(Hash) && item.key?(:class_style)
+
+          class_style_keys(item[:class_style]).each do |key|
+            next if CLASS_STYLE_KEYS.include?(key)
+
+            raise ParseError, "style named #{key} is not supported."
+          end
+        end
+      end
+
+      private
+
+      def ruby_quadrant(source)
+        tree = parse_with_grammar(Grammars::Quadrant.new, source)
+        validate_class_styles(tree)
+        Builders::Quadrant.new.apply(tree)
+      end
+
+      def class_style_keys(style)
+        style.to_s.split(",").map { |part| part.strip.split(/\s*:\s*/).first }
+      end
+    end
+  end
+end

data/lib/etassia/parser/radar.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/radar"
+require_relative "builders/radar"
+require_relative "native/builders/radar"
+require_relative "../diagram/radar"
+
+module Etassia
+  module Parser
+    # Radar chart parser for Mermaid radar-beta diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle radar chart syntax
+    # with axes and multiple data curves.
+    #
+    # Parses radar charts with support for:
+    # - Title and accessibility metadata
+    # - Axis definitions with labels
+    # - Multiple data curves/datasets
+    # - Configuration options (ticks, legend, graticule, min/max)
+    #
+    # @example Parse a simple radar chart
+    #   parser = Radar.new
+    #   source = <<~MERMAID
+    #     radar-beta
+    #       title Skills Assessment
+    #       axis A, B, C
+    #       curve mycurve{1, 2, 3}
+    #   MERMAID
+    #   diagram = parser.parse(source)
+    class Radar < Base
+      grammar Grammars::Radar
+      builder Builders::Radar
+      native :radar, builder: Native::Builders::Radar
+
+      # Assembles the diagram from the builder's intermediate result; the
+      # native builder shares it.
+      #
+      # @param result [Hash] title, axes, curves and options
+      # @return [Diagram::Radar]
+      def create_diagram(result)
+        diagram = Diagram::Radar.new
+        assign_metadata(diagram, result)
+        append_axes(diagram, result[:axes])
+        append_curves(diagram, result[:curves])
+        diagram
+      end
+
+      private
+
+      def assign_metadata(diagram, result)
+        diagram.title = result[:title]
+        diagram.acc_title = result[:acc_title]
+        diagram.acc_descr = result[:acc_descr]
+        diagram.options = result[:options]
+      end
+
+      def append_axes(diagram, axes)
+        axes.each do |data|
+          diagram.axes << Diagram::RadarAxis.new(data[:id], data[:label])
+        end
+      end
+
+      def append_curves(diagram, curves)
+        curves.each do |data|
+          diagram.curves << build_curve(data, diagram.axes)
+        end
+      end
+
+      def build_curve(data, axes)
+        curve = Diagram::RadarCurve.new(data[:id], data[:label])
+        assign_curve_values(curve, Array(data[:values]), axes)
+        curve
+      end
+
+      def assign_curve_values(curve, values, axes)
+        return assign_named_values(curve, values) if named_values?(values)
+
+        assign_positional_values(curve, values, axes)
+      end
+
+      def named_values?(values)
+        values.first.is_a?(Hash) && values.first[:axis]
+      end
+
+      def assign_named_values(curve, values)
+        values.each { |value| curve.add_value(value[:axis], value[:value]) }
+      end
+
+      def assign_positional_values(curve, values, axes)
+        values.each_with_index do |value, index|
+          next unless axes[index]
+
+          curve.add_value(axes[index].id, value)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/parser/requirement.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/requirement"
+require_relative "builders/requirement"
+require_relative "native/builders/requirement"
+require_relative "../diagram/requirement"
+
+module Etassia
+  module Parser
+    # Requirement diagram parser for Mermaid requirement diagram syntax.
+    #
+    # Parses requirement diagrams with support for:
+    # - Requirements with properties (id, text, risk, verifymethod)
+    # - Multiple requirement types (requirement, functionalRequirement, etc.)
+    # - Elements with properties (type, docref)
+    # - Relationships (contains, copies, derives, satisfies, verifies, refines,
+    #   traces)
+    # - Styling directives
+    # - Class definitions and assignments
+    #
+    # @example Parse a simple requirement diagram
+    #   parser = Requirement.new
+    #   source = "requirementDiagram\n  requirement test_req { id: 1 }"
+    #   diagram = parser.parse(source)
+    class Requirement < Base
+      grammar Grammars::Requirement
+      builder Builders::Requirement
+      native :requirement, builder: Native::Builders::Requirement
+    end
+  end
+end

data/lib/etassia/parser/sankey.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/sankey"
+require_relative "builders/sankey"
+require_relative "native/builders/sankey"
+require_relative "../diagram/sankey"
+
+module Etassia
+  module Parser
+    # Sankey parser for Mermaid sankey diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle Sankey diagram syntax
+    # with flows between nodes and optional node labels.
+    #
+    # Parses Sankey diagrams with support for:
+    # - Flow definitions (CSV format: source,target,value)
+    # - Optional node declarations with labels
+    # - Automatic node discovery from flows
+    # - Numeric flow values (integer or float)
+    # - Comments
+    #
+    # @example Parse a simple Sankey diagram
+    #   parser = Sankey.new
+    #   diagram = parser.parse(<<~SANKEY)
+    #     sankey-beta
+    #     A,B,10
+    #     B,C,20
+    #     A,D,5
+    #   SANKEY
+    #
+    # @example Parse Sankey with node labels
+    #   parser = Sankey.new
+    #   diagram = parser.parse(<<~SANKEY)
+    #     sankey-beta
+    #     Source [Energy Source]
+    #     Process [Processing Plant]
+    #     Source,Process,100
+    #     Process,Output,70
+    #   SANKEY
+    class Sankey < Base
+      grammar Grammars::Sankey
+      builder Builders::Sankey
+      native :sankey, builder: Native::Builders::Sankey
+    end
+  end
+end

data/lib/etassia/parser/sequence.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/sequence"
+require_relative "builders/sequence"
+require_relative "native/builders/sequence"
+require_relative "../diagram/sequence"
+
+module Etassia
+  module Parser
+    # Sequence parser for Mermaid sequence diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to correctly handle complex arrow
+    # patterns with activation modifiers (e.g., `->>+`, `-->>-`) that cannot
+    # be parsed accurately with regex-based lexers.
+    #
+    # Parses sequence diagrams with support for:
+    # - Participant declarations (participant, actor)
+    # - Multiple message types with activation modifiers
+    # - Activations and deactivations
+    # - Notes (left of, right of, over)
+    # - Control structures (loop, alt, opt, par, critical, break)
+    # - Box grouping
+    #
+    # @example Parse a simple sequence diagram
+    #   parser = Sequence.new
+    #   diagram = parser.parse("sequenceDiagram\nAlice->>Bob: Hello")
+    class Sequence < Base
+      grammar Grammars::Sequence
+      builder Builders::Sequence
+      native :sequence, builder: Native::Builders::Sequence
+    end
+  end
+end

data/lib/etassia/parser/state_diagram.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/state_diagram"
+require_relative "builders/state_diagram"
+require_relative "native/builders/state_diagram"
+require_relative "../diagram/state_diagram"
+
+module Etassia
+  module Parser
+    # State diagram parser for Mermaid state diagram syntax.
+    #
+    # Parses state diagrams with support for:
+    # - Normal states with labels
+    # - Special states (start [*], end [*], choice, fork, join)
+    # - Transitions with triggers and guard conditions
+    # - Composite/nested states
+    # - Direction statements (TB, BT, LR, RL)
+    #
+    # @example Parse a simple state diagram
+    #   parser = StateDiagram.new
+    #   diagram = parser.parse("stateDiagram-v2\n[*]-->Idle\nIdle-->Active")
+    class StateDiagram < Base
+      grammar Grammars::StateDiagram
+      builder Builders::StateDiagram
+      native :state_diagram, builder: Native::Builders::StateDiagram
+    end
+  end
+end

data/lib/etassia/parser/timeline.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/timeline"
+require_relative "builders/timeline"
+require_relative "native/builders/timeline"
+require_relative "../diagram/timeline"
+
+module Etassia
+  module Parser
+    # Timeline parser for Mermaid timeline diagram syntax.
+    #
+    # Uses Parslet grammar-based parsing to handle timeline syntax
+    # with sections, events, and chronological ordering.
+    #
+    # Parses timelines with support for:
+    # - Title declarations
+    # - Section grouping (periods, categories)
+    # - Events with timestamps and descriptions
+    # - Multiple descriptions per timestamp
+    # - Tasks within sections
+    # - Accessibility features (accTitle, accDescr)
+    # - Comments
+    #
+    # @example Parse a simple timeline
+    #   parser = Timeline.new
+    #   diagram = parser.parse(<<~TIMELINE)
+    #     timeline
+    #       title History of Social Media
+    #       2002 : LinkedIn
+    #       2004 : Facebook : Google
+    #       2005 : YouTube
+    #   TIMELINE
+    class Timeline < Base
+      grammar Grammars::Timeline
+      builder Builders::Timeline
+      native :timeline, builder: Native::Builders::Timeline
+    end
+  end
+end

data/lib/etassia/parser/treemap.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "grammars/treemap"
+require_relative "builders/treemap"
+require_relative "native/builders/treemap"
+require_relative "../diagram/treemap"
+
+module Etassia
+  module Parser
+    # Parser for treemap diagrams using Parslet
+    class Treemap < Base
+      grammar Grammars::Treemap
+      builder Builders::Treemap
+      native :treemap, builder: Native::Builders::Treemap
+
+      private
+
+      # The builder's Parslet pass returns statement data, not a diagram.
+      def create_diagram(data)
+        self.class.builder.new.build_diagram(data)
+      end
+    end
+  end
+end