elkrb 1.0.0

data/lib/elkrb/graph/port.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Elkrb
+  module Graph
+    class Port < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :x, :float
+      attribute :y, :float
+      attribute :width, :float
+      attribute :height, :float
+      attribute :labels, Label, collection: true
+      attribute :layout_options, LayoutOptions
+      attribute :properties, :hash
+      attribute :side, :string, default: -> { "UNDEFINED" }
+      attribute :index, :integer, default: -> { -1 }
+      attribute :offset, :float, default: -> { 0.0 }
+
+      # Port sides
+      NORTH = "NORTH"
+      SOUTH = "SOUTH"
+      EAST = "EAST"
+      WEST = "WEST"
+      UNDEFINED = "UNDEFINED"
+
+      SIDES = [NORTH, SOUTH, EAST, WEST, UNDEFINED].freeze
+
+      # Node reference (not serialized)
+      attr_accessor :node
+
+      json do
+        map "id", to: :id
+        map "x", to: :x
+        map "y", to: :y
+        map "width", to: :width
+        map "height", to: :height
+        map "labels", to: :labels
+        map "layoutOptions", to: :layout_options
+        map "properties", to: :properties
+        map "side", to: :side
+        map "index", to: :index
+        map "offset", to: :offset
+      end
+
+      yaml do
+        map "id", to: :id
+        map "x", to: :x
+        map "y", to: :y
+        map "width", to: :width
+        map "height", to: :height
+        map "labels", to: :labels
+        map "layout_options", to: :layout_options
+        map "properties", to: :properties
+        map "side", to: :side
+        map "index", to: :index
+        map "offset", to: :offset
+      end
+
+      # Validate and set port side
+      #
+      # @param value [String] The port side (NORTH, SOUTH, EAST, WEST, UNDEFINED)
+      # @raise [ArgumentError] If the side value is invalid
+      def side=(value)
+        return if value.nil?
+
+        normalized = value.to_s.upcase
+        unless SIDES.include?(normalized)
+          raise ArgumentError,
+                "Invalid port side: #{value}. Must be one of #{SIDES.join(', ')}"
+        end
+        @side = normalized
+      end
+
+      # Detect port side from position relative to node
+      #
+      # This method analyzes the port's position (x, y) relative to the node's
+      # dimensions to determine which side of the node the port is closest to.
+      #
+      # @param node_width [Float] Width of the parent node
+      # @param node_height [Float] Height of the parent node
+      # @return [String] The detected side (NORTH, SOUTH, EAST, WEST, UNDEFINED)
+      def detect_side(node_width, node_height)
+        return UNDEFINED if x.nil? || y.nil? || node_width.nil? || node_height.nil?
+        return UNDEFINED if node_width <= 0 || node_height <= 0
+
+        # Calculate relative position (0.0 to 1.0)
+        rel_x = x / node_width.to_f
+        rel_y = y / node_height.to_f
+
+        # Calculate distance to each side
+        distances = {
+          NORTH => rel_y,           # Distance from top
+          SOUTH => 1.0 - rel_y,     # Distance from bottom
+          WEST => rel_x,            # Distance from left
+          EAST => 1.0 - rel_x, # Distance from right
+        }
+
+        # Return the side with minimum distance
+        distances.min_by { |_, dist| dist }.first
+      end
+    end
+  end
+end

