elkrb 1.0.2 → 2.0.0

data/lib/elkrb/layout/algorithms/layered/cycle_breaker.rb

@@ -1,83 +1,152 @@
 # frozen_string_literal: true
 
+# This file is loadable on its own, so do not rely on another algorithm
+# having loaded Ruby's Set first.
+# rubocop:disable Lint/RedundantRequireStatement
+require "set"
+# rubocop:enable Lint/RedundantRequireStatement
+
 module Elkrb
   module Layout
     module Algorithms
       module Layered
-        # Breaks cycles in the graph to make it acyclic
+        # Finds back edges without changing the graph supplied by the caller.
+        # The returned EDGES are consumed by LayerAssigner to orient each one
+        # only while calculating layers.
+        #
+        # The set holds the edge OBJECTS and compares by identity, not their
+        # ids. An id is optional on an edge, so keying by id gave every
+        # id-less edge in the graph the same handle: reverse one of them and
+        # LayerAssigner reversed all of them. Identity is the only handle
+        # every edge has. A PLAIN Set is not enough either -- lutaml-model
+        # gives these classes VALUE equality, so two distinct edges whose
+        # attributes ALL match, id and endpoints alike, are `==`, hash
+        # alike, and collapse into one entry. Differing ids are enough to
+        # keep them apart in a plain Set; two anonymous parallel edges are
+        # not.
         #
-        # This is the first phase of the Sugiyama framework.
-        # Uses a greedy approach to reverse edges that create cycles.
+        # `outgoing_edges` still walks every source against every target,
+        # even though LayeredAlgorithm#validate_simple_edge! now rejects any
+        # edge that isn't exactly one source and one target before this class
+        # is ever constructed -- so today that cross product is always over
+        # arrays of length 0 or 1. Kept general on purpose, unlike
+        # LayerAssigner#endpoint_owner_id (singular, .first-based): this
+        # class is unit-tested directly with hyperedge-shaped input
+        # (cycle_breaker_spec.rb), and narrowing it to the current caller's
+        # guarantee would make it correct only through that one caller.
         class CycleBreaker
-          def initialize(graph)
+          def initialize(graph, index)
             @graph = graph
-            @visited = {}
-            @in_stack = {}
-            @edges_to_reverse = []
+            @index = index
           end
 
           def break_cycles
-            return unless @graph.children
+            reversed = Set.new.compare_by_identity
+            return reversed unless @graph.children
+
+            adjacency = outgoing_edges
+            colors = {}
 
-            # Find all edges that create cycles using DFS
             @graph.children.each do |node|
-              dfs(node) unless @visited[node.id]
+              # keep this `colors[node.id]` truthiness check, even though
+              # `colors.key?(node.id)` reads identically: every value ever
+              # stored in `colors` is `:active` or `:complete`, both
+              # truthy, and nothing ever stores a falsy value under a key
+              # -- so "has a value" and "has a truthy value" can never
+              # diverge for this hash. Confirmed by hand: swapping in
+              # `colors.key?(node.id)` leaves the whole suite green.
+              next if colors[node.id]
+
+              walk_from(node.id, adjacency, colors, reversed)
             end
 
-            # Reverse the problematic edges
-            reverse_edges
-
-            @edges_to_reverse
+            reversed
           end
 
           private
 
-          def dfs(node)
-            @visited[node.id] = true
-            @in_stack[node.id] = true
-
-            # Process outgoing edges
-            get_outgoing_edges(node).each do |edge|
-              target_id = edge.targets.first
-              next unless target_id
-
-              target = @graph.find_node(target_id)
-              next unless target
-
-              if @in_stack[target.id]
-                # Found a cycle - mark this edge for reversal
-                @edges_to_reverse << edge
-              elsif !@visited[target.id]
-                dfs(target)
+          # Every mutant mutant finds in this method is equivalent, confirmed
+          # by hand (each one individually applied, whole suite still
+          # green) -- they all fall into two classes:
+          #   - `stack[-1]`, `edges[edge_index]`: `Array#[]` with a single
+          #     Integer index reads identically to `#at` and, since the
+          #     `if` just above always holds `edge_index` in bounds before
+          #     either line runs, identically to `#fetch` too.
+          #   - `edge_index >= edges.length`, `next`, and the exact
+          #     `:complete` symbol: `edge_index` only ever grows by
+          #     `frame[1] = edge_index + 1` and is re-checked every pass
+          #     before it can grow again, so it can equal `edges.length`
+          #     but never exceed it -- making `>=`, `==`, `eql?` and
+          #     `equal?` the same test here, and `colors` is a local
+          #     consumed only by `== :active` / nil checks (never a
+          #     specific "is it :complete" check, never read outside this
+          #     method), so renaming that value or falling through `next`
+          #     onto a redundant `edges[edge_index]` read changes nothing
+          #     reachable from `reversed`, the one value this method hands
+          #     back out.
+          def walk_from(root_id, adjacency, colors, reversed)
+            colors[root_id] = :active
+            stack = [[root_id, 0]]
+
+            until stack.empty?
+              frame = stack[-1]
+              current_id, edge_index = frame
+              edges = adjacency[current_id]
+
+              if edge_index >= edges.length
+                colors[current_id] = :complete
+                stack.pop
+                next
               end
