etassia 0.1.0

data/lib/etassia/layout/class_diagram_namespaces.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Reads the namespace records an IR graph carries for a class diagram.
+    module ClassDiagramNamespaces
+      Namespace = Struct.new(:name, :class_ids, keyword_init: true)
+
+      module_function
+
+      # @param graph [IR::Graph] a class diagram graph
+      # @return [Array<Namespace>] the namespaces in source order
+      def call(graph)
+        children = graph.nodes.group_by(&:parent_id)
+        graph.nodes.select { |node| node.role == "namespace" }.map do |node|
+          namespace_for(node, children[node.id])
+        end
+      end
+
+      def namespace_for(node, parts)
+        members = Array(parts).select { |n| n.role == "member" }
+        Namespace.new(name: node.label, class_ids: members.map(&:label))
+      end
+    end
+  end
+end

data/lib/etassia/layout/class_diagram_notes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Reads the note records an IR graph carries for a class diagram.
+    module ClassDiagramNotes
+      Note = Struct.new(:text, :target_id, keyword_init: true)
+
+      module_function
+
+      # @param graph [IR::Graph] a class diagram graph
+      # @return [Array<Note>] the notes in source order
+      def call(graph)
+        children = graph.nodes.group_by(&:parent_id)
+        graph.nodes.select { |node| node.role == "note" }.map do |node|
+          note_for(node, children[node.id])
+        end
+      end
+
+      def note_for(node, parts)
+        target = Array(parts).find { |n| n.role == "target" }
+        Note.new(text: node.label, target_id: target&.label)
+      end
+    end
+  end
+end

data/lib/etassia/layout/class_name_advances.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Advances, in per-mille em, of the ASCII letters, digits and - _ < >
+    # of mmdc's
+    # bold class names (Trebuchet MS Bold). Fitted so that the width of every
+    # reference class-name label in spec/fixtures_mermaid stays within half
+    # a pixel; any other character is the regular face widened by
+    # FALLBACK_RATIO.
+    module ClassNameAdvances
+      FALLBACK_RATIO = 1.05
+
+      TABLE = {
+        "-" => 365, "<" => 608, ">" => 608, "_" => 580,
+        "0" => 582, "1" => 579, "2" => 577, "3" => 576, "4" => 574,
+        "5" => 572, "6" => 571, "7" => 569, "8" => 568, "9" => 567,
+        "A" => 632, "B" => 601, "C" => 629, "D" => 653, "E" => 568,
+        "F" => 577, "G" => 679, "H" => 685, "I" => 273, "J" => 524,
+        "K" => 610, "L" => 536, "M" => 737, "N" => 659, "O" => 701,
+        "P" => 577, "R" => 613, "S" => 516, "T" => 549, "U" => 687,
+        "W" => 892, "Z" => 564, "a" => 524, "b" => 570, "c" => 520,
+        "d" => 585, "e" => 569, "f" => 368, "g" => 501, "h" => 584,
+        "i" => 298, "j" => 378, "k" => 544, "l" => 304, "m" => 858,
+        "n" => 580, "o" => 554, "p" => 586, "q" => 580, "r" => 419,
+        "s" => 425, "t" => 400, "u" => 588, "v" => 526, "w" => 748,
+        "x" => 544, "y" => 525
+      }.freeze
+    end
+  end
+end

data/lib/etassia/layout/class_namespace_box.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Layout
+    # A positioned namespace box: the rectangle drawn around its classes
+    # and the title centred along its top edge, in final canvas
+    # coordinates.
+    class ClassNamespaceBox < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :title, :string
+      attribute :x, :float
+      attribute :y, :float
+      attribute :width, :float
+      attribute :height, :float
+      attribute :title_x, :float
+      attribute :title_y, :float
+    end
+  end
+end