data/lib/elkrb/graphviz_wrapper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Elkrb
+  # Wrapper for optional Graphviz integration
+  # Provides graceful degradation when Graphviz is not installed
+  class GraphvizWrapper
+    class GraphvizNotFoundError < StandardError; end
+
+    SUPPORTED_FORMATS = %i[png svg pdf ps eps].freeze
+    SUPPORTED_ENGINES = %w[dot neato fdp sfdp twopi circo].freeze
+
+    def initialize
+      @dot_path = find_graphviz
+    end
+
+    def available?
+      !@dot_path.nil?
+    end
+
+    def render(dot_file, output_file, format, options = {})
+      raise GraphvizNotFoundError, installation_message unless available?
+
+      validate_format!(format)
+      validate_file_exists!(dot_file)
+
+      engine = options[:engine] || "dot"
+      validate_engine!(engine)
+
+      dpi = options[:dpi] || 96
+
+      cmd = build_command(engine, format, dot_file, output_file, dpi)
+      execute_command(cmd)
+    end
+
+    def version
+      return nil unless available?
+
+      output = `#{@dot_path} -V 2>&1`
+      output.match(/version\s+([\d.]+)/i)&.captures&.first
+    end
+
+    def supported_formats
+      SUPPORTED_FORMATS
+    end
+
+    def supported_engines
+      SUPPORTED_ENGINES
+    end
+
+    private
+
+    def find_graphviz
+      # Try common locations
+      candidates = [
+        "dot",
+        "/usr/bin/dot",
+        "/usr/local/bin/dot",
+        "/opt/homebrew/bin/dot",
+        "/opt/local/bin/dot",
+      ]
+
+      candidates.each do |path|
+        if File.executable?(path)
+          return path
+        elsif system("which #{path} > /dev/null 2>&1")
+          return path
+        end
+      end
+
+      nil
+    end
+
+    def build_command(engine, format, input_file, output_file, dpi)
+      cmd_parts = [
+        @dot_path,
+        "-K#{engine}",
+        "-T#{format}",
+        "-Gdpi=#{dpi}",
+      ]
+
+      cmd_parts << "-o#{output_file}" if output_file
+      cmd_parts << input_file
+
+      cmd_parts.join(" ")
+    end
+
+    def execute_command(cmd)
+      success = system(cmd)
+      unless success
+        raise GraphvizNotFoundError,
+              "Graphviz command failed: #{cmd}"
+      end
+
+      success
+    end
+
+    def validate_format!(format)
+      format_sym = format.to_sym
+      return if SUPPORTED_FORMATS.include?(format_sym)
+
+      raise ArgumentError, "Unsupported format: #{format}. " \
+                           "Supported formats: #{SUPPORTED_FORMATS.join(', ')}"
+    end
+
+    def validate_engine!(engine)
+      return if SUPPORTED_ENGINES.include?(engine.to_s)
+
+      raise ArgumentError, "Unsupported engine: #{engine}. " \
+                           "Supported engines: #{SUPPORTED_ENGINES.join(', ')}"
+    end
+
+    def validate_file_exists!(file)
+      return if File.exist?(file)
+
+      raise ArgumentError, "Input file not found: #{file}"
+    end
+
+    def installation_message
+      <<~MSG
+        Graphviz is required but not found.
+
+        Installation instructions:
+          macOS:   brew install graphviz
+          Ubuntu:  sudo apt-get install graphviz
+          Fedora:  sudo dnf install graphviz
+          Windows: https://graphviz.org/download/
+
+        Alternatively, export to DOT format and render manually:
+          elkrb diagram input.json -o output.dot
+      MSG
+    end
+  end
+end