+
+              target_id, edge = edges[edge_index]
+              frame[1] = edge_index + 1
+              visit_target(target_id, edge, stack, colors, reversed)
             end
+          end
 
-            @in_stack[node.id] = false
+          def visit_target(target_id, edge, stack, colors, reversed)
+            case colors[target_id]
+            when :active
+              reversed << edge
+            when nil
+              colors[target_id] = :active
+              stack << [target_id, 0]
+            end
           end
 
-          def get_outgoing_edges(node)
-            edges = []
+          def outgoing_edges
+            adjacency = Hash.new { |hash, id| hash[id] = [] }
+
+            @index.edges.each do |edge|
+              source_ids = endpoint_owner_ids(edge.sources)
+              target_ids = endpoint_owner_ids(edge.targets)
 
-            # Get edges from the node itself
-            edges.concat(node.edges) if node.edges
+              source_ids.each do |source_id|
+                target_ids.each do |target_id|
+                  next if source_id == target_id
 
-            # Get edges from the graph that have this node as source
-            @graph.edges&.each do |edge|
-              edges << edge if edge.sources&.include?(node.id)
+                  adjacency[source_id] << [target_id, edge]
+                end
+              end
             end
 
-            edges
+            adjacency
           end
 
-          def reverse_edges
-            @edges_to_reverse.each do |edge|
-              # Swap sources and targets
-              edge.sources, edge.targets = edge.targets, edge.sources
-
-              # Mark as reversed for later processing
-              edge.properties ||= {}
-              edge.properties["reversed"] = true
-            end
+          def endpoint_owner_ids(endpoints)
+            (endpoints || []).filter_map do |id|
+              # keep the `if id` guard even though `@index.owner(nil)` is
+              # itself nil-safe (NodeIndex#owner is `node(id) ||
+              # @owners_by_descendant_id[id]`, and a Hash lookup of a nil
+              # key that was never stored just answers nil) -- so for the
+              # one falsy id this array can ever hold, skipping the call
+              # and calling it unconditionally land on the identical nil.
+              # Confirmed by hand: forcing this branch to always run
+              # leaves the whole suite green.
+              owner = @index.owner(id) if id
+              owner&.id
+            end.uniq
           end
         end
       end

data/lib/elkrb/layout/algorithms/layered/discovery_order.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # The order ELK lists a connected graph's nodes in: a depth-first walk
+        # from the first node, following each node's edges in the order the
+        # importer created them. Every layer starts out in that order, and it
+        # decides which of two equally good orders the sweep keeps.
+        class DiscoveryOrder
+          # @param graph [Graph::Node] the graph whose children are layered
+          # @param index [NodeIndex, nil] resolves edge endpoints to nodes
+          def initialize(graph, index)
+            @children = graph.children || []
+            @neighbours = neighbours(index)
+          end
+
+          # Reorders each layer in place; dummy slots keep their place at the
+          # end.
+          def sort(layers)
+            ranks = discover
+            layers.each do |layer|
+              layer.replace(layer.each_with_index.sort_by do |item, position|
+                [ranks.fetch(item.id, ranks.length), position]
+              end.map(&:first))
+            end
+          end
+
+          private
+
+          def discover
+            ranks = {}
+            @children.each { |child| walk(child.id, ranks) }
+            ranks
+          end
+
+          def walk(root, ranks)
+            return if ranks.key?(root)
+
+            pending = [[root]]
+            until pending.empty?
+              found = pending.last.shift
+              next pending.pop unless found
+              next if ranks.key?(found)
+
+              ranks[found] = ranks.length
+              pending.push(@neighbours.fetch(found).dup)
+            end
+          end
+
+          def neighbours(index)
+            table = @children.to_h { |child| [child.id, []] }
+            index&.edges&.each do |edge|
+              link(table, owner_id(index, edge.sources),
+                   owner_id(index, edge.targets))
+            end
+            table
+          end
+
+          def owner_id(index, endpoints)
+            index.owner(endpoints&.first)&.id
+          end
+
+          def link(table, source, target)
+            return unless table.key?(source) && table.key?(target)
+
+            table[source] << target
+            table[target] << source
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/layered/dummy_slot.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # Internal layer position reserved for one segment of a long edge.
+        class DummySlot
+          attr_accessor :x, :y, :width, :height
+          attr_reader :edge, :edge_id, :layer_index, :edge_order, :id
+
+          def initialize(edge:, layer_index:, edge_order:)
+            @edge = edge
+            @edge_id = edge.id
+            @layer_index = layer_index
+            @edge_order = edge_order
+            @id = "__elkrb_dummy_#{edge_order}_#{layer_index}"
+            @x = 0.0
+            @y = 0.0
+            @width = 0.0
+            @height = 0.0
+          end
+
+          def dummy?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/layered/layer_assigner.rb

