sirena 0.1.0

data/lib/sirena/transform/base.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Sirena
+  module Transform
+    # Abstract base class for diagram transformers.
+    #
+    # Transformers convert typed diagram models into generic graph structures
+    # suitable for layout computation by elkrb. Each diagram type has its own
+    # transformer that maps diagram-specific elements to graph nodes and edges.
+    #
+    # The transformer is also responsible for calculating node dimensions
+    # using TextMeasurement and setting appropriate layout options.
+    #
+    # @example Define a custom transformer
+    #   class FlowchartTransform < Transform::Base
+    #     def to_graph(diagram)
+    #       graph = create_graph
+    #       # Add nodes and edges based on diagram structure
+    #       graph
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement #to_graph
+    class Base
+      # ELK layout algorithms supported (matching mermaid-js)
+      # @see https://www.eclipse.org/elk/reference/algorithms.html
+      ALGORITHM_LAYERED = 'layered'
+      ALGORITHM_STRESS = 'stress'
+      ALGORITHM_FORCE = 'force'
+      ALGORITHM_MRTREE = 'mrtree'
+      ALGORITHM_SPORE_OVERLAP = 'sporeOverlap'
+
+      # ELK layout directions
+      DIRECTION_DOWN = 'DOWN'
+      DIRECTION_UP = 'UP'
+      DIRECTION_LEFT = 'LEFT'
+      DIRECTION_RIGHT = 'RIGHT'
+
+      # Default spacing values (in pixels)
+      DEFAULT_NODE_SPACING = 50
+      DEFAULT_EDGE_SPACING = 30
+      DEFAULT_LAYER_SPACING = 50
+
+      # ELK option keys for consistent configuration
+      # @see https://www.eclipse.org/elk/reference/options.html
+      module ElkOptions
+        ALGORITHM = 'algorithm'
+        DIRECTION = 'elk.direction'
+
+        # Spacing options
+        NODE_NODE_SPACING = 'elk.spacing.nodeNode'
+        EDGE_NODE_SPACING = 'elk.spacing.edgeNode'
+        EDGE_EDGE_SPACING = 'elk.spacing.edgeEdge'
+        LAYER_SPACING = 'elk.layered.spacing.nodeNodeBetweenLayers'
+
+        # Layered algorithm options
+        NODE_PLACEMENT = 'elk.layered.nodePlacement.strategy'
+        CROSSING_MINIMIZATION =
+          'elk.layered.crossingMinimization.strategy'
+        MODEL_ORDER = 'elk.layered.considerModelOrder.strategy'
+        COMPACTION = 'elk.layered.compaction.postCompaction.strategy'
+
+        # Hierarchy and grouping
+        HIERARCHY_HANDLING = 'elk.hierarchyHandling'
+
+        # Edge routing
+        EDGE_ROUTING = 'elk.edgeRouting'
+      end
+
+      # Converts a diagram model to an elkrb graph structure.
+      #
+      # This method should be overridden by subclasses to implement
+      # diagram-specific graph conversion logic.
+      #
+      # @param diagram [Diagram::Base] the diagram model to convert
+      # @return [Object] elkrb graph object with nodes and edges
+      # @raise [NotImplementedError] if not implemented by subclass
+      def to_graph(diagram)
+        raise NotImplementedError,
+              "#{self.class} must implement #to_graph(diagram)"
+      end
+
+      protected
+
+      # Measures text dimensions for node sizing.
+      #
+      # @param text [String] the text to measure
+      # @param font_size [Numeric] the font size in points
+      # @param width [Numeric, nil] optional width override
+      # @param height [Numeric, nil] optional height override
+      # @return [Hash] hash with :width and :height keys
+      def measure_text(text, font_size:, width: nil, height: nil)
+        TextMeasurement.measure(text,
+                                font_size: font_size,
+                                width: width,
+                                height: height)
+      end
+
+      # Creates ELK layout options with proper configuration.
+      #
+      # This method provides sensible defaults based on mermaid-js patterns
+      # and can be overridden by subclasses for diagram-specific needs.
+      #
+      # @param algorithm [String] ELK algorithm to use
+      # @param direction [String] layout direction
+      # @param options [Hash] additional ELK options to merge
+      # @return [Hash] complete ELK layout options
+      def build_elk_options(algorithm: ALGORITHM_LAYERED,
+                           direction: DIRECTION_DOWN,
+                           **options)
+        base_options = {
+          ElkOptions::ALGORITHM => algorithm,
+          ElkOptions::DIRECTION => direction
+        }
+
+        # Add algorithm-specific defaults
+        case algorithm
+        when ALGORITHM_LAYERED
+          base_options.merge!(layered_algorithm_options)
+        when ALGORITHM_STRESS, ALGORITHM_FORCE
+          base_options.merge!(force_based_algorithm_options)
+        end
+
+        base_options.merge(options)
+      end
+
+      # Default layout options for layered algorithm.
+      #
+      # The layered algorithm is optimal for hierarchical diagrams like
+      # flowcharts, sequence diagrams, and class diagrams. It minimizes
+      # edge crossings and places nodes in distinct layers.
+      #
+      # @return [Hash] layered algorithm options
+      def layered_algorithm_options
+        {
+          # Node and edge spacing
+          ElkOptions::NODE_NODE_SPACING => DEFAULT_NODE_SPACING,
+          ElkOptions::EDGE_NODE_SPACING => DEFAULT_EDGE_SPACING,
+          ElkOptions::EDGE_EDGE_SPACING => DEFAULT_EDGE_SPACING,
+          ElkOptions::LAYER_SPACING => DEFAULT_LAYER_SPACING,
+
+          # Use SIMPLE node placement for predictable layouts
+          ElkOptions::NODE_PLACEMENT => 'SIMPLE',
+
+          # Consider model order for consistent positioning
+          ElkOptions::MODEL_ORDER => 'NODES_AND_EDGES'
+        }
+      end
+
+      # Default layout options for force-based algorithms.
+      #
+      # Force-based algorithms (stress, force) are optimal for graphs
+      # without clear hierarchy, like ER diagrams or network diagrams.
+      #
+      # @return [Hash] force-based algorithm options
+      def force_based_algorithm_options
+        {
+          ElkOptions::NODE_NODE_SPACING => DEFAULT_NODE_SPACING * 1.5,
+          ElkOptions::EDGE_NODE_SPACING => DEFAULT_EDGE_SPACING,
+          ElkOptions::EDGE_EDGE_SPACING => DEFAULT_EDGE_SPACING
+        }
+      end
+
+      # Calculates node padding based on content type.
+      #
+      # @param node_type [Symbol] the type of node
+      # @return [Hash] padding hash with :top, :bottom, :left, :right
+      def node_padding(node_type)
+        case node_type
+        when :rect
+          { top: 10, bottom: 10, left: 15, right: 15 }
+        when :circle
+          { top: 15, bottom: 15, left: 15, right: 15 }
+        when :diamond
+          { top: 20, bottom: 20, left: 20, right: 20 }
+        else
+          { top: 10, bottom: 10, left: 10, right: 10 }
+        end
+      end
+
+      # Calculates total node dimensions including padding.
+      #
+      # @param content_width [Numeric] width of node content
+      # @param content_height [Numeric] height of node content
+      # @param node_type [Symbol] the type of node
+      # @return [Hash] dimensions hash with :width and :height
+      def calculate_node_dimensions(content_width, content_height, node_type)
+        padding = node_padding(node_type)
+        {
+          width: content_width + padding[:left] + padding[:right],
+          height: content_height + padding[:top] + padding[:bottom]
+        }
+      end
+    end
+
+    # Error raised during transformation.
+    class TransformError < StandardError; end
+  end
+end