data/lib/etassia/layout/class_namespace_nodes.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "class_namespace_box"
+
+module Etassia
+  module Layout
+    # Wraps the class nodes of each namespace in a grid cluster, and turns
+    # the placed clusters back into ClassNamespaceBox objects.
+    class ClassNamespaceNodes
+      # @param size [#call] given a title, returns its { width:, height: }
+      def initialize(size:)
+        @size = size
+      end
+
+      # @param nodes [Array<Hash>] class nodes
+      # @param namespaces [Array<#name, #class_ids>]
+      # @return [Array<Hash>] the nodes, with each namespace's members
+      #   replaced by one cluster at the position of its first member;
+      #   a namespace with no members follows as a titled leaf, as mmdc
+      #   draws it
+      def nest(nodes, namespaces, hierarchical: false)
+        return flat_nest(nodes, namespaces) unless hierarchical
+
+        clusters, owners = cluster_index(nodes, namespace_specs(namespaces))
+        attach_nested_clusters(clusters)
+        collapse_empty_clusters(clusters)
+        roots = root_clusters(clusters)
+        owners.transform_values! do |name|
+          clusters.fetch(root_name(name, clusters))
+        end
+        seen = {}
+        nest_members(nodes, owners, seen) + empty_nodes(roots, owners)
+      end
+
+      def nest_members(nodes, owners, seen)
+        nodes.filter_map do |node|
+          cluster = owners[node[:id]]
+          next node unless cluster
+          next if seen.key?(cluster[:id])
+
+          seen[cluster[:id]] = true
+          cluster
+        end
+      end
+
+      # @param nodes [Array<Hash>] nodes as #nest returns them, placed
+      # @return [Array(Array<Hash>, Array<ClassNamespaceBox>)] the plain
+      #   nodes and the namespace boxes, both in canvas coordinates
+      def flatten(nodes)
+        plain = []
+        boxes = []
+        collect(nodes, [0, 0], plain, boxes)
+        [plain, boxes]
+      end
+
+      private
+
+      def flat_nest(nodes, namespaces)
+        owners = flat_owner_index(nodes, namespaces)
+        seen = {}
+        nest_members(nodes, owners, seen) + flat_empty_nodes(namespaces, owners)
+      end
+
+      def flat_empty_nodes(namespaces, owners)
+        placed = owners.values.map { |cluster| cluster[:id] }
+        namespaces.filter_map do |item|
+          next if placed.include?("namespace:#{item.name}")
+
+          leaf_node(item.name, title: item.name)
+        end
+      end
+
+      def flat_owner_index(nodes, namespaces)
+        namespaces.each_with_object({}) do |item, index|
+          members = unclaimed(nodes, item.class_ids, index)
+          next if members.empty?
+
+          cluster = cluster_node(item.name, members, title: item.name)
+          members.each { |node| index[node[:id]] = cluster }
+        end
+      end
+
+      def empty_nodes(roots, owners)
+        placed = owners.values.map { |cluster| cluster[:id] }
+        roots.reject { |cluster| placed.include?(cluster[:id]) }
+      end
+
+      # mmdc pads the title 32px each side inside a 56px-high box.
+      def leaf_node(name, title: title_for(name))
+        label = @size.call(title)
+        {
+          id: "namespace:#{name}",
+          width: label[:width] + 64,
+          height: 56,
+          metadata: { title: title },
+        }
+      end
+
+      def namespace_specs(namespaces)
+        namespaces.each_with_object({}) do |item, specs|
+          prefix_names(item.name).each { |name| specs[name] ||= [] }
+          specs.fetch(item.name).concat(item.class_ids)
+        end
+      end
+
+      def prefix_names(name)
+        parts = name.split(".")
+        parts.each_index.map { |index| parts.first(index + 1).join(".") }
+      end
+
+      def cluster_index(nodes, specs)
+        owners = {}
+        clusters = specs.to_h do |name, class_ids|
+          members = unclaimed(nodes, class_ids, owners)
+          members.each { |node| owners[node[:id]] = name }
+          [name, cluster_node(name, members)]
+        end
+        [clusters, owners]
+      end
+
+      def unclaimed(nodes, class_ids, owners)
+        nodes.select do |node|
+          class_ids.include?(node[:id]) && !owners.key?(node[:id])
+        end
+      end
+
+      def cluster_node(name, members, title: title_for(name))
+        {
+          id: "namespace:#{name}",
+          children: members,
+          labels: [{ text: title }.merge(@size.call(title))],
+          metadata: { cluster: true, title: title },
+        }
+      end
+
+      def attach_nested_clusters(clusters)
+        clusters.each do |name, cluster|
+          parent = parent_name(name)
+          clusters.fetch(parent)[:children] << cluster if clusters.key?(parent)
+        end
+      end
+
+      def collapse_empty_clusters(clusters)
+        clusters.each do |name, cluster|
+          cluster.replace(leaf_node(name)) if cluster[:children].empty?
+        end
+      end
+
+      def root_clusters(clusters)
+        clusters.filter_map do |name, cluster|
+          cluster unless clusters.key?(parent_name(name))
+        end
+      end
+
+      def root_name(name, clusters)
+        parent = parent_name(name)
+        return name unless clusters.key?(parent)
+
+        root_name(parent, clusters)
+      end
+
+      def parent_name(name)
+        name.rpartition(".").first
+      end
+
+      def title_for(name)
+        name.rpartition(".").last
+      end
+
+      def collect(nodes, origin, plain, boxes)
+        nodes.each do |node|
+          x, y = offset(node, origin)
+          next plain << node.merge(x: x, y: y) unless titled?(node)
+
+          boxes << box(node, x, y)
+          collect(Array(node[:children]), [x, y], plain, boxes)
+        end
+      end
+
+      def offset(node, origin)
+        [origin[0] + (node[:x] || 0), origin[1] + (node[:y] || 0)]
+      end
+
+      def titled?(node)
+        node[:children] || node.dig(:metadata, :title)
+      end
+
+      def box(node, left, top)
+        ClassNamespaceBox.new(
+          id: node[:id], title: node[:metadata][:title], x: left, y: top,
+          width: node[:width], height: node[:height],
+          title_x: left + (node[:width] / 2), title_y: top + 22
+        )
+      end
+    end
+  end
+end