@@ -1,18 +1,46 @@
 # frozen_string_literal: true
 
+# This file is loadable on its own, so do not rely on another algorithm
+# having loaded Ruby's Set first.
+# rubocop:disable Lint/RedundantRequireStatement
+require "set"
+# rubocop:enable Lint/RedundantRequireStatement
+require_relative "dummy_slot"
+
+require_relative "../../../options/resolver"
+require_relative "layer_constraints"
+
 module Elkrb
   module Layout
     module Algorithms
       module Layered
-        # Assigns nodes to layers in the graph
-        #
-        # This is the second phase of the Sugiyama framework.
-        # Uses longest path layering to create a balanced layout.
+        # Assigns nodes to layers using an iterative longest-path pass, then
+        # applies layer constraints: `elk.layered.layering.layerConstraint`
+        # (FIRST, FIRST_SEPARATE, LAST, LAST_SEPARATE) and
+        # `constraints.layer`. A constraint wins over the edges, so an edge
+        # may end up pointing against the layer order.
         class LayerAssigner
           attr_reader :layers
 
-          def initialize(graph)
+          # `reversed_edges` holds the edge OBJECTS CycleBreaker decided to
+          # orient backwards, compared by identity. See CycleBreaker for why
+          # neither an id nor a plain Set can carry that decision.
+          #
+          # keep this `compare_by_identity` on the DEFAULT too, even though
+          # nothing in this codebase can observe it today: the default is
+          # only ever read via #include? and never added to, and an empty
+          # Set answers #include? identically whichever comparison strategy
+          # it uses -- so no spec can distinguish this from a plain
+          # `Set.new` (confirmed by mutating it by hand). It becomes the
+          # only thing standing between a dedup bug and a direct caller
+          # that relies on the default AND later mutates it in place.
+          def initialize(graph, index,
+                         reversed_edges = Set.new.compare_by_identity,
+                         resolver: Options::Resolver.new)
             @graph = graph
+            @resolver = resolver
+            @index = index
+            @reversed_edges = reversed_edges
             @layers = []
             @node_layers = {}
           end
@@ -20,20 +48,12 @@ module Elkrb
           def assign_layers
             return [] unless @graph.children
 
-            # Calculate layer for each node
-            @graph.children.each do |node|
-              calculate_layer(node)
-            end
-
-            # Group nodes by layer
-            max_layer = @node_layers.values.max || 0
-            @layers = Array.new(max_layer + 1) { [] }
-
-            @node_layers.each do |node_id, layer|
-              node = @graph.find_node(node_id)
-              @layers[layer] << node if node
-            end
-
+            nodes = @graph.children.to_h { |node| [node.id, node] }
+            predecessors = build_predecessors(nodes)
+            assign_predecessor_layers(nodes, predecessors)
+            apply_layer_constraints(nodes)
+            build_layers(nodes)
+            insert_dummy_slots
             @layers
           end
 
@@ -43,51 +63,171 @@ module Elkrb
 
           private
 
-          def calculate_layer(node)
-            return @node_layers[node.id] if @node_layers.key?(node.id)
+          # Keep the predecessor order used by the former recursive pass.
+          # That order is observable in NodePlacer's same-layer coordinates,
+          # so an acyclic graph must not be reordered as a side effect of the
+          # iterative implementation.
+          def build_predecessors(nodes)
+            predecessors = Hash.new { |hash, id| hash[id] = [] }
 
