etassia 0.1.0

data/lib/etassia/notation/plantuml/rank_hierarchy.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Classes joined by relations in a tree or a lattice, ranked the way
+      # PlantUML's hierarchical layout ranks them: the class a relation's
+      # glyph points away from sits one rank above the other (`A <|-- B` puts
+      # A on top, `A <|-- B` written with `-up-` puts B on top), a
+      # one-dash relation keeps both ends in one rank, and siblings fan out
+      # side by side in one rank. Classes joined to nothing sit in a block to
+      # the right of the hierarchy.
+      #
+      # {for} returns nil when the diagram has packages, association classes
+      # or a relation cycle, which keeps the grid.
+      class RankHierarchy
+        RANK_GAP = 60.0
+        NODE_GAP = 35.0
+        SAME_RANK_GAP = 50.0
+        BLOCK_GAP = 35.0
+        # A label on a relation between neighbouring ranks takes a text row
+        # of its own between them: 17 for one line, 15 more per further line.
+        LABEL_ROW = 15.0
+        LABEL_PAD = 2.0
+        LOOSE_COLUMNS = 2
+        SIDEWAYS = %i[left right].freeze
+        private_constant :RANK_GAP, :LABEL_ROW, :LABEL_PAD, :NODE_GAP,
+                         :SAME_RANK_GAP, :BLOCK_GAP,
+                         :LOOSE_COLUMNS, :SIDEWAYS
+
+        # @return [RankHierarchy, nil]
+        def self.for(diagram)
+          return unless fits?(diagram)
+
+          ranks = rank_of(diagram)
+          new(diagram, ranks) if ranks
+        end
+
+        def self.fits?(diagram)
+          names = diagram.classes.map(&:name)
+          diagram.packages.empty? && diagram.junctions.empty? &&
+            diagram.relations.any? &&
+            diagram.relations.all? { |relation| drawable?(relation, names) }
+        end
+
+        def self.drawable?(relation, names)
+          ends = [relation.left, relation.right]
+          !relation.layout_only? && ends.uniq.size == 2 &&
+            ends.all? { |name| names.include?(name) }
+        end
+
+        # @return [Hash{String => Integer}, nil] each related class's rank
+        def self.rank_of(diagram)
+          related = diagram.relations.flat_map { |r| [r.left, r.right] }.uniq
+          groups = same_rank_groups(diagram.relations, related)
+          levels = group_levels(diagram.relations, groups)
+          levels && related.to_h { |name| [name, levels.fetch(groups[name])] }
+        end
+
+        def self.group_levels(relations, groups)
+          longest_paths(groups.values.uniq, deeper_edges(relations, groups))
+        end
+
+        # Union of the classes a one-dash or sideways relation keeps level.
+        def self.same_rank_groups(relations, names)
+          groups = names.to_h { |name| [name, name] }
+          relations.select { |r| level?(r) }.each do |relation|
+            keep = groups.fetch(relation.left)
+            drop = groups.fetch(relation.right)
+            groups.transform_values! { |group| group == drop ? keep : group }
+          end
+          groups
+        end
+
+        def self.level?(relation)
+          SIDEWAYS.include?(relation.direction) ||
+            (relation.direction.nil? && relation.length == 1)
+        end
+
+        # `[upper, lower]` group pairs for every relation that steps a rank.
+        def self.deeper_edges(relations, groups)
+          relations.reject { |r| level?(r) }.map do |relation|
+            pair = [groups.fetch(relation.left), groups.fetch(relation.right)]
+            relation.direction == :up ? pair.reverse : pair
+          end
+        end
+
+        # Rank by longest path; nil when the relations loop.
+        def self.longest_paths(groups, deeper)
+          levels = groups.to_h { |group| [group, 0] }
+          groups.size.times { return levels unless lowered?(levels, deeper) }
+          nil
+        end
+
+        # Lowers every group that sits no deeper than its upper one; whether
+        # any moved.
+        def self.lowered?(levels, deeper)
+          deeper.map do |upper, lower|
+            next false if levels[lower] > levels[upper]
+
+            levels[lower] = levels[upper] + 1
+            true
+          end.any?
+        end
+
+        # @param diagram [Diagram]
+        # @param ranks [Hash{String => Integer}]
+        def initialize(diagram, ranks)
+          @diagram = diagram
+          @ranks = ranks
+          @order = ranks.keys.sort_by { |name| declared.index(name) }
+        end
+
+        # @param sizes [Hash{String => Array<Float>}] `[width, height]` by
+        #   class name
+        # @param origin [Array<Float>] top-left corner of the drawing
+        # @return [Hash{String => Array<Float>}] each class's top-left corner
+        def place(sizes, origin)
+          rows = rows_in_order
+          loose = loose_rows
+          tops = rank_tops(rows, loose, sizes, origin.last)
+          corners = ranked_corners(rows, sizes, origin.first, tops)
+          corners.merge(loose_corners(loose, sizes, corners, tops))
+        end
+
+        private
+
+        def ranked_corners(rows, sizes, left, tops)
+          lefts = centred_lefts(rows, sizes)
+          shift = left - lefts.values.min
+          rows.each_with_index.flat_map do |row, rank|
+            row.map do |name|
+              [name, [lefts.fetch(name) + shift,
+                      centred_top(tops.fetch(rank), sizes.fetch(name).last)]]
+            end
+          end.to_h
+        end
+
+        def declared
+          @declared ||= @diagram.classes.map(&:name)
+        end
+
+        # Each rank's classes left to right: level-relation order first, then
+        # the mean position of the class's upper neighbours.
+        def rows_in_order
+          depth = @ranks.values.max
+          rows = (0..depth).map { [] }
+          @order.each { |name| rows[@ranks.fetch(name)] << name }
+          rows.each_with_index.with_object([]) do |(row, index), placed|
+            placed << sorted_row(row, placed[index - 1], index)
+          end
+        end
+
+        def sorted_row(row, above, index)
+          keyed = row.each_with_index.sort_by do |name, position|
+            [index.zero? ? 0 : mean_position(name, above), position]
+          end.map(&:first)
+          honour_level_order(keyed)
+        end
+
+        def mean_position(name, above)
+          parents = neighbours(name, upper: true).filter_map do |parent|
+            above.index(parent)
+          end
+          parents.empty? ? above.size : parents.sum.fdiv(parents.size)
+        end
+
+        # The classes one rank above `name`, or below it.
+        def neighbours(name, upper:)
+          @diagram.relations.filter_map do |relation|
+            next if self.class.level?(relation)
+
+            top, bottom = pair(relation)
+            upper ? (top if bottom == name) : (bottom if top == name)
+          end
+        end
+
+        def pair(relation)
+          ends = [relation.left, relation.right]
+          relation.direction == :up ? ends.reverse : ends
+        end
+
+        # A one-dash relation puts its written-first class on the left.
+        def honour_level_order(row)
+          constraints = @diagram.relations.select do |relation|
+            self.class.level?(relation) && row.include?(relation.left)
+          end
+          constraints.each_with_object(row.dup) do |relation, ordered|
+            move_before(ordered, *level_pair(relation))
+          end
+        end
+
+        def move_before(ordered, left, right)
+          return unless ordered.index(left) > ordered.index(right)
+
+          ordered.delete(left)
+          ordered.insert(ordered.index(right), left)
+        end
+
+        def level_pair(relation)
+          ends = [relation.left, relation.right]
+          relation.direction == :left ? ends.reverse : ends
+        end
+
+        # Left edges: rows packed left to right, then each class pulled
+        # under its parents (and over its children) as far as its neighbours
+        # allow.
+        def centred_lefts(rows, sizes)
+          lefts = {}
+          rows.each { |row| pack(row, sizes, lefts) }
+          rows.drop(1).each { |row| pull(row, sizes, lefts, upper: true) }
+          rows.reverse.each { |row| pull(row, sizes, lefts, upper: false) }
+          lefts
+        end
+
+        def pack(row, sizes, lefts)
+          cursor = 0.0
+          row.each do |name|
+            lefts[name] = cursor
+            cursor += sizes.fetch(name).first + gap_after(name, row)
+          end
+        end
+
+        def gap_after(name, row)
+          level = @diagram.relations.any? do |relation|
+            self.class.level?(relation) && relation.left == name &&
+              row.include?(relation.right)
+          end
+          level ? SAME_RANK_GAP : NODE_GAP
+        end
+
+        def pull(row, sizes, lefts, upper:)
+          row.each_with_index do |name, index|
+            wanted = wanted_centre(name, sizes, lefts, upper)
+            next unless wanted
+
+            floor = floor_for(row, index, sizes, lefts)
+            lefts[name] = [wanted - (sizes.fetch(name).first / 2), floor].max
+          end
+        end
+
+        # The leftmost the class at `index` may sit: clear of the one before.
+        def floor_for(row, index, sizes, lefts)
+          return -Float::INFINITY if index.zero?
+
+          before = row[index - 1]
+          lefts[before] + sizes.fetch(before).first + gap_after(before, row)
+        end
+
+        def wanted_centre(name, sizes, lefts, upper)
+          others = neighbours(name, upper: upper)
+          return if others.empty?
+
+          centres = others.map { |other| centre(other, sizes, lefts) }
+          centres.sum / centres.size
+        end
+
+        def centre(name, sizes, lefts)
+          lefts.fetch(name) + (sizes.fetch(name).first / 2)
+        end
+
+        # Each rank's top and height: as tall as its tallest class, loose
+        # ones included, the next rank a rank gap and the labels' room below.
+        def rank_tops(rows, loose, sizes, start)
+          cursor = start
+          Array.new([rows.size, loose.size].max) do |rank|
+            height = [rows, loose].map do |set|
+              row_height(set.fetch(rank, []), sizes)
+            end.max
+            Top.new(cursor, height).tap do
+              cursor += height + RANK_GAP + label_room(rows, rank)
+            end
+          end
+        end
+
+        Top = Struct.new(:at, :height)
+        private_constant :Top
+
+        # Classes of unequal height share their rank's middle.
+        def centred_top(rank, height)
+          rank.at + ((rank.height - height) / 2)
+        end
+
+        # The room the labels of the relations from rank `rank` down to the
+        # next take: the tallest of them.
+        def label_room(rows, rank)
+          lines = rows[rank + 1] && @diagram.relations.filter_map do |relation|
+            label_lines(relation, rows[rank], rows[rank + 1])
+          end&.max
+          lines ? LABEL_PAD + (lines * LABEL_ROW) : 0.0
+        end
+
+        def label_lines(relation, row, below)
+          top, bottom = pair(relation)
+          return if self.class.level?(relation) || relation.label.to_s.empty?
+          return unless row.include?(top) && below.include?(bottom)
+
+          relation.label.split('\\n').size
+        end
+
+        def row_height(row, sizes)
+          row.map { |name| sizes.fetch(name).last }.max || 0.0
+        end
+
+        # Unrelated classes fill rows of two beside the hierarchy, a row to
+        # a rank.
+        def loose_rows
+          (declared - @ranks.keys).each_slice(LOOSE_COLUMNS).to_a
+        end
+
+        # The first column sits right of the hierarchy's ranks that hold a
+        # loose class and centres its classes on one another; the rest follow
+        # their neighbour.
+        def loose_corners(loose, sizes, corners, tops)
+          return {} if loose.empty?
+
+          left = loose_left(loose, sizes, corners)
+          starts = first_columns(loose, sizes, left)
+          loose.each_index.map do |rank|
+            row_corners(loose[rank], sizes, tops.fetch(rank), starts[rank])
+          end.reduce(:merge)
+        end
+
+        def first_columns(loose, sizes, left)
+          widths = loose.map { |row| sizes.fetch(row.first).first }
+          widths.map { |width| left + ((widths.max - width) / 2) }
+        end
+
+        def loose_left(loose, sizes, corners)
+          beside = corners.select { |name, _| @ranks.fetch(name) < loose.size }
+          beside.map { |name, (x, _)| x + sizes.fetch(name).first }.max +
+            BLOCK_GAP
+        end
+
+        def row_corners(row, sizes, rank, first)
+          x = first
+          row.to_h do |name|
+            width, height = sizes.fetch(name)
+            corner = [name, [x, centred_top(rank, height)]]
+            x += width + NODE_GAP
+            corner
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/relation.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # A relation line, kept the way it was written.
+      #
+      # `left` and `right` are the class names on either side of the arrow.
+      # `head` is the side the marker or arrowhead sits on, :left or :right,
+      # :both, or nil for a plain `--`. `kind` is :extension,
+      # :implementation, :association, :dependency, :aggregation,
+      # :composition or :nesting, and nil when `head` is :both; `markers`
+      # then maps each side to its kind. `dashed` is true for a dotted
+      # body. `color`, `width` and `dotted?` come from a bracketed style such as
+      # `-[#red,dotted,thickness=4]->` and are nil, nil and false without one.
+      # `direction` is the glyph's :up, :down, :left or :right word,
+      # or nil. `length` counts the body's dashes and dots. The
+      # multiplicities, roles and the label are the quoted, `/"role"` and
+      # `: text` parts, or nil.
+      class Relation
+        attr_reader :left, :right, :kind, :head, :markers,
+                    :left_multiplicity, :right_multiplicity, :label,
+                    :left_role, :right_role, :direction, :length,
+                    :color, :width
+
+        # @param arrow [Hash] holds `:kind`, `:head`, `:markers`, `:dashed`
+        #   and `:plain`, and optionally `:direction` and `:length` (2 when
+        #   absent, the body of `--`)
+        # @param ends [Hash] holds `:left`, `:right`, `:left_role` and
+        #   `:right_role`, each a String or nil
+        #
+        # Those two travel as hashes because the scoreboard counts a parameter
+        # list past five as lint debt.
+        def initialize(left:, right:, arrow:, ends:, **options)
+          @left = left
+          @right = right
+          assign_arrow(arrow)
+          assign_ends(ends)
+          @label = options.fetch(:label)
+          @layout_only = options.fetch(:layout_only, false)
+          freeze
+        end
+
+        def assign_arrow(arrow)
+          @kind, @head, @markers, @dashed, @plain =
+            arrow.fetch_values(:kind, :head, :markers, :dashed, :plain)
+          @direction = arrow[:direction]
+          @length = arrow.fetch(:length, 2)
+          @color = arrow[:color]
+          @width = arrow[:width]
+          @dotted = arrow.fetch(:dotted, false)
+        end
+
+        def assign_ends(ends)
+          @left_multiplicity, @right_multiplicity, @left_role, @right_role =
+            ends.fetch_values(:left, :right, :left_role, :right_role)
+        end
+
+        private :assign_arrow, :assign_ends
+
+        def dashed?
+          @dashed
+        end
+
+        # True for a bracketed `dotted` style, drawn finer than a dash.
+        def dotted?
+          @dotted
+        end
+
+        # True for a bare `-->` or `<--` style arrow, which a sequence
+        # diagram also has.
+        def plain?
+          @plain
+        end
+
+        # True when PlantUML keeps this edge as a layout constraint but does
+        # not draw it, such as a relation touching a hidden Smetana class.
+        def layout_only?
+          @layout_only
+        end
+
+        def as_layout_only
+          self.class.new(left: left, right: right, arrow: arrow_attributes,
+                         ends: end_attributes, label: label,
+                         layout_only: true)
+        end
+
+        private
+
+        def arrow_attributes
+          { kind: kind, head: head, markers: markers, dashed: dashed?,
+            plain: plain?, direction: direction, length: length,
+            color: color, width: width, dotted: dotted? }
+        end
+
+        def end_attributes
+          { left: left_multiplicity, right: right_multiplicity,
+            left_role: left_role, right_role: right_role }
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/relation_label_separator.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "relation_path_points"
+require_relative "segment_box"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Keeps relation labels from printing over one another, and off other
+      # relations' lines. Each label sits on the middle of its own relation,
+      # so two relations between the same pair of classes would draw their
+      # labels at one point; a later label that meets an earlier one, or
+      # another relation's line, slides along its own relation and steps up
+      # and down in whole lines until it finds free space.
+      class RelationLabelSeparator
+        ROLE = "relation_label"
+        MARGIN = 1.0
+        MAX_STEPS = 24
+        REACH = 20.0
+        SLIDES = [0.0, 0.1, -0.1, 0.2, -0.2, 0.3, -0.3, 0.4, -0.4].freeze
+
+        # @param size [Float] label font size
+        # @param width_of [#call] maps label text to its width in the layout
+        # @param drawn_width_of [#call] maps label text to the width it is
+        #   drawn at, which decides what lines run through it
+        # @param boxes [Array<Scene::Box>] boxes a label may not lie on
+        def initialize(size:, width_of:, drawn_width_of: width_of, boxes: [])
+          @size = size
+          @boxes = boxes
+          @width_of = width_of
+          @drawn_width_of = drawn_width_of
+        end
+
+        # Moves colliding labels in place.
+        # @param scenes [Array<Scene::Relation>]
+        # @return [Array<Scene::Relation>] the same scenes
+        def call(scenes)
+          taken = box_areas
+          scenes.each do |scene|
+            next unless scene.respond_to?(:texts)
+
+            track = Track.new(scene, scenes)
+            scene.texts.each do |text|
+              taken << free_box(text, taken, track) if text.role == ROLE
+            end
+          end
+          scenes
+        end
+
+        private
+
+        def box_areas
+          @boxes.map do |box|
+            [box.x, box.y, box.x + box.width, box.y + box.height]
+          end
+        end
+
+        # A relation's own points, and with them the lines of all the others.
+        Track = Struct.new(:scene, :scenes) do
+          def own
+            @own ||= RelationPathPoints.call(
+              scene.respond_to?(:path) ? scene.path : nil,
+            )
+          end
+
+          # How near its own line a label stays, from the line's middle.
+          def reach
+            (scene.stroke_width.to_f / 2) + REACH
+          end
+
+          def others
+            @others ||= other_lines
+          end
+
+          private
+
+          def other_lines
+            scenes.reject { |other| other.equal?(scene) }
+              .select { |other| other.respond_to?(:path) }
+              .map { |other| line_of(other) }
+          end
+
+          def line_of(other)
+            [RelationPathPoints.call(other.path), other.stroke_width.to_f / 2]
+          end
+        end
+        private_constant :Track
+
+        def free_box(text, taken, track)
+          home = [text.x, text.y]
+          shift(text, home, best_move(text, home, taken, track) || [0.0, 0.0])
+          box_of(text)
+        end
+
+        # The first move that leaves the label clear of every line but its
+        # own; when each spot near its line has another line across it, the
+        # move with the fewest.
+        def best_move(text, home, taken, track)
+          fewest = nil
+          moves(track.own).each do |move|
+            shift(text, home, move)
+            count = clashes(text, taken, track)
+            next unless count
+            return move if count.zero?
+
+            fewest = [move, count] if fewer?(fewest, count)
+          end
+          fewest&.first
+        end
+
+        def fewer?(fewest, count)
+          fewest.nil? || count < fewest[1]
+        end
+
+        def shift(text, home, move)
+          text.x, text.y = home.zip(move).map(&:sum)
+        end
+
+        # Where to try the label, nearest its home first: each step up and
+        # down off it, then the same further along the line either way.
+        def moves(points)
+          return offsets.map { |down| [0.0, down] } if points.size < 2
+
+          SLIDES.flat_map { |slide| slid(points, slide) }
+        end
+
+        def slid(points, slide)
+          home = RelationPathPoints.along(points, 0.5)
+          at = RelationPathPoints.along(points, 0.5 + slide)
+          stepped(at[0] - home[0], at[1] - home[1])
+        end
+
+        def stepped(across, down)
+          offsets.map { |step| [across, down + step] }
+        end
+
+        # How many other lines run through the label, or nil when it
+        # cannot stay: on another label, across its own line or too far
+        # from it.
+        def clashes(text, taken, track)
+          return if taken.any? { |other| overlap?(box_of(text), other) }
+
+          drawn = box_of(text, @drawn_width_of)
+          return unless beside?(drawn, track)
+
+          track.others.count { |line| crossed?(drawn, *line) }
+        end
+
+        def beside?(drawn, track)
+          return true if track.own.empty?
+
+          !crossed?(drawn, track.own, 0.0) && reaches?(drawn, track)
+        end
+
+        def reaches?(drawn, track)
+          track.own.each_cons(2).any? do |from, to|
+            SegmentBox.within?(drawn, from, to, track.reach)
+          end
+        end
+
+        def crossed?(box, points, half)
+          padded = box.zip([-half, -half, half, half]).map(&:sum)
+          points.each_cons(2).any? do |from, to|
+            SegmentBox.crosses?(padded, from, to)
+          end
+        end
+
+        def offsets
+          [0.0, *(1..MAX_STEPS).flat_map do |step|
+            [step * line, -step * line]
+          end]
+        end
+
+        def line
+          @size * 1.3
+        end
+
+        def box_of(text, measure = @width_of)
+          width = measure.call(text.content)
+          left = left_edge(text, width)
+          [left - MARGIN, text.y - @size, left + width + MARGIN,
+           text.y + (@size / 4)]
+        end
+
+        # The left side of the text, which is drawn from `x` rightwards,
+        # leftwards or either way from it.
+        def left_edge(text, width)
+          { "middle" => text.x - (width / 2),
+            "end" => text.x - width }.fetch(text.anchor, text.x)
+        end
+
+        def overlap?(first, second)
+          first[0] < second[2] && second[0] < first[2] &&
+            first[1] < second[3] && second[1] < first[3]
+        end
+      end
+    end
+  end
+end