data/lib/sirena/transform/block.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../diagram/block'
+
+module Sirena
+  module Transform
+    # Block diagram transformer for converting block models to positioned layouts.
+    #
+    # Converts a typed block diagram model into a column-based layout structure.
+    # Handles block dimension calculation, column-based positioning, and
+    # connection routing.
+    #
+    # @example Transform a block diagram
+    #   transform = BlockTransform.new
+    #   layout = transform.to_layout(block_diagram)
+    class BlockTransform < Base
+      # Default dimensions
+      DEFAULT_BLOCK_WIDTH = 100
+      DEFAULT_BLOCK_HEIGHT = 60
+      DEFAULT_SPACING = 20
+      DEFAULT_COMPOUND_PADDING = 20
+
+      # Converts a block diagram to a positioned layout structure.
+      #
+      # @param diagram [Diagram::BlockDiagram] the block diagram to transform
+      # @return [Hash] positioned layout hash
+      # @raise [TransformError] if diagram is invalid
+      def to_graph(diagram)
+        raise TransformError, 'Diagram cannot be nil' if diagram.nil?
+
+        blocks_layout = calculate_column_layout(diagram)
+        connections_layout = calculate_connections(diagram, blocks_layout)
+
+        {
+          blocks: blocks_layout,
+          connections: connections_layout,
+          columns: diagram.columns,
+          width: calculate_total_width(blocks_layout, diagram.columns),
+          height: calculate_total_height(blocks_layout)
+        }
+      end
+
+      private
+
+      def calculate_column_layout(diagram)
+        columns = diagram.columns
+        blocks = diagram.blocks
+        positioned_blocks = {}
+
+        current_row = 0
+        current_col = 0
+        row_heights = []
+        col_widths = Array.new(columns, 0)
+
+        blocks.each do |block|
+          # Handle space blocks
+          if block.space?
+            current_col += 1
+            if current_col >= columns
+              current_col = 0
+              current_row += 1
+            end
+            next
+          end
+
+          # Calculate block dimensions
+          dims = calculate_block_dimensions(block)
+          block_width = block.width || 1
+
+          # Check if block fits in current row
+          if current_col + block_width > columns
+            current_col = 0
+            current_row += 1
+          end
+
+          # Position block
+          x = calculate_x_position(current_col, col_widths)
+          y = calculate_y_position(current_row, row_heights)
+
+          positioned_blocks[block.id] = {
+            block: block,
+            x: x,
+            y: y,
+            width: dims[:width] * block_width,
+            height: dims[:height],
+            row: current_row,
+            col: current_col,
+            col_span: block_width
+          }
+
+          # Update column widths
+          (current_col...current_col + block_width).each do |col|
+            col_widths[col] = [col_widths[col], dims[:width]].max if col < columns
+          end
+
+          # Update row height
+          row_heights[current_row] = [row_heights[current_row] || 0, dims[:height]].max
+
+          # Handle compound blocks
+          if block.compound? && !block.children.empty?
+            child_layout = layout_compound_children(block, x, y, dims)
+            positioned_blocks.merge!(child_layout)
+          end
+
+          # Move to next position
+          current_col += block_width
+          if current_col >= columns
+            current_col = 0
+            current_row += 1
+          end
+        end
+
+        positioned_blocks
+      end
+
+      def layout_compound_children(parent_block, parent_x, parent_y, parent_dims)
+        positioned = {}
+        child_y = parent_y + DEFAULT_COMPOUND_PADDING
+
+        parent_block.children.each_with_index do |child, index|
+          child_dims = calculate_block_dimensions(child)
+
+          positioned[child.id] = {
+            block: child,
+            x: parent_x + DEFAULT_COMPOUND_PADDING,
+            y: child_y,
+            width: child_dims[:width],
+            height: child_dims[:height],
+            parent_id: parent_block.id
+          }
+
+          child_y += child_dims[:height] + DEFAULT_SPACING
+        end
+
+        positioned
+      end
+
+      def calculate_block_dimensions(block)
+        if block.arrow?
+          return {
+            width: DEFAULT_BLOCK_WIDTH / 2,
+            height: DEFAULT_BLOCK_HEIGHT / 2
+          }
+        end
+
+        label = block.label || block.id
+        label_dims = measure_text(label, font_size: 14)
+
+        # Add padding
+        width = [label_dims[:width] + 40, DEFAULT_BLOCK_WIDTH].max
+        height = [label_dims[:height] + 30, DEFAULT_BLOCK_HEIGHT].max
+
+        if block.compound?
+          # Compound blocks need more space
+          child_height = block.children.reduce(0) do |sum, child|
+            child_dims = calculate_block_dimensions(child)
+            sum + child_dims[:height] + DEFAULT_SPACING
+          end
+          height = [height, child_height + DEFAULT_COMPOUND_PADDING * 2].max
+        end
+
+        {
+          width: width,
+          height: height
+        }
+      end
+
+      def calculate_x_position(col, col_widths)
+        return DEFAULT_SPACING if col == 0
+
+        col_widths[0...col].sum + (DEFAULT_SPACING * (col + 1))
+      end
+
+      def calculate_y_position(row, row_heights)
+        return DEFAULT_SPACING if row == 0
+
+        row_heights[0...row].sum + (DEFAULT_SPACING * (row + 1))
+      end
+
+      def calculate_connections(diagram, blocks_layout)
+        diagram.connections.map do |conn|
+          from_block = blocks_layout[conn.from]
+          to_block = blocks_layout[conn.to]
+
+          next unless from_block && to_block
+
+          {
+            from: conn.from,
+            to: conn.to,
+            from_x: from_block[:x] + from_block[:width] / 2,
+            from_y: from_block[:y] + from_block[:height],
+            to_x: to_block[:x] + to_block[:width] / 2,
+            to_y: to_block[:y],
+            connection_type: conn.connection_type
+          }
+        end.compact
+      end
+
+      def calculate_total_width(blocks_layout, columns)
+        return DEFAULT_SPACING * 2 if blocks_layout.empty?
+
+        max_x = blocks_layout.values.map { |b| b[:x] + b[:width] }.max || 0
+        max_x + DEFAULT_SPACING
+      end
+
+      def calculate_total_height(blocks_layout)
+        return DEFAULT_SPACING * 2 if blocks_layout.empty?
+
+        max_y = blocks_layout.values.map { |b| b[:y] + b[:height] }.max || 0
+        max_y + DEFAULT_SPACING
+      end
+    end
+  end
+end