-            # Find incoming edges
-            incoming = get_incoming_edges(node)
+            @index.edges.each do |edge|
+              source_id, target_id = oriented_endpoints(edge)
+              next unless usable_edge?(source_id, target_id, nodes)
 
-            if incoming.empty?
-              # Root node - assign to layer 0
-              @node_layers[node.id] = 0
-            else
-              # Assign to one layer below the maximum of predecessors
-              max_pred_layer = incoming.filter_map do |edge|
-                source_id = edge.sources.first
-                next 0 unless source_id
+              predecessors[target_id] << source_id
+            end
 
-                source = @graph.find_node(source_id)
-                next 0 unless source
+            predecessors
+          end
+
+          # Iterative post-order traversal of each node's predecessors. This
+          # is the stack-safe equivalent of the original memoised recursive
+          # longest-path calculation and preserves its insertion order.
+          def assign_predecessor_layers(nodes, predecessors)
+            @node_layers = {}
+            colors = {}
+
+            nodes.each_key do |node_id|
+              next if @node_layers.key?(node_id)
+
+              walk_predecessors(node_id, predecessors, colors)
+            end
+          end
+
+          def walk_predecessors(root_id, predecessors, colors)
+            colors[root_id] = :active
+            stack = [[root_id, 0]]
 
-                calculate_layer(source)
-              end.max || 0
+            until stack.empty?
+              step_predecessor_stack(stack, predecessors, colors)
+            end
+          end
 
-              @node_layers[node.id] = max_pred_layer + 1
+          def step_predecessor_stack(stack, predecessors, colors)
+            # `stack[-1]` and `stack.at(-1)` are the same Array call with a
+            # single integer index -- no spec can tell them apart, and
+            # mutant flags the swap as a surviving mutation every run.
+            # Equivalent mutant, not a coverage gap.
+            frame = stack[-1]
+            current_id, predecessor_index = frame
+            incoming = predecessors[current_id]
+
+            if predecessor_index >= incoming.length
+              finish_predecessor_frame(stack, current_id, incoming, colors)
+              return
             end
 
-            @node_layers[node.id]
+            predecessor_id = incoming[predecessor_index]
+            frame[1] = predecessor_index + 1
+            return if predecessor_assigned?(predecessor_id, colors)
+
+            colors[predecessor_id] = :active
+            stack << [predecessor_id, 0]
           end
 
-          def get_incoming_edges(node)
-            edges = []
+          def finish_predecessor_frame(stack, node_id, incoming, colors)
+            assign_layer(node_id, incoming)
+            # keep this write even though `colors` is only ever read with
+            # `== :active` in predecessor_assigned?, which checks
+            # @node_layers.key?(node_id) FIRST and returns true before it
+            # would ever read :complete here -- assign_layer above always
+            # runs first, so by the time anything could read this node's
+            # color, the key-check has already short-circuited. Confirmed
+            # by hand: removing this line changes nothing observable. It
+            # becomes load-bearing only if that ordering, or the
+            # :active-only read in predecessor_assigned?, ever changes.
+            colors[node_id] = :complete
+            stack.pop
+          end
 
-            # Get all edges that target this node
-            @graph.edges&.each do |edge|
-              edges << edge if edge.targets&.include?(node.id)
+          # False here is the ordinary case: predecessor_id hasn't been
+          # visited by an earlier root yet, so the caller descends into it
+          # next. True from the :active check is the defensive case --
+          # CycleBreaker orients every back edge away from the active DFS
+          # path, so through the real pipeline this branch never fires; it
+          # guards a direct caller of LayerAssigner that supplies an
+          # incomplete reversal set. Warn there specifically (not on the
+          # plain-revisit case above it): silently proceeding is what
+          # dropped a diagnostic this class used to print for exactly that
+          # misuse.
+          def predecessor_assigned?(predecessor_id, colors)
+            return true if @node_layers.key?(predecessor_id)
+            return false unless colors[predecessor_id] == :active
+
+            warn "LayerAssigner: cycle through #{predecessor_id} not " \
+                 "fully broken; treating as a root for this branch"
+            true
+          end
+
+          def assign_layer(node_id, incoming)
+            max_predecessor_layer = incoming.filter_map do |predecessor_id|
+              @node_layers[predecessor_id]
+            end.max
+
+            @node_layers[node_id] =
+              if max_predecessor_layer
+                max_predecessor_layer + 1
+              else
+                0
+              end
+          end
+
+          def apply_layer_constraints(nodes)
+            LayerConstraints.new(nodes, @node_layers, @resolver).apply
+          end
+
+          def build_layers(nodes)
+            max_layer = @node_layers.values.max || 0
+            @layers = Array.new(max_layer + 1) { [] }
+            @node_layers.each do |node_id, layer|
+              @layers[layer] << nodes[node_id]
             end
 