data/lib/etassia/layout/class_namespace_placement.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "class_cell_placement"
+require_relative "flowchart/directed_placement"
+
+module Etassia
+  module Layout
+    # Routes namespace-bearing Class graphs through the compound-aware
+    # directed placer while preserving ClassCellPlacement for flat graphs.
+    module ClassNamespacePlacement
+      module_function
+
+      def apply(graph)
+        return directed(graph) if nested?(graph)
+
+        ClassCellPlacement.apply(graph)
+      end
+
+      # mmdc's dagre puts sibling class boxes 50 apart, not the layout's 80.
+      # Keep the rank gap: cluster rank spacing already matches the reference.
+      def directed(graph)
+        graph[:layoutOptions] = (graph[:layoutOptions] || {}).merge(
+          Base::ElkOptions::NODE_NODE_SPACING => ClassCellPlacement::DAGRE_GAP,
+        )
+        ranked = graph.merge(edges: ClassCellPlacement.written_edges(graph))
+        inherit_nested_direction(
+          ranked[:children], ranked.dig(:layoutOptions, Base::ElkOptions::DIRECTION)
+        )
+        Flowchart::DirectedPlacement.apply(ranked)
+        center_vertical_siblings(ranked[:children])
+        graph.merge!(ranked.except(:edges))
+      end
+
+      def inherit_nested_direction(children, direction)
+        Array(children).each do |child|
+          nested_children = Array(child[:children])
+          if nested?(child)
+            child[:metadata] = (child[:metadata] || {}).merge(
+              direction: direction,
+            )
+          end
+          inherit_nested_direction(nested_children, direction)
+        end
+      end
+
+      def center_vertical_siblings(children)
+        Array(children).each do |child|
+          center_vertical_siblings(child[:children])
+        end
+        Array(children).group_by { |child| child[:x] }.each_value do |column|
+          center_column(column)
+        end
+      end
+
+      def center_column(column)
+        return unless column.map { |child| child[:y] }.uniq.size > 1
+
+        width = column.map { |child| child[:width] }.max
+        column.each { |child| child[:x] += (width - child[:width]) / 2.0 }
+      end
+
+      def nested?(graph)
+        Array(graph[:children]).any? do |child|
+          child[:children] || child[:id].to_s.start_with?("namespace:")
+        end
+      end
+      private_class_method :center_vertical_siblings, :center_column,
+                           :directed, :inherit_nested_direction, :nested?
+    end
+  end
+end

data/lib/etassia/layout/class_note.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Layout
+    # A positioned class-diagram note: the box, its text, and the line to
+    # the class it belongs to. Coordinates are final canvas coordinates.
+    class ClassNote < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :text, :string
+      attribute :x, :float
+      attribute :y, :float
+      attribute :width, :float
+      attribute :height, :float
+      attribute :text_x, :float
+      attribute :text_y, :float
+
+      # The id of the class the note hangs from; nil for a general note
+      attribute :target_id, :string
+
+      # Ends of the line to the class; nil for a general note
+      attribute :link_x1, :float
+      attribute :link_y1, :float
+      attribute :link_x2, :float
+      attribute :link_y2, :float
+
+      # @param text [String] note text, lines joined by newlines
+      # @return [Array<String>] the lines, at least one
+      def self.lines_of(text)
+        text.to_s.split("\n", -1).then { |all| all.empty? ? [""] : all }
+      end
+
+      # @return [Array<String>] the text split into lines
+      def lines
+        self.class.lines_of(text)
+      end
+
+      def linked?
+        !link_x1.nil?
+      end
+    end
+  end
+end

