etassia 0.1.0

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # One line of a class body.
+      #
+      # `kind` is :field or :method. `visibility` is :public, :private,
+      # :protected, :package, or nil when the line carries no marker.
+      # `parameters` is the text between a method's parentheses and is nil
+      # for a field and for a `{method}` written without parentheses. `type`
+      # is the declared type or nil. `type_position` preserves whether that
+      # type preceded the name or followed `:`; it defaults to :suffix for
+      # callers and older IR that do not record the distinction. `modifiers`
+      # holds :abstract and :static as written. `type_separator` is the
+      # text written around the `:` before a suffix type, ": " by default.
+      class Member
+        attr_reader :kind, :visibility, :name, :type, :parameters, :modifiers,
+                    :type_position, :type_separator
+
+        # @param detail [Hash] optional `:parameters`, nil by default, and
+        #   `:modifiers`, empty by default
+        def initialize(kind:, visibility:, name:, type:, **detail)
+          @kind = kind
+          @visibility = visibility
+          @name = name
+          @type = type
+          @parameters = detail[:parameters]
+          @modifiers = detail.fetch(:modifiers, [].freeze)
+          @type_position = detail.fetch(:type_position, :suffix)
+          @type_separator = detail.fetch(:type_separator, ": ")
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The visibility icon PlantUML draws before a class member: a circle for
+      # `+`, a square for `-`, a diamond for `#` and a triangle for `~`. A
+      # field's icon is hollow and a method's is filled. `skinparam
+      # classAttributeIconSize 0` turns the icons off and keeps the prefix
+      # character in the text. Geometry is measured against PlantUML 1.2026.6.
+      module MemberIcon
+        extend self
+
+        # The icon is centred this far from the box's left edge and the text
+        # of a row that has one starts this far from it; any other row starts
+        # at TEXT_PLAIN.
+        CENTRE_INSET = 11.0
+        TEXT_INSET = 20.0
+        TEXT_PLAIN = 6.0
+        # Offset of the icon's centre above the row's baseline.
+        CENTRE_RISE = { circle: 3.79, square: 3.79, diamond: 4.79,
+                        triangle: 4.79 }.freeze
+        SHAPES = { public: :circle, private: :square, protected: :diamond,
+                   package: :triangle }.freeze
+        MARKS = { public: "+", private: "-", protected: "#",
+                  package: "~" }.freeze
+        DISABLED = /\Askinparam[ \t]+classAttributeIconSize[ \t]+0\z/i
+        private_constant :CENTRE_RISE, :SHAPES, :MARKS, :DISABLED
+
+        # @param directives [Array<String>] a diagram's directive lines
+        # @return [Boolean] whether member icons are drawn
+        def enabled?(directives)
+          directives.none? { |line| DISABLED.match?(line) }
+        end
+
+        # @return [String] the written prefix character of a visibility
+        def mark(visibility)
+          MARKS.fetch(visibility, "")
+        end
+
+        # @param kinds [Array<Symbol>] each row's kind (:separator included)
+        # @param visibilities [Array<Symbol, nil>] each row's visibility
+        # @param enabled [Boolean] whether icons are drawn
+        # @return [Array<Float, nil>] how far each row's text starts from the
+        #   box's left edge: the whole of a field or method group is pushed
+        #   in when any of its members carries an icon; nil for a separator
+        def insets(kinds, visibilities, enabled)
+          iconed = enabled ? iconed_kinds(kinds, visibilities) : []
+          kinds.map do |kind|
+            next if kind == :separator
+
+            iconed.include?(kind) ? TEXT_INSET : TEXT_PLAIN
+          end
+        end
+
+        def iconed_kinds(kinds, visibilities)
+          kinds.zip(visibilities).filter_map do |kind, visibility|
+            kind if SHAPES.key?(visibility)
+          end
+        end
+
+        # @return [String] the row's text without the prefix an icon replaces
+        def visible_text(content, visibility, enabled)
+          return content unless enabled && SHAPES.key?(visibility)
+
+          content.delete_prefix(mark(visibility))
+        end
+
+        # @param visibility [Symbol, nil]
+        # @param kind [Symbol] :field or :method
+        # @param left [Float] the box's left edge
+        # @param baseline [Float] the member text's baseline
+        # @return [Scene::Icon, nil] nil when the member has no visibility
+        def at(visibility, kind, left, baseline)
+          shape = SHAPES[visibility]
+          return unless shape
+
+          Scene::Icon.new(shape: shape.to_s, visibility: visibility.to_s,
+                          filled: kind == :method, cx: left + CENTRE_INSET,
+                          cy: baseline - CENTRE_RISE.fetch(shape))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../svg"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Draws a {Scene::Icon} as SVG, in the colours PlantUML gives each
+      # visibility: a stroke and, for a method's filled icon, a fill.
+      module MemberIconElements
+        extend self
+
+        # visibility => [stroke, fill]
+        COLOURS = { "public" => %w[#038048 #84BE84],
+                    "private" => %w[#C82930 #F24D5C],
+                    "protected" => %w[#B38D22 #FFFF44],
+                    "package" => %w[#1963A0 #4177AF] }.freeze
+        MODIFIERS = { "public" => "PUBLIC", "private" => "PRIVATE",
+                      "protected" => "PROTECTED",
+                      "package" => "PACKAGE_PRIVATE" }.freeze
+        HALF = { "circle" => 3.0, "square" => 3.0, "diamond" => 4.0,
+                 "triangle" => 4.0 }.freeze
+        private_constant :COLOURS, :MODIFIERS, :HALF
+
+        # @param icon [Scene::Icon]
+        # @return [Svg::Group] the icon, marked with the visibility and kind
+        #   of its member as PlantUML marks it
+        def group(icon)
+          modifier = "#{MODIFIERS.fetch(icon.visibility)}_" \
+                     "#{icon.filled ? 'METHOD' : 'FIELD'}"
+          Svg::Group.new(data_visibility_modifier: modifier)
+            .tap { |group| group << element(icon) }
+        end
+
+        # @param icon [Scene::Icon]
+        # @return [Svg::Element]
+        def element(icon)
+          stroke, fill = COLOURS.fetch(icon.visibility)
+          fill = "none" unless icon.filled
+          return circle(icon, stroke, fill) if icon.shape == "circle"
+
+          styled(shape_of(icon), stroke, fill)
+        end
+
+        private
+
+        def shape_of(icon)
+          icon.shape == "square" ? square(icon) : polygon(icon)
+        end
+
+        def styled(shape, stroke, fill)
+          shape.tap do |element|
+            element.fill = fill
+            element.stroke = stroke
+            element.stroke_width = "1"
+          end
+        end
+
+        def circle(icon, stroke, fill)
+          Svg::Circle.new(cx: icon.cx, cy: icon.cy, r: HALF.fetch("circle"),
+                          fill: fill, stroke: stroke, stroke_width: "1")
+        end
+
+        def square(icon)
+          Svg::Rect.new(x: icon.cx - 3.0, y: icon.cy - 3.0, width: 6.0,
+                        height: 6.0)
+        end
+
+        def polygon(icon)
+          half = HALF.fetch(icon.shape)
+          points = if icon.shape == "diamond"
+                     diamond_points(icon, half)
+                   else
+                     triangle_points(icon, half)
+                   end
+          Svg::Polygon.new(points: Svg::Polygon.build_points(points))
+        end
+
+        def triangle_points(icon, half)
+          [[icon.cx, icon.cy - 3.0], [icon.cx - half, icon.cy + 3.0],
+           [icon.cx + half, icon.cy + 3.0]]
+        end
+
+        def diamond_points(icon, half)
+          [[icon.cx, icon.cy - half], [icon.cx + half, icon.cy],
+           [icon.cx, icon.cy + half], [icon.cx - half, icon.cy]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # How far apart PlantUML sets the rows of a class box's members,
+      # measured against 1.2026.6. A row is 16.49 below the one before, with
+      # 8 more between a field group and a method group; an empty group
+      # keeps a gap of its own, unless a separator already splits the rows
+      # into compartments of their own. A separator with a title is a row of
+      # its own, drawn 3.5 low and followed 4 further down; one without a
+      # title is no row but 8 of gap, its rule 6.95 under the row before.
+      module MemberPitch
+        extend self
+
+        ROW = 16.48828125
+        GROUP_GAP = 8.0
+        TITLED_DROP = 3.5
+        TITLED_EXTRA = 4.0
+        BARE_GAP = 8.0
+        BARE_RULE_DROP = 10.95
+        private_constant :ROW, :GROUP_GAP, :TITLED_DROP, :TITLED_EXTRA,
+                         :BARE_GAP, :BARE_RULE_DROP
+
+        # @param kinds [Array<Symbol>] each row's kind, :separator included
+        # @param titles [Array<String>] each row's text
+        # @param gaps [Boolean] whether an empty field or method group keeps
+        #   its gap; `hide` and `show` lines on members remove it
+        # @return [Array(Array<Float>, Float)] each row's offset from the
+        #   first row's baseline, and the extent the rows add to a box
+        def layout(kinds, titles, gaps: true)
+          cursor = gaps ? lead(kinds) : 0.0
+          last = -ROW
+          offsets = kinds.each_index.map do |index|
+            cursor += GROUP_GAP if group_opens?(kinds, index)
+            offset, cursor, last = place(kinds[index], titles[index], cursor,
+                                         last)
+            offset
+          end
+          [offsets, cursor + (gaps ? tail(kinds) : 0.0)]
+        end
+
+        # @return [Float] the gap above the rows of a box with methods and no
+        #   fields: PlantUML draws the empty field compartment there
+        def lead(kinds)
+          return 0.0 if kinds.include?(:separator)
+
+          kinds.include?(:method) && !kinds.include?(:field) ? GROUP_GAP : 0.0
+        end
+
+        # @return [Float] the gap below the rows of a box with fields and no
+        #   methods: the empty method compartment
+        def tail(kinds)
+          return 0.0 if kinds.include?(:separator)
+
+          kinds.include?(:field) && !kinds.include?(:method) ? GROUP_GAP : 0.0
+        end
+
+        private
+
+        def group_opens?(kinds, index)
+          index.positive? && kinds[index - 1] == :field &&
+            kinds[index] == :method
+        end
+
+        def place(kind, title, cursor, last)
+          return [cursor, cursor + ROW, cursor] unless kind == :separator
+          return [last + BARE_RULE_DROP, cursor + BARE_GAP, last] if
+            title.empty?
+
+          [cursor + TITLED_DROP, cursor + ROW + TITLED_EXTRA, cursor]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # How PlantUML draws the rule of a class body's separator line: `..`
+      # dotted, `==` two solid lines two pixels apart, `__` a hairline and
+      # `--` a solid line.
+      module MemberRule
+        extend self
+
+        Style = Struct.new(:width, :dash, :double)
+        DOUBLE_GAP = 2.0
+        STYLES = {
+          "." => Style.new(1.0, "1,2", false),
+          "=" => Style.new(1.0, nil, true),
+          "_" => Style.new(0.5, nil, false),
+          "-" => Style.new(1.0, nil, false),
+        }.freeze
+        private_constant :DOUBLE_GAP, :STYLES
+
+        # @param character [String] the separator's character: . = _ or -
+        # @param pieces [Array<Scene::Segment>] the rule's unstyled parts
+        # @return [Array<Scene::Segment>] the parts as drawn
+        def style(character, pieces)
+          rule = STYLES.fetch(character, STYLES["-"])
+          drawn = pieces.map { |piece| styled(piece, rule) }
+          rule.double ? drawn + drawn.map { |piece| lowered(piece) } : drawn
+        end
+
+        private
+
+        def styled(piece, rule)
+          Scene::Segment.new(x1: piece.x1, y1: piece.y1, x2: piece.x2,
+                             y2: piece.y2, width: rule.width, dash: rule.dash)
+        end
+
+        def lowered(piece)
+          Scene::Segment.new(x1: piece.x1, y1: piece.y1 + DOUBLE_GAP,
+                             x2: piece.x2, y2: piece.y2 + DOUBLE_GAP,
+                             width: piece.width, dash: piece.dash)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/network/grid.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "../drawing"
+require_relative "shapes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Network
+        # Where the bars, the rows of boxes under them and the boxes
+        # themselves fall, in the JAR's measures.
+        class Grid
+          # One bar and the row of nodes hung from it: `top` is the bar's;
+          # `level` and `height` the row's; `after` where the next bar's
+          # top falls.
+          Row = Struct.new(:top, :spans, :level, :height, :bottom, :after)
+
+          LEFT = 5.0
+          BAR = 5.0
+          INSET = 15.0
+          COLUMN_GAP = 30.0
+          MIN_BAR = 70.0
+          # Space between a bar and the row under it, and between a row and
+          # the next bar; every address on a node's lines widens both.
+          ABOVE = 30.0
+          BELOW = 35.0
+          LABEL_ROOM = 6.4775
+          # Where a bar sits against its name's baseline.
+          BAR_RISE = 7.0352
+          NAME_STEP = 14.1328
+          FIRST_BASELINE = 16.6016
+          TAIL = 47.75
+          BARE_TAIL = 51.15
+          private_constant :INSET, :COLUMN_GAP, :MIN_BAR, :ABOVE, :BELOW,
+                           :LABEL_ROOM, :BAR_RISE, :FIRST_BASELINE, :TAIL,
+                           :BARE_TAIL
+
+          # @return [Float] x where the bars start
+          attr_reader :left
+          # @return [Float] the bars' width
+          attr_reader :bars
+
+          # @param diagram [Diagram]
+          # @param placement [Placement]
+          def initialize(diagram, placement)
+            @diagram = diagram
+            @placement = placement
+            @left = LEFT + label_width + LEFT
+            @sizes = diagram.shapes.to_h do |name, shape|
+              [name, Shapes.size(shape, face(name))]
+            end
+            @widths = column_widths
+            @bars = bar_width
+            @rows = build_rows
+          end
+
+          # @return [Row] the bar of a network and the row under it
+          def row(index)
+            @rows.fetch(index)
+          end
+
+          # @return [Drawing::Box]
+          def box(span)
+            width, height = @sizes.fetch(span.name)
+            Drawing::Box.new(box_left(span, width), box_top(span, height),
+                             width, height)
+          end
+
+          # @return [Float] y of the name's baseline at a network's bar
+          def baseline(index)
+            row(index).top + BAR_RISE - lift(@diagram.networks[index])
+          end
+
+          # @return [Float] the canvas' width and height
+          def canvas
+            [(@left + @bars + 6).floor + 1, foot.ceil]
+          end
+
+          private
+
+          def box_left(span, width)
+            slot_left(span.column) + ((@widths[span.column] - width) / 2)
+          end
+
+          def box_top(span, height)
+            row = row(span.entry)
+            row.level + ((row.height - height) / 2)
+          end
+
+          # Where the canvas ends: under the last row, or under a last bar
+          # that has none.
+          def foot
+            last = @rows.last
+            return last.bottom + TAIL if last.spans.any?
+
+            last.top + BAR + BARE_TAIL
+          end
+
+          def face(text)
+            Drawing::Face.width(text, size: 12)
+          end
+
+          def lift(network)
+            network.address ? NAME_STEP / 2 : 0
+          end
+
+          def label_width
+            texts = @diagram.networks.flat_map { |n| [n.name, n.address] }
+            texts.compact.map { |text| face(text) }.max.to_f
+          end
+
+          def column_widths
+            Array.new(@placement.columns) do |column|
+              spans = @placement.spans.select { |s| s.column == column }
+              spans.map { |s| @sizes.fetch(s.name).first }.max
+            end
+          end
+
+          def bar_width
+            inner = @widths.sum + (COLUMN_GAP * (@widths.size - 1))
+            [INSET + inner + INSET, MIN_BAR].max
+          end
+
+          def slot_left(column)
+            @left + INSET + @widths.first(column).sum + (COLUMN_GAP * column)
+          end
+
+          def build_rows
+            top = FIRST_BASELINE - BAR_RISE + lift(@diagram.networks.first)
+            @diagram.networks.each_index.map do |index|
+              row_at(index, top).tap { |row| top = row.after }
+            end
+          end
+
+          def row_at(index, top)
+            spans = @placement.spans.select { |s| s.entry == index }
+            return bare_row(top) if spans.empty?
+
+            hung_row(top, spans)
+          end
+
+          def bare_row(top)
+            Row.new(top, [], top + BAR + ABOVE, 0.0, top + BAR,
+                    top + BAR + ABOVE + BELOW)
+          end
+
+          def hung_row(top, spans)
+            height = spans.map { |s| @sizes.fetch(s.name).last }.max
+            extra = room(spans)
+            level = top + BAR + ABOVE + extra
+            Row.new(top, spans, level, height, level + height,
+                    level + height + BELOW + extra)
+          end
+
+          def room(spans)
+            LABEL_ROOM * spans.map { |s| lines(s) }.max
+          end
+
+          # How many address lines a node's lines carry in all.
+          def lines(span)
+            @diagram.networks.sum do |network|
+              member = network.nodes.find { |m| m.name == span.name }
+              member&.address ? member.address.split(/\s*,\s*/).size : 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/network/layout.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "../drawing"
+require_relative "grid"
+require_relative "placement"
+require_relative "shapes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Network
+        # Stacks the networks as horizontal bars with their names at the left
+        # and hangs each node's box in a row below the first bar it belongs
+        # to, with a line to every bar after. Measures are the JAR's.
+        class Layout
+          include Drawing::Pen
+
+          BAR = 5.0
+          LINE_STEP = 12.9551
+          NAME_STEP = 14.1328
+          SLOT = 2.0
+          SHADE = "#E7E7E7"
+          DEFAULT_BAR = "#E2E2F0"
+          INK = "#000000"
+          COLOR = /\A#?[A-Za-z0-9]+\z/
+          private_constant :BAR, :LINE_STEP, :NAME_STEP, :SLOT, :SHADE,
+                           :DEFAULT_BAR, :INK, :COLOR
+
+          # @param diagram [Diagram]
+          # @return [Drawing::Scene]
+          def call(diagram, **)
+            @diagram = diagram
+            @placement = Placement.new(diagram)
+            @grid = Grid.new(diagram, @placement)
+            draw_all
+            scene(*@grid.canvas)
+          end
+
+          private
+
+          def draw_all
+            @diagram.networks.each_index do |index|
+              draw_groups(index)
+              draw_bar(index)
+            end
+            @placement.spans.each { |span| draw_node(span) }
+          end
+
+          def draw_bar(index)
+            rect(@grid.left, @grid.row(index).top, @grid.bars, BAR,
+                 fill: paint(@diagram.networks[index].color))
+            draw_names(@diagram.networks[index], @grid.baseline(index))
+          end
+
+          def draw_names(network, baseline)
+            name_line(network.name, baseline)
+            return unless network.address
+
+            name_line(network.address, baseline + NAME_STEP)
+          end
+
+          def name_line(content, baseline)
+            text(content, @grid.left - 5, Drawing::Face.middle(baseline, 12),
+                 anchor: "end", fill: INK)
+          end
+
+          def paint(color)
+            color&.match?(COLOR) ? color : DEFAULT_BAR
+          end
+
+          def draw_node(span)
+            box = @grid.box(span)
+            draw_links(span, box)
+            shape = @diagram.shapes[span.name]
+            Shapes.draw(self, shape, box)
+            text(span.name, Shapes.label_x(shape, box),
+                 Drawing::Face.middle(Shapes.baseline(shape, box), 12),
+                 anchor: "middle", fill: INK)
+            draw_addresses(span, box)
+          end
+
+          # A node reached through a network that already holds an earlier
+          # node hangs its line left of its centre; the others, right.
+          def link_x(span, box)
+            box.centre + (carried?(span) ? -SLOT : SLOT)
+          end
+
+          def carried?(span)
+            @diagram.networks[span.entry].nodes.any? do |member|
+              @placement[member.name].entry < span.entry
+            end
+          end
+
+          def draw_links(span, box)
+            x = link_x(span, box)
+            line(x, bar_bottom(span.entry), x, box.top)
+            return unless span.exit > span.entry
+
+            line(x, box.bottom, x, @grid.row(span.exit).top)
+          end
+
+          def bar_bottom(index)
+            @grid.row(index).top + BAR
+          end
+
+          def draw_addresses(span, box)
+            @diagram.networks.each_with_index do |network, index|
+              member = network.nodes.find { |m| m.name == span.name }
+              next unless member&.address
+
+              draw_address(member.address.split(/\s*,\s*/), span, box, index)
+            end
+          end
+
+          # The addresses sit along the line between a bar and the box,
+          # centred on it, one step apart.
+          def draw_address(entries, span, box, index)
+            middle = address_middle(span, box, index)
+            entries.each_with_index do |entry, row|
+              base = middle + ((row - ((entries.size - 1) / 2.0)) * LINE_STEP)
+              text(entry, link_x(span, box), Drawing::Face.middle(base, 11),
+                   size: 11, anchor: "middle", fill: INK)
+            end
+          end
+
+          # Where the line that carries the address runs: from the entry
+          # bar to the box, or from the box to a later bar.
+          def address_middle(span, box, index)
+            return ((bar_bottom(index) + box.top) / 2) + 1.66 if
+              index == span.entry
+
+            ((box.bottom + @grid.row(index).top) / 2) + 4.15
+          end
+
+          def draw_groups(index)
+            @diagram.networks[index].groups.each do |group|
+              spans = group.names.map { |name| @placement[name] }
+              spans = spans.select { |span| span.entry == index }
+              draw_group(spans, group, @grid.row(index)) if spans.any?
+            end
+          end
+
+          def draw_group(spans, group, row)
+            left, right = reach(spans.map { |span| @grid.box(span) })
+            color = paint(group.color || SHADE)
+            rect(left, row.level - 5, right - left, row.height + 10,
+                 fill: color, stroke: color)
+          end
+
+          # How far a group's shading runs round its boxes.
+          def reach(boxes)
+            [boxes.map(&:left).min - 5, boxes.map(&:right).max + 5]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/network/model.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Network
+        # A node's membership of one network.
+        Member = Struct.new(:name, :address, keyword_init: true)
+
+        # A named shaded cluster of nodes.
+        Group = Struct.new(:name, :color, :names, keyword_init: true)
+
+        # One horizontal bar and the nodes hanging from it.
+        Network = Struct.new(:name, :address, :color, :nodes, :groups,
+                             keyword_init: true)
+
+        # The whole diagram: its networks, and each node's shape.
+        Diagram = Struct.new(:networks, :shapes, keyword_init: true)
+      end
+    end
+  end
+end