-            # Also check edges from other nodes
-            @graph.children&.each do |other_node|
-              next unless other_node.edges
+            @layers
+          end
 
-              other_node.edges.each do |edge|
-                edges << edge if edge.targets&.include?(node.id)
+          def insert_dummy_slots
+            @index.edges.each_with_index do |edge, edge_order|
+              source_id, target_id = oriented_endpoints(edge)
+              source_layer = @node_layers[source_id]
+              target_layer = @node_layers[target_id]
+              next unless source_layer && target_layer
+              next unless (source_layer - target_layer).abs > 1
+
+              intermediate_layers(source_layer, target_layer).each do |layer|
+                @layers[layer] << DummySlot.new(
+                  edge: edge, layer_index: layer, edge_order: edge_order,
+                )
               end
             end
+          end
+
+          def intermediate_layers(source_layer, target_layer)
+            low, high = [source_layer, target_layer].minmax
+            ((low + 1)...high).to_a
+          end
+
+          def usable_edge?(source_id, target_id, nodes)
+            source_id && target_id && source_id != target_id &&
+              nodes.key?(source_id) && nodes.key?(target_id)
+          end
+
+          def oriented_endpoints(edge)
+            source_id = endpoint_owner_id(edge.sources)
+            target_id = endpoint_owner_id(edge.targets)
+            return [nil, nil] unless source_id && target_id
+
+            if @reversed_edges.include?(edge)
+              [target_id, source_id]
+            else
+              [source_id, target_id]
+            end
+          end
 
-            edges
+          def endpoint_owner_id(endpoints)
+            id = (endpoints || []).first
+            owner = @index.owner(id) if id
+            owner&.id
           end
         end
       end

data/lib/elkrb/layout/algorithms/layered/layer_constraints.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # Moves nodes to the layers their constraints ask for, after the
+        # longest-path pass has assigned every node a layer.
+        #
+        # `elk.layered.layering.layerConstraint` puts a node first or last:
+        # FIRST and LAST share a layer with other nodes, FIRST_SEPARATE and
+        # LAST_SEPARATE get a layer of their own. `constraints.layer` is an
+        # explicit layer index, applied last, so it wins over the option.
+        # Both override the edges.
+        class LayerConstraints
+          OPTION = "elk.layered.layering.layerConstraint"
+
+          # @param nodes [Hash{String => Graph::Node}] the nodes by id
+          # @param node_layers [Hash{String => Integer}] layer by node id,
+          #   updated in place
+          # @param resolver [Options::Resolver]
+          def initialize(nodes, node_layers, resolver)
+            @nodes = nodes
+            @layers = node_layers
+            @kinds = nodes.transform_values do |node|
+              resolver.get(OPTION, node)
+            end
+          end
+
+          def apply
+            place_by_kind
+            place_by_index
+          end
+
+          private
+
+          def ids_of(kind)
+            @kinds.select { |_id, value| value == kind }.keys
+          end
+
+          def place_by_kind
+            first_separate = ids_of("FIRST_SEPARATE")
+            last_separate = ids_of("LAST_SEPARATE")
+            first_layer = first_separate.empty? ? 0 : 1
+
+            shift(@nodes.keys - first_separate - last_separate, first_layer)
+            set(ids_of("FIRST"), first_layer)
+            set(first_separate, 0)
+
+            place_last(last_separate, first_layer)
+          end
+
+          def place_last(last_separate, fallback)
+            last_layer = last_movable_layer(last_separate, fallback)
+            set(ids_of("LAST"), last_layer)
+            set(last_separate, last_layer + 1)
+          end
+
+          def last_movable_layer(last_separate, fallback)
+            movable = @nodes.keys - last_separate - ids_of("LAST")
+            @layers.values_at(*movable).max || fallback
+          end
+
+          def place_by_index
+            @nodes.each do |id, node|
+              index = node.constraints&.layer
+              @layers[id] = [index, 0].max if index
+            end
+          end
+
+          def shift(ids, by)
+            ids.each { |id| @layers[id] += by }
+          end
+
+          def set(ids, layer)
+            ids.each { |id| @layers[id] = layer }
+          end
+        end
+      end
+    end
+  end
+end