etassia 0.1.0

data/lib/etassia/layout/er_diagram_adjacency.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # The neighbours of every node in a chain of edges, in edge order.
+    class ErDiagramAdjacency
+      attr_reader :successors, :predecessors
+
+      # @param edges [Array<Array(String, String)>] [from, to] pairs
+      def initialize(edges)
+        @successors = Hash.new { |hash, key| hash[key] = [] }
+        @predecessors = Hash.new { |hash, key| hash[key] = [] }
+        edges.each do |from, to|
+          @successors[from] << to
+          @predecessors[to] << from
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_alignment.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # One vertical alignment of Brandes-Koepf: each node joins the block of
+    # its median neighbour in the rank before, unless that would cross
+    # another alignment or use a conflicted edge.
+    class ErDiagramAlignment
+      # @param neighbours [Hash{String=>Array<String>}] the ids in the
+      #   previous rank that each node may join
+      # @param conflicts [Hash] pairs that must not be joined
+      def initialize(neighbours, conflicts)
+        @neighbours = neighbours
+        @conflicts = conflicts
+      end
+
+      # @param layers [Array<Array<String>>] ids per rank, in sweep order
+      # @return [Hash{String=>String}] the block root of every node
+      def call(layers)
+        @root = {}
+        @align = {}
+        @position = {}
+        layers.each do |layer|
+          register(layer)
+          align_layer(layer)
+        end
+        @root
+      end
+
+      private
+
+      def register(layer)
+        layer.each_with_index do |id, index|
+          @root[id] = @align[id] = id
+          @position[id] = index
+        end
+      end
+
+      def align_layer(layer)
+        previous = -1
+        layer.each do |id|
+          candidates = @neighbours[id].sort_by { |other| @position[other] }
+          previous = join_median(id, candidates, previous)
+        end
+      end
+
+      def join_median(id, candidates, previous)
+        return previous if candidates.empty?
+
+        middle = (candidates.length - 1) / 2.0
+        (middle.floor..middle.ceil).each do |index|
+          other = candidates[index]
+          next unless joinable?(id, other, previous)
+
+          join(id, other)
+          previous = @position[other]
+        end
+        previous
+      end
+
+      def joinable?(id, other, previous)
+        @align[id] == id && previous < @position[other] &&
+          !@conflicts[[id, other]]
+      end
+
+      def join(id, other)
+        @align[other] = id
+        @align[id] = @root[id] = @root[other]
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_compaction.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Gives each block of aligned nodes its x: blocks keep their rank order
+    # and at least the separation apart, pushed left first and then back
+    # right as far as their neighbours allow.
+    class ErDiagramCompaction
+      # @param layers [Array<Array<String>>] ids per rank, in sweep order
+      # @param root [Hash{String=>String}] the block root of every node
+      # @param separation [#call] (left_id, right_id) => minimum distance
+      def initialize(layers, root, separation)
+        @layers = layers
+        @root = root
+        @separation = separation
+      end
+
+      # @return [Hash{String=>Numeric}] x of every node
+      def call
+        build_graph
+        positions = place_blocks
+        @root.transform_values { |block| positions[block] }
+      end
+
+      private
+
+      def build_graph
+        @incoming = Hash.new { |hash, block| hash[block] = {} }
+        @outgoing = Hash.new { |hash, block| hash[block] = {} }
+        @layers.each { |layer| add_layer(layer) }
+      end
+
+      def add_layer(layer)
+        layer.each_cons(2) { |left, right| link(left, right) }
+        layer.each { |id| declare(@root[id]) }
+      end
+
+      # Looking a block up adds it to both graphs, so blocks with no
+      # neighbour in their rank still get placed.
+      def declare(block)
+        [@incoming, @outgoing].each { |graph| graph[block] }
+      end
+
+      def link(left, right)
+        from = @root[left]
+        to = @root[right]
+        gap = [@separation.call(left, right), @incoming[to][from] || 0].max
+        @incoming[to][from] = gap
+        @outgoing[from][to] = gap
+      end
+
+      def place_blocks
+        positions = {}
+        visit(@incoming) { |block| push_right(block, positions) }
+        visit(@outgoing) { |block| pull_back(block, positions) }
+        positions
+      end
+
+      def push_right(block, positions)
+        farthest = @incoming[block].map { |from, gap| positions[from] + gap }
+        positions[block] = farthest.max || 0
+      end
+
+      def pull_back(block, positions)
+        least = @outgoing[block].map { |to, gap| positions[to] - gap }.min
+        positions[block] = [positions[block], least].max if least
+      end
+
+      # Yields every key after the keys it points at.
+      def visit(graph)
+        done = Set.new
+        graph.each_key do |start|
+          stack = [[start, false]]
+          until stack.empty?
+            id, expanded = stack.pop
+            next yield(id) if expanded
+            next unless done.add?(id)
+
+            stack.push([id, true], *graph.fetch(id).keys.map { |o| [o, false] })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_conflicts.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Finds the edges Brandes-Koepf must not align: a long edge's inner
+    # segment crossed by a short one keeps the long edge straight.
+    class ErDiagramConflicts
+      # @param layers [Array<Array<String>>] ids per rank, left to right
+      # @param adjacency [ErDiagramAdjacency]
+      # @param dummies [Hash{String=>Boolean}] true for edge-dummy nodes
+      # @return [Hash{Array(String, String)=>true}] both orders of each pair
+      def self.call(layers, adjacency, dummies)
+        new(layers, adjacency, dummies).call
+      end
+
+      def initialize(layers, adjacency, dummies)
+        @layers = layers
+        @predecessors = adjacency.predecessors
+        @dummies = dummies
+        @order = {}
+        layers.each do |layer|
+          layer.each_with_index { |id, index| @order[id] = index }
+        end
+      end
+
+      def call
+        @layers.each_cons(2).with_object({}) do |(previous, layer), found|
+          scan_layer(previous, layer, found)
+        end
+      end
+
+      private
+
+      def scan_layer(previous, layer, found)
+        left = 0
+        scanned = 0
+        layer.each_with_index do |id, index|
+          other = inner_neighbour(id)
+          right = other ? @order[other] : previous.length
+          next unless other || id == layer.last
+
+          layer[scanned..index].each { |node| mark(node, left, right, found) }
+          scanned = index + 1
+          left = right
+        end
+      end
+
+      def mark(node, left, right, found)
+        @predecessors[node].each do |upper|
+          next unless crossing?(upper, node, left, right)
+
+          found[[upper, node]] = true
+          found[[node, upper]] = true
+        end
+      end
+
+      def crossing?(upper, node, left, right)
+        position = @order[upper]
+        (position < left || right < position) &&
+          !(@dummies[upper] && @dummies[node])
+      end
+
+      def inner_neighbour(id)
+        return unless @dummies[id]
+
+        @predecessors[id].find { |upper| @dummies[upper] }
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_coordinates.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "er_diagram_adjacency"
+require_relative "er_diagram_conflicts"
+require_relative "er_diagram_alignment"
+require_relative "er_diagram_compaction"
+
+module Etassia
+  module Layout
+    # Assigns each node its x by Brandes-Koepf, as dagre does: four
+    # alignments (up/down, left/right) are compacted, aligned to the
+    # narrowest, and each node takes the mean of its two middle values.
+    class ErDiagramCoordinates
+      ALIGNMENTS = %i[up down].product(%i[left right]).freeze
+
+      # @param layers [Array<Array<String>>] ids per rank, left to right
+      # @param edges [Array<Array(String, String)>] chain edges
+      # @param widths [Hash{String=>Numeric}] node widths
+      # @param dummies [Hash{String=>Boolean}] true for edge-dummy nodes
+      # @param spacing [Hash] :node and :edge separation
+      # @return [Hash{String=>Float}] centre x of every node
+      def self.call(layers, edges, widths, dummies, spacing)
+        new(layers, edges, widths, dummies, spacing).call
+      end
+
+      def initialize(layers, edges, widths, dummies, spacing)
+        @layers = layers
+        @widths = widths
+        @dummies = dummies
+        @spacing = spacing
+        @adjacency = ErDiagramAdjacency.new(edges)
+        @conflicts = ErDiagramConflicts.call(layers, @adjacency, dummies)
+      end
+
+      def call
+        by_alignment = ALIGNMENTS.to_h do |vertical, horizontal|
+          [[vertical, horizontal], alignment(vertical, horizontal)]
+        end
+        narrowest = by_alignment.values.min_by { |xs| extent(xs) }
+        shift_to(by_alignment, narrowest)
+        balance(by_alignment)
+      end
+
+      private
+
+      def alignment(vertical, horizontal)
+        layers = sweep_order(vertical, horizontal)
+        neighbours = if vertical == :up
+                       @adjacency.predecessors
+                     else
+                       @adjacency.successors
+                     end
+        root = ErDiagramAlignment.new(neighbours, @conflicts).call(layers)
+        xs = ErDiagramCompaction.new(layers, root, method(:separation)).call
+        horizontal == :right ? xs.transform_values(&:-@) : xs
+      end
+
+      def sweep_order(vertical, horizontal)
+        layers = vertical == :up ? @layers : @layers.reverse
+        horizontal == :right ? layers.map(&:reverse) : layers
+      end
+
+      def separation(left, right)
+        (@widths[left] / 2.0) + margin(left) + margin(right) +
+          (@widths[right] / 2.0)
+      end
+
+      def margin(id)
+        (@dummies[id] ? @spacing[:edge] : @spacing[:node]) / 2.0
+      end
+
+      def extent(positions)
+        sides = positions.flat_map do |id, x|
+          [x - (@widths[id] / 2.0), x + (@widths[id] / 2.0)]
+        end
+        sides.max - sides.min
+      end
+
+      def shift_to(by_alignment, narrowest)
+        bounds = narrowest.values.minmax
+        by_alignment.each do |key, positions|
+          next if positions.equal?(narrowest)
+
+          delta = offset(positions, key.last, bounds)
+          by_alignment[key] = positions.transform_values { |x| x + delta }
+        end
+      end
+
+      def offset(positions, horizontal, bounds)
+        low, high = bounds
+        return low - positions.values.min if horizontal == :left
+
+        high - positions.values.max
+      end
+
+      def balance(by_alignment)
+        by_alignment[ALIGNMENTS.first].keys.to_h do |id|
+          middle = ALIGNMENTS.map { |key| by_alignment[key][id] }.sort
+          [id, (middle[1] + middle[2]) / 2.0]
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_entity_size.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../text_measurement/trebuchet_advances"
+
+module Etassia
+  module Layout
+    # Sizes an entity box the way mmdc's erBox does: a name row above one row
+    # per attribute, with the type, name, key and comment columns each as wide
+    # as their widest cell. Text is measured as Trebuchet MS at 16px, the face
+    # mmdc measured with.
+    #
+    # The numbers are mmdc's defaults after its 1.25 scale for non-HTML
+    # labels: diagramPadding 20 and entityPadding 15 become PADDING and
+    # TEXT_PADDING, and a text line is 24px tall.
+    module ErDiagramEntitySize
+      FONT_SIZE = 16
+      TEXT_HEIGHT = 24
+      PADDING = 25
+      TEXT_PADDING = 18.75
+      ROW_HEIGHT = TEXT_HEIGHT + TEXT_PADDING
+      # An entity with no attributes is a plain padded label box instead.
+      LABEL_PADDING_X = 20
+      LABEL_PADDING_Y = 30
+      MIN_ENTITY_WIDTH = 100
+      TABLE = TextMeasurement::TrebuchetAdvances::TABLE
+      private_constant :TABLE
+
+      module_function
+
+      # @param name [String] the entity name
+      # @param attributes [Array<Hash>] cells under :attribute_type, :name,
+      #   :key_type and :note
+      # @return [Hash] :width and :height of the box
+      def call(name, attributes)
+        return label_box(name) if attributes.empty?
+
+        {
+          width: box_width(name, cell_texts(attributes)),
+          height: ROW_HEIGHT * (attributes.length + 1),
+        }
+      end
+
+      # @return [Float] the width of one line of text
+      def text_width(text)
+        text.to_s.each_char.sum { |char| TABLE.fetch(char.ord, 1000) } *
+          FONT_SIZE / 1000.0
+      end
+
+      def label_box(name)
+        width = text_width(name) + (LABEL_PADDING_X * 2)
+        {
+          width: [width, MIN_ENTITY_WIDTH].max.to_f,
+          height: TEXT_HEIGHT + (LABEL_PADDING_Y * 2),
+        }
+      end
+
+      def box_width(name, cells)
+        [column_widths(cells).sum,
+         text_width(name) + (PADDING * 2),
+         cells.flatten.map { |cell| text_width(cell) }.max + (PADDING * 2)].max
+      end
+
+      def cell_texts(attributes)
+        attributes.map do |attribute|
+          [attribute[:attribute_type], attribute[:name],
+           attribute[:key_type].to_s.split(/\s*,\s*/).join(","),
+           attribute[:note]]
+        end
+      end
+
+      # The type and name columns always count; the key and comment columns
+      # vanish when no attribute fills them.
+      def column_widths(cells)
+        cells.transpose.each_with_index.map do |column, index|
+          widest = column.map { |cell| text_width(cell) }.max + PADDING
+          index >= 2 && widest <= PADDING ? 0 : widest
+        end
+      end
+      private_class_method :label_box, :box_width, :cell_texts, :column_widths
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_layering.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Gives each entity a rank (a row of the diagram), the way dagre does
+    # for mmdc: every relationship spans at least two ranks, so that it has
+    # a middle rank to hold its label.
+    #
+    # APPROXIMATION: dagre ranks with network simplex. This starts from the
+    # longest path and then moves a node toward whichever side has more
+    # edges until nothing moves. It minimises the same total edge length,
+    # but it can stop at a different rank than network simplex on a graph
+    # where moving one node alone does not help.
+    class ErDiagramLayering
+      MIN_LENGTH = 2
+      MAX_PASSES = 100
+
+      # @param ids [Array<String>] entity ids in declaration order
+      # @param edges [Array<Array(String, String)>] [source, target] pairs
+      # @return [Array(Hash, Array)] each id's rank, and the edges pointing
+      #   down the ranks (nil for a self-loop); a cycle is broken by turning
+      #   its back edge around
+      def self.call(ids, edges)
+        new(ids, edges).call
+      end
+
+      def initialize(ids, edges)
+        @ids = ids
+        @edges = edges
+      end
+
+      def call
+        oriented = acyclic(@edges)
+        ranks = longest_path(oriented.compact)
+        balance(ranks, oriented.compact)
+        floor = ranks.values.min || 0
+        [ranks.transform_values { |rank| rank - floor }, oriented]
+      end
+
+      private
+
+      # Depth-first, in declaration order: an edge into a node still on the
+      # stack closes a cycle and is reversed.
+      def acyclic(edges)
+        on_stack = {}
+        seen = {}
+        reversed = {}
+        @ids.each { |id| visit(id, edges, on_stack, seen, reversed) }
+        edges.each_with_index.map do |(from, to), index|
+          next if from == to
+
+          reversed[index] ? [to, from] : [from, to]
+        end
+      end
+
+      def visit(id, edges, on_stack, seen, reversed)
+        return if seen[id]
+
+        seen[id] = on_stack[id] = true
+        edges.each_with_index do |(from, to), index|
+          next unless from == id && to != id
+
+          reversed[index] = true if on_stack[to]
+          visit(to, edges, on_stack, seen, reversed)
+        end
+        on_stack[id] = false
+      end
+
+      def longest_path(edges)
+        ranks = @ids.to_h { |id| [id, 0] }
+        (@ids.length + 1).times do
+          edges.each do |from, to|
+            ranks[to] = [ranks[to], ranks[from] + MIN_LENGTH].max
+          end
+        end
+        ranks
+      end
+
+      def balance(ranks, edges)
+        MAX_PASSES.times do
+          moved = @ids.map { |id| relocated?(id, ranks, edges) }
+          break unless moved.any?
+        end
+      end
+
+      def relocated?(id, ranks, edges)
+        target = target_rank(id, ranks, edges)
+        return false if target.nil? || target == ranks[id]
+
+        ranks[id] = target
+        true
+      end
+
+      # A node follows whichever side has more edges; equal sides stay put.
+      def target_rank(id, ranks, edges)
+        incoming, outgoing = sides(id, edges)
+        case incoming.length <=> outgoing.length
+        when 1 then incoming.map { |from| ranks[from] + MIN_LENGTH }.max
+        when -1 then outgoing.map { |to| ranks[to] - MIN_LENGTH }.min
+        end
+      end
+
+      def sides(id, edges)
+        [edges.select { |_from, to| to == id }.map(&:first),
+         edges.select { |from, _to| from == id }.map(&:last)]
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_ordering.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "er_diagram_adjacency"
+
+module Etassia
+  module Layout
+    # Orders the nodes within each rank to cut edge crossings, following
+    # dagre's order step: a depth-first starting order, then alternating
+    # barycenter sweeps up and down, keeping the layering with the fewest
+    # crossings. Dummy nodes stand in for the middle of every edge.
+    class ErDiagramOrdering
+      STALL_LIMIT = 4
+
+      # @param ranks [Hash{String=>Integer}] rank of every node, dummies too
+      # @param edges [Array<Array(String, String)>] chain edges, rank by rank
+      # @return [Array<Array<String>>] the ids on each rank, left to right
+      def self.call(ranks, edges)
+        new(ranks, edges).call
+      end
+
+      def initialize(ranks, edges)
+        @ranks = ranks
+        adjacency = ErDiagramAdjacency.new(edges)
+        @successors = adjacency.successors
+        @predecessors = adjacency.predecessors
+      end
+
+      def call
+        layers = starting_layers
+        best = nil
+        stalled = 0
+        0.step do |sweep|
+          layers = sweep_once(layers, sweep)
+          best, stalled = better(best, layers, stalled)
+          return best.first if stalled >= STALL_LIMIT
+        end
+      end
+
+      private
+
+      def starting_layers
+        layers = Array.new((@ranks.values.max || -1) + 1) { [] }
+        seen = {}
+        @ranks.keys.sort_by.with_index { |id, index| [@ranks[id], index] }
+          .each { |id| descend(id, layers, seen) }
+        layers
+      end
+
+      def descend(id, layers, seen)
+        return if seen[id]
+
+        seen[id] = true
+        layers[@ranks[id]] << id
+        @successors[id].each { |to| descend(to, layers, seen) }
+      end
+
+      # @param best [Array(Array, Integer), nil] layers and their crossings
+      # @return [Array(Array, Integer)] the fewer-crossings candidate, and
+      #   how many sweeps in a row it has stood
+      def better(best, layers, stalled)
+        crossings = crossing_count(layers)
+        return [best, stalled + 1] if best && best.last <= crossings
+
+        [[layers, crossings], 1]
+      end
+
+      def sweep_once(layers, sweep)
+        layers = layers.dup
+        order, offset, neighbours = sweep_plan(layers.length, sweep.odd?)
+        order.each do |rank|
+          layers[rank] = reorder(layers[rank], layers[rank + offset],
+                                 neighbours, (sweep % 4) >= 2)
+        end
+        layers
+      end
+
+      # The ranks to visit, where the fixed rank lies relative to each, and
+      # which edges say where a node belongs.
+      def sweep_plan(count, downwards)
+        if downwards
+          [(1...count), -1, @predecessors]
+        else
+          [(count - 2).downto(0), 1, @successors]
+        end
+      end
+
+      # A node with no neighbour in the fixed layer keeps its slot.
+      def reorder(layer, fixed, neighbours, bias_right)
+        position = fixed.each_with_index.to_h
+        centres = layer.to_h { |id| [id, barycenter(neighbours[id], position)] }
+        movable, keepers =
+          layer.each_with_index.partition { |id, _| centres[id] }
+        merge(rank(movable, centres, bias_right), keepers)
+      end
+
+      # Ties on the barycenter keep the old order, or reverse it on a
+      # right-biased sweep.
+      def rank(movable, centres, bias_right)
+        movable.sort_by do |id, index|
+          [centres[id], bias_right ? -index : index]
+        end.map(&:first)
+      end
+
+      def barycenter(neighbours, position)
+        near = neighbours.filter_map { |other| position[other] }
+        near.sum.fdiv(near.length) unless near.empty?
+      end
+
+      # Puts each keeper back at its old index once enough nodes precede it.
+      def merge(movable, keepers)
+        ordered = []
+        take_keepers(ordered, keepers)
+        movable.each do |id|
+          ordered << id
+          take_keepers(ordered, keepers)
+        end
+        ordered
+      end
+
+      def take_keepers(ordered, keepers)
+        while keepers.any? && keepers.first.last <= ordered.length
+          ordered << keepers.shift.first
+        end
+      end
+
+      def crossing_count(layers)
+        layers.each_cons(2).sum do |upper, lower|
+          crossings_between(upper, lower)
+        end
+      end
+
+      def crossings_between(upper, lower)
+        position = lower.each_with_index.to_h
+        pairs = upper.flat_map do |id|
+          @successors[id].filter_map { |to| position[to] }.sort
+        end
+        pairs.each_with_index.sum do |value, index|
+          pairs[(index + 1)..].count { |later| later < value }
+        end
+      end
+    end
+  end
+end