etassia 0.1.0

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

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/state_diagram"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting Parslet parse tree to State diagram model.
+      #
+      # Converts the parse tree output from Grammars::StateDiagram into a
+      # fully-formed Diagram::StateDiagram object with states and transitions.
+      class StateDiagram
+        # Special state markers
+        START_END_MARKER = "[*]"
+
+        # Transform parse tree into State diagram.
+        #
+        # @param tree [Array, Hash] Parslet parse tree
+        # @return [Diagram::StateDiagram] the State diagram model
+        def apply(tree)
+          @diagram = Diagram::StateDiagram.new
+          @states = @diagram.states
+          @state_counter = 0
+          @concurrent_region_counter = 0
+          statements_in(tree).each { |item| process_item(item) }
+          @diagram
+        end
+
+        private
+
+        def statements_in(tree)
+          return tree.grep(Hash) if tree.is_a?(Array)
+
+          tree.is_a?(Hash) ? [tree] : []
+        end
+
+        def process_item(item)
+          return unless item.is_a?(Hash)
+
+          # Process a top-level direction statement
+          if item[:direction] && item[:direction][:dir_value]
+            @diagram.direction = extract_text(item[:direction][:dir_value])
+          end
+
+          # Process statements
+          process_statement(item) unless item[:header] || item[:direction]
+        end
+
+        def process_statement(stmt)
+          return unless stmt.is_a?(Hash)
+          return process_state_declaration(stmt) if state_declaration?(stmt)
+          return process_transition(stmt) if transition?(stmt)
+          return if handle_ignored_statement?(stmt)
+
+          process_standalone_state(stmt) if standalone_state?(stmt)
+        end
+
+        def state_declaration?(stmt)
+          stmt[:keyword] == "state" && stmt[:state_id]
+        end
+
+        def transition?(stmt)
+          stmt[:from] && stmt[:to]
+        end
+
+        def attached_note?(stmt)
+          stmt[:note_keyword] && stmt[:note_target]
+        end
+
+        def standalone_state?(stmt)
+          stmt[:state_id] && !stmt[:keyword]
+        end
+
+        # Floating notes and styles remain unsupported. A direction nested in
+        # a composite also falls through; it cannot be attached to the model's
+        # flattened state collection.
+        def handle_ignored_statement?(stmt)
+          return false unless stmt[:note_keyword] || stmt[:style_keyword]
+
+          process_note(stmt) if attached_note?(stmt)
+          true
+        end
+
+        def process_note(stmt)
+          target_id = extract_text(stmt[:note_target])
+          target = find_state(target_id)
+          return unless target
+
+          @diagram.notes << Diagram::StateNote.new(
+            id: "#{target_id}----note",
+            text: extract_text(stmt[:note_text]).strip,
+            target_id: target_id,
+            position: extract_text(stmt[:position]),
+          )
+        end
+
+        def process_state_declaration(stmt)
+          state_id = extract_text(stmt[:state_id])
+          label = state_label(stmt)
+          if stmt[:marker]
+            declare_special_state(state_id, stmt[:marker])
+          elsif stmt[:composite]
+            declare_composite_state(state_id, label, stmt[:composite])
+          else
+            update_declared_state(state_id, label, description_of(stmt))
+          end
+        end
+
+        # Marker states have no label because the model has no matching shape
+        # for mermaid's labelled choice/fork/join declarations.
+        def declare_special_state(state_id, marker)
+          add_special_state(state_id, extract_text(marker[:marker_type]))
+        end
+
+        def declare_composite_state(state_id, label, composite)
+          state = process_composite_state(state_id, label, composite)
+          state.declaration_only = false
+          append_display_text(state, label)
+        end
+
+        def update_declared_state(state_id, label, description)
+          existing = find_state(state_id)
+          state = add_or_update_state(state_id, label)
+          state.declaration_only = existing.nil? && label.nil? &&
+            description.nil?
+          append_display_text(state, label)
+          return unless description
+
+          state.description = description
+          append_display_text(state, description)
+        end
+
+        # nil rather than "" when there is no description: every non-nil
+        # value is recorded as display text.
+        def description_of(stmt)
+          extract_text(stmt[:description]) if stmt[:description]
+        end
+
+        def process_standalone_state(stmt)
+          state_id = extract_text(stmt[:state_id])
+          state = ensure_state_exists(state_id)
+          return unless stmt[:description]
+
+          description = extract_text(stmt[:description])
+          state.description = description
+          append_display_text(state, description)
+        end
+
+        # `state "Idle mode" as Idle` labels the state Idle "Idle mode";
+        # without the alias the id is its own label.
+        def state_label(stmt)
+          return unless stmt[:state_label]
+
+          label = extract_text(stmt[:state_label]).strip
+          return if label.empty?
+
+          label
+        end
+
+        def append_display_text(state, text)
+          state.descriptions << text if text && !text.empty?
+        end
+
+        def process_transition(stmt)
+          from_id = extract_state_id(stmt[:from], is_source: true)
+          to_id = extract_state_id(stmt[:to], is_source: false)
+          trigger, guard = parse_transition_label(stmt[:label])
+          create_transition(from_id, to_id, trigger, guard)
+          process_transition_chain(to_id, stmt[:chain])
+        end
+
+        def process_transition_chain(current_from, chain)
+          Array(chain).each do |chain_item|
+            next unless chain_item[:chain_to]
+
+            chain_to = extract_state_id(chain_item[:chain_to], is_source: false)
+            create_transition(current_from, chain_to)
+            current_from = chain_to
+          end
+        end
+
+        def process_composite_state(parent_id, label, composite_data)
+          parent_state = add_or_update_state(parent_id, label)
+          process_composite_statements(parent_state, composite_data)
+
+          parent_state
+        end
+
+        def process_composite_statements(parent, composite_data)
+          statements = statements_in(composite_data)
+          return process_nested_statements(parent.children, statements) unless
+            statements.any? { |item| item[:concurrent_sep] }
+
+          concurrent_groups(statements).each_with_index do |group, index|
+            region = concurrent_region(parent, index)
+            parent.children << region
+            process_nested_statements(region.children, group)
+          end
+        end
+
+        def process_nested_statements(children, statements)
+          within(children) do
+            statements.each { |stmt| process_statement(stmt) }
+          end
+        end
+
+        def concurrent_groups(statements)
+          statements.each_with_object([[]]) do |statement, groups|
+            statement[:concurrent_sep] ? groups << [] : groups.last << statement
+          end
+        end
+
+        def concurrent_region(_parent, _index)
+          @concurrent_region_counter += 1
+          build_state("concurrent_region_#{@concurrent_region_counter}",
+                      nil, "normal")
+        end
+
+        def within(states)
+          previous = @states
+          @states = states
+          yield
+        ensure
+          @states = previous
+        end
+
+        # A marker is a start state as a source and an end state as a target.
+        def extract_state_id(state_data, is_source: nil)
+          state_str = extract_text(state_data)
+          return state_str unless state_str.strip == START_END_MARKER
+
+          is_source ? ensure_start_state : ensure_end_state
+        end
+
+        def ensure_start_state
+          start_state = @states.find(&:start_state?)
+          return start_state.id if start_state
+
+          start_id = generate_state_id("start")
+          state = Diagram::StateNode.new.tap do |s|
+            s.id = start_id
+            s.label = START_END_MARKER
+            s.state_type = "start"
+          end
+          @states << state
+          start_id
+        end
+
+        def ensure_end_state
+          end_state = @states.find(&:end_state?)
+          return end_state.id if end_state
+
+          end_id = generate_state_id("end")
+          state = Diagram::StateNode.new.tap do |s|
+            s.id = end_id
+            s.label = START_END_MARKER
+            s.state_type = "end"
+          end
+          @states << state
+          end_id
+        end
+
+        def ensure_state_exists(state_id)
+          existing = find_state(state_id)
+          return reveal_state(existing) if existing
+
+          state = Diagram::StateNode.new.tap do |s|
+            s.id = state_id
+            s.label = state_id
+            s.state_type = "normal"
+          end
+          @states << state
+          state
+        end
+
+        def reveal_state(state)
+          state.declaration_only = false
+          state
+        end
+
+        def add_special_state(state_id, state_type)
+          existing = find_state(state_id)
+          if existing
+            existing.declaration_only = false
+            return existing
+          end
+
+          state = ensure_state_exists(state_id)
+          state.label = nil
+          state.state_type = state_type
+          state
+        end
+
+        def add_or_update_state(state_id, label = nil)
+          existing = find_state(state_id)
+          return update_state_label(existing, label) if existing
+
+          state = build_state(state_id, label || state_id, "normal")
+          @states << state
+          state
+        end
+
+        def find_state(state_id)
+          @states.find { |state| state.id == state_id } ||
+            @diagram.find_state(state_id)
+        end
+
+        def update_state_label(state, label)
+          state.label = label if label && !label.empty?
+          state
+        end
+
+        def build_state(id, label, type)
+          Diagram::StateNode.new.tap do |state|
+            state.id = id
+            state.label = label
+            state.state_type = type
+          end
+        end
+
+        def create_transition(from_id, to_id, trigger = nil, guard = nil)
+          # Ensure both states exist
+          ensure_state_exists(from_id) unless from_id.start_with?("start_",
+                                                                  "end_")
+          ensure_state_exists(to_id) unless to_id.start_with?("start_", "end_")
+
+          transition = Diagram::StateTransition.new.tap do |t|
+            t.from_id = from_id
+            t.to_id = to_id
+            t.trigger = trigger
+            t.guard_condition = guard
+          end
+          @diagram.transitions << transition
+        end
+
+        # Split "trigger [guard]" while preserving a trigger with no guard.
+        def parse_transition_label(label_data)
+          return [nil, nil] unless label_data
+
+          label_text = extract_text(label_data[:label_text] || label_data).strip
+          return [nil, nil] if label_text.empty?
+
+          match = label_text.match(/^(.+?)\s*\[(.+?)\]\s*$/)
+          return [label_text, nil] unless match
+
+          [match[1].strip, match[2].strip]
+        end
+
+        def generate_state_id(prefix)
+          @state_counter += 1
+          "#{prefix}_#{@state_counter}"
+        end
+
+        def extract_text(value)
+          return value.to_s unless value.is_a?(Hash)
+
+          keys = %i[string marker_type dir_value label_text]
+          key = keys.find { |name| value[name] }
+          key ? value[key].to_s : value.values.first.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/timeline"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting Parslet parse tree to Timeline diagram model.
+      #
+      # Converts the parse tree output from Grammars::Timeline into a
+      # fully-formed Diagram::Timeline object with sections and events.
+      class Timeline
+        ITEM_HANDLERS = {
+          title: :process_title,
+          acc_title: :process_acc_title,
+          acc_descr: :process_acc_descr,
+          section: :process_section,
+          event_entry: :process_event,
+          continuation_entry: :process_continuation,
+          task: :process_task,
+        }.freeze
+        private_constant :ITEM_HANDLERS
+
+        # Transform parse tree into Timeline diagram.
+        #
+        # @param tree [Array, Hash] Parslet parse tree
+        # @return [Diagram::Timeline] the timeline diagram model
+        def apply(tree)
+          diagram = Diagram::Timeline.new
+          @current_section = nil
+          @last_event = nil
+
+          # A bare header parses to one Hash; header plus statements
+          # to an Array.
+          [tree].flatten(1).each { |item| process_item(diagram, item) }
+
+          diagram
+        end
+
+        private
+
+        def process_item(diagram, item)
+          ITEM_HANDLERS.each do |key, handler|
+            send(handler, diagram, item) if item.key?(key)
+          end
+        end
+
+        def process_title(diagram, item)
+          diagram.title = extract_text(item[:title])
+        end
+
+        def process_acc_title(diagram, item)
+          diagram.acc_title = extract_text(item[:acc_title])
+        end
+
+        def process_acc_descr(diagram, item)
+          diagram.acc_description = extract_text(item[:acc_descr])
+        end
+
+        def process_section(diagram, item)
+          section_name = extract_text(item[:section])
+          @current_section = Diagram::TimelineSection.new(section_name)
+          diagram.sections << @current_section
+          @last_event = nil
+        end
+
+        def process_event(diagram, item)
+          event_data = item[:event_entry]
+          return unless event_data
+
+          time = extract_text(event_data[:time])
+          descriptions = extract_descriptions(event_data[:descriptions])
+          event = timeline_event(time, descriptions)
+          @last_event = event
+          append_event(diagram, event)
+        end
+
+        def process_continuation(diagram, item)
+          continuation_data = item[:continuation_entry]
+          return unless continuation_data
+
+          descriptions = extract_descriptions(continuation_data[:descriptions])
+          if @last_event
+            @last_event.descriptions.concat(descriptions)
+          else
+            @last_event = timeline_event("", descriptions)
+            append_event(diagram, @last_event)
+          end
+        end
+
+        def timeline_event(time, descriptions)
+          Diagram::TimelineEvent.new.tap do |event|
+            event.time = time
+            event.descriptions.concat(descriptions)
+          end
+        end
+
+        def append_event(diagram, event)
+          collection = if @current_section
+                         @current_section.events
+                       else
+                         diagram.events
+                       end
+          collection << event
+        end
+
+        def process_task(diagram, item)
+          task_name = extract_text(item[:task])
+          return if task_name.empty?
+
+          event = Diagram::TimelineEvent.new.tap { |e| e.time = task_name }
+          (@current_section || diagram).events << event
+        end
+
+        def extract_descriptions(descriptions_data)
+          return [] unless descriptions_data
+
+          # One description parses to a Hash, several to an Array of Hashes.
+          [descriptions_data].flatten(1).map do |item|
+            extract_text(item[:desc])
+          end.reject(&:empty?)
+        end
+
+        def extract_text(value)
+          case value
+          when String then value
+          else value.to_s
+          end.strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "../../diagram/treemap"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting treemap parse tree to diagram model
+      class Treemap < Parslet::Transform
+        rule(number: simple(:x)) { x.to_f }
+        rule(string: simple(:x)) { x.to_s }
+        rule(string: sequence(:x)) { "" } # Empty string
+        rule(identifier: simple(:x)) { x.to_s }
+
+        rule(keyword: simple(:_kw), statements: subtree(:stmts)) do
+          {
+            type: :treemap,
+            statements: Array(stmts).grep(Hash),
+          }
+        end
+
+        # Title
+        rule(title: simple(:t)) do
+          { type: :title, value: t.to_s }
+        end
+
+        # Accessibility
+        rule(acc_title: simple(:t)) do
+          { type: :acc_title, value: t.to_s }
+        end
+
+        rule(acc_descr: simple(:d)) do
+          { type: :acc_descr, value: d.to_s }
+        end
+
+        # Class definition
+        rule(
+          class_def: {
+            class_name: simple(:name),
+            class_styles: simple(:styles),
+          },
+        ) do
+          {
+            type: :class_def,
+            name: name.to_s,
+            styles: styles.to_s,
+          }
+        end
+
+        # Transform happens bottom-up, so handle nested parts first
+        # Then handle the node structure
+
+        # Node with all fields
+        rule(node: subtree(:n)) do
+          # An empty indent parses to [], a non-empty one to a string.
+          indent_val = n[:indent]
+          indent_len = indent_val.is_a?(Array) ? 0 : indent_val.to_s.length
+
+          result = {
+            type: :node,
+            indent: indent_len,
+            label: n[:label],
+          }
+
+          result[:value] = n[:value] if n.key?(:value)
+          result[:css_class] = n[:css_class].to_s if n.key?(:css_class)
+
+          result
+        end
+
+        # Builds Treemap from the intermediate statement list. #apply
+        # cannot be overridden to do this: Parslet's transform recurses
+        # through it, so it would run on every subtree.
+        #
+        # @param data [Hash] the `{type: :treemap, statements: [...]}`
+        #   hash produced by this class's Parslet rules
+        # @return [Diagram::Treemap] the built diagram
+        def build_diagram(data)
+          diagram = Diagram::Treemap.new
+          statements = data[:statements] || []
+          nodes = statements.filter_map { |stmt| consume(stmt, diagram) }
+          build_hierarchy(diagram, nodes)
+          diagram
+        end
+
+        private
+
+        def consume(statement, diagram)
+          case statement[:type]
+          when :title then diagram.title = statement[:value]
+          when :class_def then add_class_def(statement, diagram)
+          when :acc_title, :acc_descr
+            # Accessibility metadata is parsed, not yet stored on the model.
+          else
+            # Only :node is left: the rules above emit no other type.
+            return statement
+          end
+          nil
+        end
+
+        def add_class_def(statement, diagram)
+          diagram.add_class_def(statement[:name], statement[:styles])
+        end
+
+        # Builds the hierarchical node tree from the flat, indented
+        # node list the parse tree produces.
+        #
+        # @param diagram [Diagram::Treemap] diagram to populate
+        # @param nodes [Array<Hash>] flat node statements, in source
+        #   order, each carrying its indentation level
+        # @return [void]
+        def build_hierarchy(diagram, nodes)
+          stack = []
+          nodes.each do |node_data|
+            indent = node_data[:indent] || 0
+            node = build_node(node_data)
+            stack.pop while stack.any? && stack.last[0] >= indent
+            attach_node(diagram, stack, node)
+            stack.push([indent, node])
+          end
+        end
+
+        def build_node(data)
+          Diagram::TreemapNode.new(data[:label], data[:value]).tap do |node|
+            node.css_class = data[:css_class] if data[:css_class]
+          end
+        end
+
+        def attach_node(diagram, stack, node)
+          return diagram.add_root_node(node) if stack.empty?
+
+          stack.last[1].add_child(node)
+        end
+      end
+    end
+  end
+end