etassia 0.1.0

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

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "parslet"
+require_relative "../../diagram/block"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting block diagram parse trees to diagram models.
+      #
+      # Handles transformation of blocks, compound blocks, connections, and
+      # styling directives from Parslet parse trees into Block objects.
+      class Block < Parslet::Transform
+        # Shape delimiter to type mapping
+        SHAPE_MAP = {
+          "[]" => "rect",
+          "(())" => "circle",
+        }.freeze
+
+        # Arrow type mapping
+        ARROW_MAP = {
+          "-->" => "arrow",
+          "---" => "line",
+        }.freeze
+
+        STATEMENT_HANDLERS = [
+          [:columns_keyword, nil],
+          %i[space_keyword process_space],
+          %i[arrow_id process_arrow],
+          %i[compound_keyword process_compound],
+          %i[block_id process_block],
+          [%i[from to], :process_connection],
+          %i[style_keyword process_style],
+        ].freeze
+
+        # Block ID
+        rule(block_id: simple(:id)) { id.to_s }
+        rule(block_id: { string: simple(:s) }) { s.to_s }
+
+        # Block width (grammar includes colon, e.g. ":2")
+        rule(block_width: simple(:w)) { w.to_s.sub(/^:/, "").to_i }
+
+        # Arrow direction
+        rule(arrow_direction: { direction: simple(:d) }) { d.to_s }
+
+        # Shape with label
+        rule(
+          block_shape: {
+            open: simple(:o),
+            label: simple(:l),
+            close: simple(:c),
+          },
+        ) do
+          delims = "#{o}#{c}"
+          {
+            shape_type: SHAPE_MAP[delims] || "rect",
+            label: l.to_s.strip,
+          }
+        end
+
+        # Handle empty labels
+        rule(
+          block_shape: {
+            open: simple(:o),
+            label: sequence(:_),
+            close: simple(:c),
+          },
+        ) do
+          delims = "#{o}#{c}"
+          {
+            shape_type: SHAPE_MAP[delims] || "rect",
+            label: "",
+          }
+        end
+
+        # Process parsed diagram.
+        #
+        # Deliberately builds its own diagram rather than accepting one. Ids
+        # are positional, so feeding a second tree into a populated diagram
+        # would re-issue "compound-1" and the later block would overwrite the
+        # earlier one. No caller ever passed a diagram, so the parameter only
+        # exposed that hazard.
+        def apply(tree)
+          diagram = Diagram::Block.new
+          statements = tree.is_a?(Array) ? tree : [tree]
+          assign_columns(diagram, statements)
+          process_statements(diagram, statements)
+          diagram
+        end
+
+        def assign_columns(diagram, statements)
+          statement = statements.find do |item|
+            item.is_a?(Hash) && item[:columns_keyword] && item[:columns_value]
+          end
+          diagram.columns = statement[:columns_value].to_s.to_i if statement
+        end
+
+        def process_statements(diagram, statements, parent_block = nil)
+          statements.each_with_index do |stmt, index|
+            next unless stmt.is_a?(Hash)
+
+            handler = statement_handler(stmt)
+            send(handler, diagram, stmt, parent_block, index) if handler
+          end
+        end
+
+        def statement_handler(stmt)
+          match = STATEMENT_HANDLERS.find do |keys, _|
+            required_keys = keys.is_a?(Array) ? keys : [keys]
+            required_keys.all? { |key| stmt[key] }
+          end
+          match&.last
+        end
+
+        def process_space(diagram, _stmt, parent_block, index)
+          block = create_space_block(parent_block, index)
+          add_block(diagram, parent_block, block)
+        end
+
+        def process_arrow(diagram, stmt, parent_block, _index)
+          add_block(diagram, parent_block, create_arrow_block(stmt))
+        end
+
+        def process_compound(diagram, stmt, parent_block, index)
+          block = create_compound_block(stmt, parent_block, index)
+          process_compound_children(diagram, stmt[:compound_statements], block)
+          add_block(diagram, parent_block, block)
+        end
+
+        def process_compound_children(diagram, statements, block)
+          return unless statements
+
+          children = statements.is_a?(Array) ? statements : [statements]
+          process_statements(diagram, children, block)
+        end
+
+        def process_block(diagram, stmt, parent_block, _index)
+          add_block(diagram, parent_block, create_block(stmt))
+        end
+
+        def process_connection(diagram, stmt, _parent_block, _index)
+          diagram.add_connection(create_connection(stmt))
+        end
+
+        def process_style(diagram, stmt, _parent_block, _index)
+          diagram.add_style(create_style(stmt))
+        end
+
+        def add_block(diagram, parent_block, block)
+          return parent_block.add_child(block) if parent_block
+
+          diagram.add_block(block)
+        end
+
+        # Anonymous ids are derived from the statement's position and its
+        # parent, never randomly. A random id varies in digit length, and
+        # that length reaches TextMeasurement, so the same source used to
+        # render at different sizes between runs.
+        #
+        # The hyphen separator is what keeps these ids out of the author's
+        # namespace: identifier_char is [a-zA-Z0-9_], so no bare block id can
+        # ever spell "compound-1". An underscore could, and the collision
+        # silently dropped the generated block's children from the SVG.
+        def anonymous_id(kind, parent_block, index)
+          prefix = parent_block ? "#{parent_block.id}-" : ""
+          "#{prefix}#{kind}-#{index}"
+        end
+
+        def create_space_block(parent_block, index)
+          Diagram::BlockNode.new.tap do |b|
+            b.id = anonymous_id("space", parent_block, index)
+            b.block_type = "space"
+          end
+        end
+
+        def create_arrow_block(stmt)
+          Diagram::BlockNode.new.tap do |b|
+            b.id = stmt[:arrow_id].to_s
+            b.block_type = "arrow"
+            b.label = stmt[:arrow_label].to_s if stmt[:arrow_label]
+            b.direction = stmt[:arrow_direction].to_s if stmt[:arrow_direction]
+          end
+        end
+
+        def create_compound_block(stmt, parent_block, index)
+          Diagram::BlockNode.new.tap do |b|
+            b.id = if stmt[:compound_id]
+                     stmt[:compound_id].to_s
+                   else
+                     anonymous_id("compound", parent_block, index)
+                   end
+            b.is_compound = true
+          end
+        end
+
+        def create_block(stmt)
+          Diagram::BlockNode.new.tap do |b|
+            b.id = stmt[:block_id].to_s
+            assign_width(b, stmt[:block_width])
+            assign_shape(b, stmt[:block_shape])
+          end
+        end
+
+        def assign_width(block, width)
+          return unless width
+
+          value = width.is_a?(Hash) ? width[:width] : width.to_s.sub(/^:/, "")
+          block.width = value.to_i
+        end
+
+        def assign_shape(block, shape)
+          return block.label = block.id unless shape
+          return unless shape.is_a?(Hash)
+
+          handler = shape_handler(shape)
+          send(handler, block, shape) if handler
+        end
+
+        def shape_handler(shape)
+          return :assign_raw_shape if shape[:open] && shape[:close]
+
+          :assign_transformed_shape if shape[:shape_type]
+        end
+
+        def assign_transformed_shape(block, shape)
+          block.shape = shape[:shape_type] || "rect"
+          block.label = unquote(shape[:label] || block.id)
+        end
+
+        def assign_raw_shape(block, shape)
+          delimiters = "#{shape[:open]}#{shape[:close]}"
+          block.shape = SHAPE_MAP[delimiters] || "rect"
+          block.label = unquote(shape[:label])
+        end
+
+        def unquote(label)
+          label.to_s.gsub(/^["']|["']$/, "")
+        end
+
+        def create_connection(stmt)
+          Diagram::BlockConnection.new.tap do |c|
+            c.from = stmt[:from].to_s
+            c.to = stmt[:to].to_s
+            c.connection_type = connection_type(stmt[:arrow])
+          end
+        end
+
+        def connection_type(arrow)
+          return "arrow" unless arrow
+
+          type = arrow[:arrow_type] || arrow[:line_type]
+          ARROW_MAP[type.to_s] || "arrow"
+        end
+
+        def create_style(stmt)
+          Diagram::BlockStyle.new.tap do |s|
+            s.block_id = stmt[:style_target].to_s
+            assign_style_properties(s, stmt[:style_props])
+          end
+        end
+
+        def assign_style_properties(style, properties)
+          return unless properties
+
+          values = properties.is_a?(Array) ? properties : [properties]
+          values.each { |property| assign_style_property(style, property) }
+        end
+
+        def assign_style_property(style, property)
+          value = property.to_s.strip
+          if value.start_with?("fill:")
+            style.fill = property_value(value, "fill:")
+          elsif value.start_with?("stroke:")
+            style.stroke = property_value(value, "stroke:")
+          elsif value.start_with?("stroke-width:")
+            style.stroke_width = property_value(value, "stroke-width:")
+          else
+            style.properties << value
+          end
+        end
+
+        def property_value(property, prefix)
+          property.sub(prefix, "").strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative "capture_string"
+require_relative "../../diagram/c4"
+
+module Etassia
+  module Parser
+    module Builders
+      # Transform for converting Parslet parse tree to C4 diagram model.
+      #
+      # Converts the parse tree output from Grammars::C4 into a
+      # fully-formed Diagram::C4 object with elements, relationships, and
+      # boundaries.
+      class C4
+        include CaptureString
+
+        LEVELS = {
+          "C4Context" => "Context",
+          "C4Container" => "Container",
+          "C4Component" => "Component",
+          "C4Dynamic" => "Dynamic",
+          "C4Deployment" => "Deployment",
+        }.freeze
+        private_constant :LEVELS
+
+        STATEMENT_HANDLERS = {
+          header: :ignore_statement,
+          title: :process_title,
+          config_params: :process_layout_config,
+          boundary_type: :process_boundary,
+          rel_type: :process_relationship,
+          element_type: :process_element,
+        }.freeze
+        private_constant :STATEMENT_HANDLERS
+
+        SCATTERED_STOP_KEYS = %i[
+          element_type boundary_type rel_type title config_params header
+        ].freeze
+        private_constant :SCATTERED_STOP_KEYS
+
+        BOUNDARY_FIELDS = {
+          id: :id=,
+          label: :label=,
+          type: :type_param=,
+          link: :link=,
+          tags: :tags=,
+        }.freeze
+        private_constant :BOUNDARY_FIELDS
+
+        ELEMENT_FIELDS = {
+          id: :id=,
+          label: :label=,
+          description: :description=,
+          technology: :technology=,
+          sprite: :sprite=,
+          link: :link=,
+          tags: :tags=,
+        }.freeze
+        private_constant :ELEMENT_FIELDS
+
+        RELATIONSHIP_FIELDS = {
+          from: :from_id=,
+          to: :to_id=,
+          label: :label=,
+          technology: :technology=,
+        }.freeze
+        private_constant :RELATIONSHIP_FIELDS
+
+        def initialize
+          @boundary_stack = []
+          @current_boundary = nil
+        end
+
+        # Transform parse tree into C4 diagram.
+        #
+        # @param tree [Array, Hash] Parslet parse tree
+        # @return [Diagram::C4] the C4 diagram model
+        def apply(tree)
+          diagram = Diagram::C4.new
+          @boundary_stack = []
+          @current_boundary = nil
+          extract_level(diagram, tree)
+
+          statements(tree).each { |item| process_statement(diagram, item) }
+
+          diagram
+        end
+
+        private
+
+        def statements(tree)
+          return merge_scattered_attributes(tree) if tree.is_a?(Array)
+          return [tree] if tree.is_a?(Hash)
+
+          []
+        end
+
+        def merge_scattered_attributes(tree)
+          result = []
+          index = 0
+          while index < tree.length
+            item, index = merge_scattered_item(tree, index)
+            result << item
+          end
+          result
+        end
+
+        def merge_scattered_item(tree, index)
+          item = tree[index]
+          return [item, index + 1] unless scattered_statement?(item)
+
+          merge_following_attributes(tree, item, index + 1)
+        end
+
+        def scattered_statement?(item)
+          item.is_a?(Hash) &&
+            (item[:element_type] || item[:boundary_type]) && !item[:body]
+        end
+
+        def merge_following_attributes(tree, item, index)
+          while mergeable_attribute?(tree[index])
+            item = item.merge(tree[index])
+            index += 1
+          end
+          [item, index]
+        end
+
+        def mergeable_attribute?(item)
+          item.is_a?(Hash) && SCATTERED_STOP_KEYS.none? { |key| item[key] }
+        end
+
+        def extract_level(diagram, tree)
+          header = find_header(tree)
+          return unless header
+
+          diagram.level = LEVELS.fetch(header[:header].to_s, "Context")
+        end
+
+        def find_header(tree)
+          if tree.is_a?(Array)
+            return tree.find { |item| item.is_a?(Hash) && item[:header] }
+          end
+
+          tree if tree.is_a?(Hash) && tree[:header]
+        end
+
+        def process_statement(diagram, stmt)
+          return unless stmt.is_a?(Hash)
+
+          kind = STATEMENT_HANDLERS.keys.find { |key| stmt[key] }
+          send(STATEMENT_HANDLERS.fetch(kind), diagram, stmt) if kind
+        end
+
+        def ignore_statement(_diagram, _stmt); end
+
+        def process_title(diagram, stmt)
+          diagram.title = extract_text(stmt[:title])
+        end
+
+        def process_layout_config(diagram, stmt)
+          params = stmt[:config_params]
+          diagram.layout_config = config_parts(params).join(", ")
+        end
+
+        def config_parts(params)
+          if params.is_a?(Array)
+            return params.filter_map { |param| config_part(param, true) }
+          end
+          return [config_part(params, false)] if params.is_a?(Hash)
+
+          []
+        end
+
+        def config_part(param, require_values)
+          key = extract_text(param[:key]) if param[:key]
+          value = extract_text(param[:value]) if param[:value]
+          return if require_values && (!key || !value)
+
+          "#{key}=#{value}"
+        end
+
+        def process_boundary(diagram, stmt)
+          boundary = create_boundary(stmt)
+          diagram.boundaries << boundary
+          process_boundary_body(diagram, boundary, stmt[:body]) if stmt[:body]
+          boundary.id
+        end
+
+        def create_boundary(stmt)
+          Diagram::C4Boundary.new.tap do |boundary|
+            boundary.boundary_type = type_name(stmt[:boundary_type])
+            assign_fields(boundary, stmt, BOUNDARY_FIELDS)
+            boundary.parent_id = @current_boundary if @current_boundary
+          end
+        end
+
+        def process_boundary_body(diagram, boundary, body)
+          old_boundary = @current_boundary
+          @current_boundary = boundary.id
+          nested_statements(body).each do |nested_item|
+            process_nested_statement(diagram, boundary, nested_item)
+          end
+        ensure
+          @current_boundary = old_boundary
+        end
+
+        def nested_statements(body)
+          items = (body.is_a?(Array) ? body : [body]).flat_map do |item|
+            item.is_a?(Hash) && item[:item] ? [item[:item]].flatten : []
+          end
+          merge_scattered_attributes(items)
+        end
+
+        def process_nested_statement(diagram, boundary, stmt)
+          if stmt[:boundary_type]
+            id = process_boundary(diagram, stmt)
+            boundary.boundary_ids << id if id
+          elsif stmt[:element_type]
+            id = process_element(diagram, stmt)
+            boundary.element_ids << id if id
+          end
+        end
+
+        def process_element(diagram, stmt)
+          element = create_element(stmt)
+          element.boundary_id = @current_boundary if @current_boundary
+          diagram.elements << element
+          element.id
+        end
+
+        def create_element(stmt)
+          Diagram::C4Element.new.tap do |element|
+            element.element_type = type_name(stmt[:element_type])
+            assign_fields(element, stmt, ELEMENT_FIELDS)
+            element.external = element.element_type&.end_with?("_Ext") || false
+          end
+        end
+
+        def process_relationship(diagram, stmt)
+          relationship = Diagram::C4Relationship.new.tap do |item|
+            item.rel_type = stmt[:rel_type].to_s
+            assign_fields(item, stmt, RELATIONSHIP_FIELDS)
+          end
+          diagram.relationships << relationship
+        end
+
+        def assign_fields(target, stmt, fields)
+          fields.each do |capture, writer|
+            next unless stmt[capture]
+
+            target.public_send(writer, extract_text(stmt[capture]))
+          end
+        end
+
+        def type_name(value)
+          return value.to_s unless value.is_a?(Hash) && value[:variable]
+
+          extract_text(value[:variable][:var])
+        end
+
+        def extract_text(value)
+          text = value.is_a?(Hash) ? extract_hash_text(value) : value.to_s
+          text.strip
+        end
+
+        def extract_hash_text(value)
+          return capture_string(value[:string]) if value[:string]
+          return value[:var].to_s if value[:var]
+
+          value.values.first.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Parser
+    module Builders
+      # Parslet captures an empty `.repeat.as(:string)` as `[]`, not as an
+      # empty slice, so `""` would otherwise render as the text "[]".
+      module CaptureString
+        private
+
+        def capture_string(capture)
+          capture.is_a?(Array) ? "" : capture.to_s
+        end
+      end
+    end
+  end
+end