data/lib/sirena/transform/c4.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../diagram/c4'
+
+module Sirena
+  module Transform
+    # C4 transformer for converting C4 models to graphs.
+    #
+    # Converts a typed C4 diagram model into a generic graph structure
+    # suitable for layout computation by elkrb. Handles element positioning,
+    # boundary grouping, and relationship routing.
+    #
+    # @example Transform a C4 diagram
+    #   transform = C4Transform.new
+    #   graph = transform.to_graph(c4_diagram)
+    class C4Transform < Base
+      # Default font size for text measurement
+      DEFAULT_FONT_SIZE = 14
+
+      # Element dimensions based on type
+      PERSON_WIDTH = 140
+      PERSON_HEIGHT = 180
+      SYSTEM_WIDTH = 160
+      SYSTEM_HEIGHT = 120
+      CONTAINER_WIDTH = 160
+      CONTAINER_HEIGHT = 120
+      COMPONENT_WIDTH = 160
+      COMPONENT_HEIGHT = 100
+
+      # Spacing
+      ELEMENT_SPACING = 60
+      BOUNDARY_PADDING = 40
+      LEVEL_SPACING = 80
+
+      # Converts a C4 diagram to a graph structure.
+      #
+      # @param diagram [Diagram::C4] the C4 diagram to transform
+      # @return [Hash] elkrb-compatible graph hash
+      # @raise [TransformError] if diagram is invalid
+      def to_graph(diagram)
+        raise TransformError, 'Invalid diagram' unless diagram.valid?
+
+        # Build hierarchy with boundaries as containers
+        root_elements = diagram.elements.select { |e| e.boundary_id.nil? }
+        root_boundaries = diagram.boundaries.select { |b| b.parent_id.nil? }
+
+        {
+          id: diagram.id || 'c4',
+          children: transform_root_nodes(diagram, root_elements,
+                                         root_boundaries),
+          edges: transform_relationships(diagram),
+          layoutOptions: layout_options(diagram),
+          metadata: {
+            level: diagram.level,
+            title: diagram.title,
+            element_count: diagram.elements.length,
+            relationship_count: diagram.relationships.length
+          }
+        }
+      end
+
+      private
+
+      def transform_root_nodes(diagram, elements, boundaries)
+        nodes = []
+
+        # Add root-level boundaries (which contain their own elements)
+        boundaries.each do |boundary|
+          nodes << transform_boundary(diagram, boundary)
+        end
+
+        # Add root-level elements (not in any boundary)
+        elements.each do |element|
+          nodes << transform_element(element)
+        end
+
+        nodes
+      end
+
+      def transform_boundary(diagram, boundary)
+        # Get elements in this boundary
+        elements = diagram.elements_in_boundary(boundary.id)
+        child_boundaries = diagram.boundaries_in_boundary(boundary.id)
+
+        children = []
+
+        # Add child boundaries first
+        child_boundaries.each do |child_boundary|
+          children << transform_boundary(diagram, child_boundary)
+        end
+
+        # Add elements in this boundary
+        elements.each do |element|
+          children << transform_element(element)
+        end
+
+        # Calculate boundary dimensions based on contents
+        dims = calculate_boundary_dimensions(children)
+
+        {
+          id: boundary.id,
+          width: dims[:width],
+          height: dims[:height],
+          labels: [
+            {
+              text: boundary.label,
+              width: measure_text(boundary.label,
+                                  font_size: DEFAULT_FONT_SIZE + 2)[:width],
+              height: measure_text(boundary.label,
+                                   font_size: DEFAULT_FONT_SIZE + 2)[:height]
+            }
+          ],
+          children: children,
+          layoutOptions: boundary_layout_options,
+          metadata: {
+            boundary_type: boundary.boundary_type,
+            type_param: boundary.type_param,
+            link: boundary.link,
+            tags: boundary.tags
+          }
+        }
+      end
+
+      def transform_element(element)
+        dims = element_dimensions(element)
+
+        labels = []
+
+        # Main label
+        label_dims = measure_text(element.label,
+                                   font_size: DEFAULT_FONT_SIZE + 2)
+        labels << {
+          text: element.label,
+          width: label_dims[:width],
+          height: label_dims[:height]
+        }
+
+        # Description (if present)
+        if element.description && !element.description.empty?
+          desc_dims = measure_text(element.description,
+                                    font_size: DEFAULT_FONT_SIZE - 2)
+          labels << {
+            text: element.description,
+            width: desc_dims[:width],
+            height: desc_dims[:height]
+          }
+        end
+
+        # Technology (if present)
+        if element.technology && !element.technology.empty?
+          tech_dims = measure_text(element.technology,
+                                    font_size: DEFAULT_FONT_SIZE - 2)
+          labels << {
+            text: "[#{element.technology}]",
+            width: tech_dims[:width],
+            height: tech_dims[:height]
+          }
+        end
+
+        {
+          id: element.id,
+          width: dims[:width],
+          height: dims[:height],
+          labels: labels,
+          metadata: {
+            element_type: element.element_type,
+            base_type: element.base_type,
+            external: element.external,
+            sprite: element.sprite,
+            link: element.link,
+            tags: element.tags,
+            person: element.person?,
+            system: element.system?,
+            container: element.container?,
+            component: element.component?
+          }
+        }
+      end
+
+      def transform_relationships(diagram)
+        return [] if diagram.relationships.nil? || diagram.relationships.empty?
+
+        diagram.relationships.map.with_index do |rel, index|
+          labels = []
+
+          if rel.label && !rel.label.empty?
+            label_dims = measure_text(rel.label, font_size: DEFAULT_FONT_SIZE)
+            labels << {
+              text: rel.label,
+              width: label_dims[:width],
+              height: label_dims[:height]
+            }
+          end
+
+          if rel.technology && !rel.technology.empty?
+            tech_dims = measure_text("[#{rel.technology}]",
+                                      font_size: DEFAULT_FONT_SIZE - 2)
+            labels << {
+              text: "[#{rel.technology}]",
+              width: tech_dims[:width],
+              height: tech_dims[:height]
+            }
+          end
+
+          {
+            id: "rel_#{index}",
+            sources: [rel.from_id],
+            targets: [rel.to_id],
+            labels: labels,
+            metadata: {
+              rel_type: rel.rel_type,
+              bidirectional: rel.bidirectional?
+            }
+          }
+        end
+      end
+
+      def element_dimensions(element)
+        # Base dimensions on element type
+        if element.person?
+          { width: PERSON_WIDTH, height: PERSON_HEIGHT }
+        elsif element.system?
+          { width: SYSTEM_WIDTH, height: SYSTEM_HEIGHT }
+        elsif element.container?
+          { width: CONTAINER_WIDTH, height: CONTAINER_HEIGHT }
+        elsif element.component?
+          { width: COMPONENT_WIDTH, height: COMPONENT_HEIGHT }
+        else
+          { width: SYSTEM_WIDTH, height: SYSTEM_HEIGHT }
+        end
+      end
+
+      def calculate_boundary_dimensions(children)
+        return { width: 300, height: 200 } if children.empty?
+
+        # Calculate based on child count and type
+        # Simple heuristic: arrange in grid
+        count = children.length
+        cols = Math.sqrt(count).ceil
+        rows = (count.to_f / cols).ceil
+
+        max_width = children.map { |c| c[:width] || 160 }.max
+        max_height = children.map { |c| c[:height] || 120 }.max
+
+        width = (cols * max_width) + ((cols + 1) * ELEMENT_SPACING) +
+                (2 * BOUNDARY_PADDING)
+        height = (rows * max_height) + ((rows + 1) * ELEMENT_SPACING) +
+                 (2 * BOUNDARY_PADDING) + 30 # Extra for title
+
+        { width: [width, 300].max, height: [height, 200].max }
+      end
+
+      def layout_options(diagram)
+        # C4 diagrams use hierarchical layout
+        # Top-down for Context/Container, can be left-right for Component
+        direction = case diagram.level
+                    when 'Component', 'Code'
+                      DIRECTION_RIGHT
+                    else
+                      DIRECTION_DOWN
+                    end
+
+        build_elk_options(
+          algorithm: ALGORITHM_LAYERED,
+          direction: direction,
+          ElkOptions::NODE_NODE_SPACING => ELEMENT_SPACING,
+          ElkOptions::LAYER_SPACING => LEVEL_SPACING,
+          ElkOptions::EDGE_NODE_SPACING => 25,
+          ElkOptions::EDGE_EDGE_SPACING => 20,
+          ElkOptions::HIERARCHY_HANDLING => 'INCLUDE_CHILDREN',
+          ElkOptions::NODE_PLACEMENT => 'NETWORK_SIMPLEX'
+        )
+      end
+
+      def boundary_layout_options
+        # Boundaries use box packing for internal layout
+        {
+          'elk.algorithm' => 'box',
+          'elk.box.packingMode' => 'GROUP_MIXED',
+          'elk.padding' => "[top=#{BOUNDARY_PADDING},left=#{BOUNDARY_PADDING}," \
+                          "bottom=#{BOUNDARY_PADDING},right=#{BOUNDARY_PADDING}]",
+          'elk.spacing.nodeNode' => ELEMENT_SPACING.to_s
+        }
+      end
+    end
+  end
+end