data/lib/elkrb/layout/algorithm_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    class AlgorithmRegistry
+      @algorithms = {}
+      @metadata = {}
+
+      class << self
+        def register(name, algorithm_class, metadata = {})
+          name_str = name.to_s
+          @algorithms[name_str] = algorithm_class
+          @metadata[name_str] = metadata
+        end
+
+        def get(name)
+          algorithm_name = normalize_name(name)
+          @algorithms[algorithm_name]
+        end
+
+        def available_algorithms
+          @algorithms.keys.sort
+        end
+
+        def algorithm_info(name)
+          algorithm_class = get(name)
+          return nil unless algorithm_class
+
+          name_str = normalize_name(name)
+          metadata = @metadata[name_str] || {}
+
+          {
+            id: name_str,
+            name: metadata[:name] || name_str.capitalize,
+            description: metadata[:description] || "",
+            category: metadata[:category] || "general",
+            supports_hierarchy: metadata[:supports_hierarchy] || false,
+          }
+        end
+
+        def all_algorithm_info
+          available_algorithms.map { |name| algorithm_info(name) }
+        end
+
+        private
+
+        def normalize_name(name)
+          # Support both full names and short names
+          # e.g., "org.eclipse.elk.layered" -> "layered"
+          name = name.to_s
+          name = name.split(".").last if name.include?(".")
+          name.downcase
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/base_algorithm.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../edge_router"
+require_relative "../hierarchical_processor"
+require_relative "../label_placer"
+require_relative "../port_constraint_processor"
+require_relative "../constraints/constraint_processor"
+
+module Elkrb
+  module Layout
+    module Algorithms
+      # Base class for all layout algorithms
+      #
+      # Layout algorithms are responsible for computing positions for nodes
+      # and routing paths for edges in a graph. Each algorithm implements
+      # a specific layout strategy (e.g., hierarchical, force-directed, etc.)
+      class BaseAlgorithm
+        include EdgeRouter
+        include HierarchicalProcessor
+        include LabelPlacer
+        include PortConstraintProcessor
+
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options
+        end
+
+        # Main layout method - automatically handles hierarchical graphs and labels
+        #
+        # Subclasses should implement #layout_flat for their specific
+        # algorithm logic. This method will automatically handle hierarchical
+        # graphs by calling layout_hierarchical when needed, and place labels
+        # after layout is complete.
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph to layout
+        # @return [Elkrb::Graph::Graph] The graph with updated positions
+        def layout(graph)
+          # Apply port constraints before layout
+          apply_port_constraints(graph)
+
+          # Apply pre-layout constraints (marks nodes)
+          apply_pre_layout_constraints(graph)
+
+          # Perform layout
+          if option("hierarchical", false) || graph.hierarchical?
+            layout_hierarchical(graph, @options)
+          else
+            layout_flat(graph, @options)
+          end
+
+          # Enforce post-layout constraints (adjust positions)
+          enforce_post_layout_constraints(graph)
+
+          # Apply edge routing
+          apply_edge_routing(graph)
+
+          # Place labels after layout (unless disabled)
+          unless option("label.placement.disabled", false)
+            place_labels(graph)
+          end
+
+          graph
+        end
+
+        # Layout a flat (non-hierarchical) graph
+        #
+        # This method must be implemented by subclasses with their specific
+        # layout algorithm logic.
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph to layout
+        # @param options [Hash] Layout options
+        # @return [Elkrb::Graph::Graph] The graph with updated positions
+        def layout_flat(graph, options = {})
+          raise NotImplementedError,
+                "#{self.class.name} must implement #layout_flat method"
+        end
+
+        protected
+
+        # Get an option value with a default fallback
+        #
+        # @param key [String, Symbol] The option key
+        # @param default [Object] The default value if option is not set
+        # @return [Object] The option value or default
+        def option(key, default = nil)
+          key_str = key.to_s
+          @options[key_str] || @options[key.to_sym] || default
+        end
+
+        # Get spacing between nodes
+        #
+        # @return [Float] The node spacing value
+        def node_spacing
+          option("spacing_node_node", 20.0).to_f
+        end
+
+        # Get padding values
+        #
+        # @return [Hash] Padding values for top, bottom, left, right
+        def padding
+          default_padding = { top: 12, bottom: 12, left: 12, right: 12 }
+          padding_opt = option("padding", default_padding)
+
+          if padding_opt.is_a?(Hash)
+            default_padding.merge(padding_opt)
+          else
+            default_padding
+          end
+        end
+
+        # Calculate the bounding box for a set of nodes
+        #
+        # @param nodes [Array<Elkrb::Graph::Node>] The nodes
+        # @return [Elkrb::Geometry::Rectangle] The bounding rectangle
+        def calculate_bounding_box(nodes)
+          return Elkrb::Geometry::Rectangle.new(0, 0, 0, 0) if nodes.empty?
+
+          min_x = nodes.map(&:x).min
+          min_y = nodes.map(&:y).min
+          max_x = nodes.map { |n| n.x + n.width }.max
+          max_y = nodes.map { |n| n.y + n.height }.max
+
+          Elkrb::Geometry::Rectangle.new(
+            min_x,
+            min_y,
+            max_x - min_x,
+            max_y - min_y,
+          )
+        end
+
+        # Apply padding to graph dimensions
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph
+        def apply_padding(graph)
+          return if graph.children.nil? || graph.children.empty?
+
+          pad = padding
+          bbox = calculate_bounding_box(graph.children)
+
+          # Shift all nodes by padding
+          graph.children.each do |node|
+            node.x = node.x - bbox.x + pad[:left]
+            node.y = node.y - bbox.y + pad[:top]
+          end
+
+          # Set graph dimensions
+          graph.width = bbox.width + pad[:left] + pad[:right]
+          graph.height = bbox.height + pad[:top] + pad[:bottom]
+        end
+
+        # Apply edge routing based on routing style option
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph
+        def apply_edge_routing(graph)
+          routing_style = get_edge_routing_style(graph)
+          route_edges(graph, nil, routing_style)
+        end
+
+        # Get edge routing style from graph options
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph
+        # @return [String] Routing style (ORTHOGONAL, POLYLINE, SPLINES)
+        def get_edge_routing_style(graph)
+          return "ORTHOGONAL" unless graph.layout_options
+
+          style = graph.layout_options["elk.edgeRouting"] ||
+            graph.layout_options["edgeRouting"] ||
+            graph.layout_options.edge_routing ||
+            option("elk.edgeRouting") ||
+            option("edgeRouting")
+
+          style ? style.to_s.upcase : "ORTHOGONAL"
+        end
+
+        # Apply pre-layout constraints
+        #
+        # These constraints mark nodes for special algorithm handling.
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph
+        def apply_pre_layout_constraints(graph)
+          processor = Constraints::ConstraintProcessor.new
+          processor.apply_pre_layout(graph)
+        end
+
+        # Enforce post-layout constraints
+        #
+        # These constraints adjust positions after layout algorithm runs.
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph
+        def enforce_post_layout_constraints(graph)
+          processor = Constraints::ConstraintProcessor.new
+          processor.enforce_post_layout(graph)
+
+          # Validate all constraints
+          errors = processor.validate_all(graph)
+
+          return if errors.empty?
+
+          # Log warnings for constraint violations
+          errors.each do |error|
+            warn "Layout constraint violation: #{error}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/box.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base_algorithm"
+
+module Elkrb
+  module Layout
+    module Algorithms
+      # Box layout algorithm
+      #
+      # Arranges nodes in a simple box/grid pattern. Nodes are placed
+      # in rows from left to right, top to bottom, with uniform spacing.
+      # Useful for simple diagrams and quick visualization.
+      class Box < BaseAlgorithm
+        def layout_flat(graph, _options = {})
+          return graph if graph.children.nil? || graph.children.empty?
+
+          # Get configuration
+          aspect_ratio = option("aspect_ratio", 1.6).to_f
+          spacing = node_spacing
+
+          # Calculate number of columns based on aspect ratio
+          num_nodes = graph.children.length
+          cols = Math.sqrt(num_nodes * aspect_ratio).ceil
+          cols = [cols, 1].max
+
+          # Find maximum node dimensions for uniform grid
+          max_width = graph.children.map(&:width).max
+          max_height = graph.children.map(&:height).max
+
+          # Position nodes in grid
+          graph.children.each_with_index do |node, i|
+            row = i / cols
+            col = i % cols
+
+            node.x = col * (max_width + spacing)
+            node.y = row * (max_height + spacing)
+          end
+
+          # Apply padding and set graph dimensions
+          apply_padding(graph)
+
+          graph
+        end
+      end
+    end
+  end
+end