data/lib/etassia/layout/class_note_nodes.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "class_note"
+
+module Etassia
+  module Layout
+    # Turns the notes of a class diagram into grid nodes, and back into
+    # positioned ClassNote objects once the grid has placed them.
+    class ClassNoteNodes
+      LINE_HEIGHT = 24
+      VERTICAL_PADDING = 12
+      PADDING = 12
+
+      # @param font_size [Numeric] the note text size
+      # @param measure [#call] given text and font size, returns its width
+      # @param connect [#call] given two boxes, returns the point on the
+      #   first box's edge facing the second
+      def initialize(font_size:, measure:, connect:)
+        @font_size = font_size
+        @measure = measure
+        @connect = connect
+      end
+
+      # @param notes [Array<Diagram::ClassNote>]
+      # @return [Array<Hash>] one grid node per note
+      def nodes(notes)
+        notes.each_with_index.map { |note, index| node(note, index) }
+      end
+
+      # @param node [Hash] a node made by #nodes
+      def note?(node)
+        node.dig(:metadata, :note) == true
+      end
+
+      # @param nodes [Array<Hash>] placed note nodes
+      # @param classes [Hash{String => Hash}] placed class nodes by id
+      # @return [Array<ClassNote>]
+      def notes(nodes, classes)
+        nodes.map { |node| note(node, classes[node[:metadata][:target_id]]) }
+      end
+
+      private
+
+      def node(note, index)
+        lines = ClassNote.lines_of(note.text)
+        {
+          id: "note:#{index}",
+          width: width(lines),
+          height: (lines.size * LINE_HEIGHT) + VERTICAL_PADDING,
+          metadata: { note: true, text: note.text, target_id: note.target_id },
+        }
+      end
+
+      def width(lines)
+        lines.map { |line| @measure.call(line, @font_size) }.max + PADDING
+      end
+
+      def note(node, target)
+        ClassNote.new(
+          id: node[:id].delete_prefix("note:"), text: node[:metadata][:text],
+          target_id: node[:metadata][:target_id],
+          **geometry(node),
+          **link(node, target)
+        )
+      end
+
+      def geometry(node)
+        {
+          x: node[:x], y: node[:y], width: node[:width], height: node[:height],
+          text_x: node[:x] + (node[:width] / 2), text_y: node[:y] + 23
+        }
+      end
+
+      def link(node, target)
+        return {} unless target
+
+        from = @connect.call(node, target)
+        to = @connect.call(target, node)
+        { link_x1: from[:x], link_y1: from[:y],
+          link_x2: to[:x], link_y2: to[:y] }
+      end
+    end
+  end
+end

data/lib/etassia/layout/elk_notices.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "logger"
+
+module Etassia
+  module Layout
+    # A delegate around the logger elkrb reports through, minus its
+    # "partially honoured" notices.
+    #
+    # Etassia hands elkrb only the options it acts on (see ElkPlacement).
+    # Three of them, direction, alignment and node spacing, are only partly
+    # honoured by elkrb across all its algorithms but fully for the layered
+    # algorithm Etassia uses, so elkrb's notice for them is noise on every
+    # layout. Every other message, at every level, reaches the wrapped
+    # logger unchanged, whether that is elkrb's default or one the host
+    # application assigned before loading Etassia.
+    class ElkNotices < SimpleDelegator
+      PARTIAL = /\Aelkrb: option \S+ is partially honoured/
+
+      # Wraps the current Elkrb.logger once; a second call is a no-op.
+      def self.install
+        return if Elkrb.logger.is_a?(self)
+
+        Elkrb.logger = new(Elkrb.logger)
+      end
+
+      def warn(message = nil, &block)
+        return true if partial?(message || block&.call)
+
+        __getobj__.warn(message, &block)
+      end
+
+      def add(severity, message = nil, progname = nil, &block)
+        return true if partial?(message || progname || block&.call)
+
+        __getobj__.add(severity, message, progname, &block)
+      end
+      alias log add
+
+      private
+
+      def partial?(text)
+        text.is_a?(String) && PARTIAL.match?(text)
+      end
+    end
+  end
+end