etassia 0.1.0

data/lib/etassia/notation/plantuml/gantt/renderer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../../../renderer/gantt"
+require_relative "../../../svg/polygon"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Gantt
+        # Draws a PlantUML gantt scene: grey table and day grid, lilac bars
+        # with a dark outline. The Mermaid renderer it extends draws a dated
+        # axis over coloured sections.
+        class Renderer < Etassia::Renderer::Gantt
+          GRID = "#C0C0C0"
+          INK = "#181818"
+          BAR_FILL = "#E2E2F0"
+          private_constant :GRID, :INK, :BAR_FILL
+
+          # @param scene [Gantt::Scene] final canvas geometry
+          # @return [Svg::Document]
+          def render(scene)
+            validate_scene!(scene)
+            svg = create_document(scene)
+            draw_grid(scene, svg)
+            draw_marks(scene, svg)
+            scene.texts.each { |label| svg << text_element(label) }
+            svg
+          end
+
+          private
+
+          def draw_grid(scene, svg)
+            scene.grid_lines.each { |line| svg << stroked(line, GRID) }
+            scene.bars.each { |bar| bars(bar, svg) }
+          end
+
+          def draw_marks(scene, svg)
+            scene.diamonds.each { |points| svg << diamond(points) }
+            scene.rules.each { |line| svg << stroked(line, INK) }
+          end
+
+          def stroked(geometry, colour)
+            Svg::Line.new.tap do |line|
+              apply_line_geometry(line, geometry)
+              line.stroke = colour
+              line.stroke_width = "1"
+            end
+          end
+
+          def bars(geometry, svg)
+            svg << Svg::Rect.new.tap do |rect|
+              apply_rect_geometry(rect, geometry)
+              rect.fill = BAR_FILL
+              rect.stroke = INK
+              rect.stroke_width = "1"
+            end
+          end
+
+          def diamond(points)
+            Svg::Polygon.new.tap do |polygon|
+              polygon.points = points
+              polygon.fill = INK
+              polygon.stroke = INK
+              polygon.stroke_width = "1"
+            end
+          end
+
+          def apply_text_style(text, geometry, fill)
+            super
+            text.font_family = "sans-serif"
+          end
+
+          def apply_text_geometry(text, geometry)
+            super
+            text.dominant_baseline = nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "gantt/reader"
+require_relative "gantt/layout"
+require_relative "gantt/renderer"
+require_relative "../mermaid/ir_adapters/gantt"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML gantt chart (`@startgantt`). The front end reads the
+      # source into the Gantt model Etassia already schedules and maps it
+      # through the same IR adapter; the layout and renderer are PlantUML's
+      # own, because PlantUML counts days from the first and draws a table
+      # beside the grid where Mermaid draws a dated axis. Dispatched to from
+      # {PlantUML.parse}.
+      module Gantt
+        extend self
+
+        # @param source [String] PlantUML source
+        # @return [Notation::Parsed]
+        def parse(source)
+          model, dated = Reader.new.parse(source)
+          model.axis_format = dated ? "dated" : "days"
+          Notation::Parsed.new(
+            type: :gantt,
+            diagram: Etassia::Notation::Mermaid::IRAdapters::Gantt.call(model),
+            transform: Layout, renderer: Renderer
+          )
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/include/blocks.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Include
+        # Which lines of an included file a directive keeps.
+        module Blocks
+          START_SUB = /\A!startsub[ \t]+(?<name>\S+)\z/
+          END_SUB = /\A!endsub\b/
+          BLOCK_START = /\A@start\w+/
+          BLOCK_END = /\A@end\w+/
+          private_constant :START_SUB, :END_SUB, :BLOCK_START, :BLOCK_END
+
+          module_function
+
+          # @param text [String] file bytes or text
+          # @return [Array<String>] its lines, UTF-8, line endings removed
+          def lines_of(text)
+            text.dup.force_encoding(Encoding::UTF_8).scrub.lines.map(&:chomp)
+          end
+
+          # @param kind [String] "include" or "includesub"
+          # @param selector [String, nil] the part after `!`
+          # @return [Array<String>]
+          # @raise [Error] an `!includesub` of a name the file lacks
+          def pick(kind, lines, name, selector)
+            return first_block(lines) if kind == "include"
+
+            subs = sub_blocks(lines, selector)
+            return subs unless subs.empty?
+
+            raise Error, "cannot include #{name}!#{selector}"
+          end
+
+          # @return [Array<String>] LINES without `!startsub` / `!endsub`
+          def strip_subs(lines)
+            lines.reject do |line|
+              text = line.strip
+              text.match?(START_SUB) || text.match?(END_SUB)
+            end
+          end
+
+          def first_block(lines)
+            from = lines.index { |line| line.strip.match?(BLOCK_START) }
+            return lines unless from
+
+            body = lines.drop(from + 1)
+            stop = body.index { |line| line.strip.match?(BLOCK_END) }
+            stop ? body.take(stop) : body
+          end
+
+          def sub_blocks(lines, name)
+            current = nil
+            lines.select do |line|
+              text = line.strip
+              current = START_SUB.match(text)&.[](:name) || current
+              current = nil if text.match?(END_SUB)
+              current == name && !text.match?(START_SUB)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/include/finder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Include
+        # Finds an included file, and only inside the allowed roots: the
+        # directory of the source being rendered and the include-path
+        # entries, all resolved through symlinks.
+        class Finder
+          URL = %r{\A\w[\w+.-]*://}
+          private_constant :URL
+
+          # @param base_dir [String, nil]
+          # @param include_path [Array<String>, String, nil] directories,
+          #   or a String of them joined by File::PATH_SEPARATOR
+          def initialize(base_dir, include_path)
+            extra = Array(include_path).flat_map do |entry|
+              entry.to_s.split(File::PATH_SEPARATOR)
+            end
+            @roots = [base_dir, *extra].compact.filter_map { |d| real(d) }
+          end
+
+          # @param name [String] the path as written in the directive
+          # @param dir [String, nil] directory of the including file
+          # @return [String] the real path of the file
+          # @raise [Error] a URL, or a file not found inside the roots
+          def locate(name, dir)
+            if name.match?(URL)
+              raise Error, "PlantUML include of a URL is not supported: #{name}"
+            end
+
+            found = candidates(name, dir).filter_map { |c| allowed(c) }.first
+            found || raise(Error, "cannot include #{name}")
+          end
+
+          private
+
+          def candidates(name, dir)
+            return [name] if File.absolute_path?(name)
+
+            [dir, *@roots].compact.uniq.map { |root| File.join(root, name) }
+          end
+
+          def allowed(candidate)
+            path = real(candidate)
+            path if path && File.file?(path) && @roots.any? do |root|
+              path.start_with?(File.join(root, ""))
+            end
+          end
+
+          def real(path)
+            File.realpath(path)
+          rescue SystemCallError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../../error"
+require_relative "include/blocks"
+require_relative "include/finder"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # PlantUML's file preprocessor: `!include FILE[!SELECTOR]` and
+      # `!includesub FILE!NAME`, expanded into the source before any family
+      # reads it. `!startsub NAME` / `!endsub` marker lines are dropped from
+      # the text that is kept.
+      #
+      # Measured against PlantUML 1.2026.6 (`java -jar plantuml.jar -tsvg`):
+      #
+      # - `!include FILE!N`, `!include FILE!ID` and a bare `!include FILE`
+      #   all take the FIRST `@start...` block of FILE (`!2`, `!7`, `!NOPE`
+      #   and `!BACKEND` on a file whose first block is something else all
+      #   drew the first block). The selector is accepted and ignored, which
+      #   is what the oracle draws.
+      # - `!includesub FILE!NAME` takes every `!startsub NAME` .. `!endsub`
+      #   stretch of FILE, in file order.
+      # - a relative path is looked up beside the including file, then in the
+      #   include path (`-Dplantuml.include.path`).
+      # - a file that cannot be found is an error.
+      #
+      # Unlike the JAR, which reads `../../etc/hosts` from anywhere, a path is
+      # only read when it resolves (symlinks followed) inside an allowed root:
+      # the directory of the source being rendered or an include-path entry.
+      module Include
+        # A refused or failed include; a Etassia::Error so the engine
+        # propagates it unwrapped.
+        class Error < Etassia::Error; end
+
+        DIRECTIVE = /\A!(?<kind>include|includesub)[ \t]+(?<spec>\S.*)\z/
+        PREPROCESSED = /^[ \t]*!(?:include|startsub|endsub)/n
+        MAX_DEPTH = 16
+        private_constant :DIRECTIVE, :PREPROCESSED, :MAX_DEPTH
+
+        module_function
+
+        # @param source [String] PlantUML source
+        # @param base_dir [String, nil] directory of the source; without it
+        #   only include-path entries can be read
+        # @param include_path [Array<String>, String, nil] extra roots
+        # @return [String] the source with every include expanded
+        # @raise [Error] a missing, refused or runaway include
+        def expand(source, base_dir: nil, include_path: nil)
+          return source unless source.b.match?(PREPROCESSED)
+
+          finder = Finder.new(base_dir, include_path)
+          lines = Blocks.strip_subs(Blocks.lines_of(source))
+          walk(lines, finder, base_dir && File.expand_path(base_dir), 0)
+            .join("\n")
+        end
+
+        def walk(lines, finder, dir, depth)
+          lines.flat_map do |line|
+            match = DIRECTIVE.match(line.strip)
+            match ? include_lines(match, finder, dir, depth) : [line]
+          end
+        end
+
+        def include_lines(match, finder, dir, depth)
+          raise Error, "PlantUML include nests too deeply" if depth >= MAX_DEPTH
+
+          name, selector = match[:spec].strip.split("!", 2)
+          path = finder.locate(name, dir)
+          kept = Blocks.pick(match[:kind], Blocks.lines_of(File.binread(path)),
+                             name, selector)
+          walk(Blocks.strip_subs(kept), finder, File.dirname(path), depth + 1)
+        end
+        private_class_method :walk, :include_lines
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ir_adapter/annotations.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module IRAdapter
+        # Encodes what surrounds the classes: captions, the style sheet and
+        # the directives the parser recorded.
+        module Annotations
+          module_function
+
+          def call(diagram, sink)
+            diagram.captions.each do |caption|
+              sink.node(caption.kind.to_s, caption.text)
+            end
+            style(diagram.style, sink)
+            diagram.directives.each { |text| sink.node("directive", text) }
+          end
+
+          # @param style [StyleSheet] encoded only when it sets something
+          def style(style, sink)
+            rules = style.rules
+            return if style.background.nil? && rules.empty?
+
+            node = sink.node("style")
+            sink.detail(node, "background", style.background)
+            rules.each { |kind, rule| style_rule(kind, rule, node, sink) }
+          end
+
+          def style_rule(kind, rule, parent, sink)
+            node = sink.node("style_rule", kind.to_s, parent: parent)
+            rule.each do |property, value|
+              sink.detail(node, property.to_s, value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ir_adapter/links.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module IRAdapter
+        # Encodes relations, association classes and note attachments as
+        # edges between the class nodes.
+        module Links
+          module_function
+
+          # @param ids [Hash{String => IR::Node}] class node by class name
+          def call(diagram, sink, ids)
+            diagram.relations.each { |rel| relation(rel, sink, ids) }
+            diagram.junctions.each { |junction| junction(junction, sink, ids) }
+            diagram.notes.each { |note| note(note, sink, ids) }
+          end
+
+          def relation(relation, sink, ids)
+            attributes = relation_attributes(relation, sink)
+            attributes[:properties] = markers(relation)
+            attributes[:label] = relation.label
+            sink.edge(relation.kind&.to_s, ids.fetch(relation.left),
+                      ids.fetch(relation.right), **attributes)
+          end
+
+          def markers(relation)
+            IR::PropertySet.new(
+              source_marker: relation.markers[:left]&.to_s,
+              target_marker: relation.markers[:right]&.to_s,
+            )
+          end
+
+          # The relation facts an edge has no field for hang off one node.
+          def relation_attributes(relation, sink)
+            details = relation_details(relation)
+            return {} if details.empty?
+
+            node = sink.node("relation_attributes")
+            details.each { |role, value| sink.detail(node, role, value) }
+            { parent_id: node.id }
+          end
+
+          def relation_details(relation)
+            {
+              "left_multiplicity" => relation.left_multiplicity,
+              "right_multiplicity" => relation.right_multiplicity,
+              "left_role" => relation.left_role,
+              "right_role" => relation.right_role,
+              "direction" => relation.direction&.to_s,
+              "color" => relation.color, "width" => relation.width&.to_s
+            }.merge(relation_flags(relation)).compact
+          end
+
+          def relation_flags(relation)
+            {
+              "dashed" => ("true" if relation.dashed?),
+              "plain" => ("true" if relation.plain?),
+              "dotted" => ("true" if relation.dotted?),
+              "layout_only" => ("true" if relation.layout_only?),
+              "length" => (relation.length.to_s unless relation.length == 2),
+            }.compact
+          end
+
+          def note_details(note, node, sink)
+            { "side" => note.side, "member" => note.member,
+              "color" => note.color, "stereotype" => note.stereotype }
+              .each { |role, value| sink.detail(node, role, value) }
+            sink.details(node, "line", note.lines)
+          end
+
+          def junction(junction, sink, ids)
+            node = sink.node("association_class")
+            [junction.from, junction.to].each do |name|
+              sink.edge("association_end", node, ids.fetch(name))
+            end
+            sink.edge("association_owner", node, ids.fetch(junction.owner))
+          end
+
+          def note(note, sink, ids)
+            node = sink.node("note")
+            note_details(note, node, sink)
+            return unless note.target
+
+            sink.edge("note_link", node, ids.fetch(note.target))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ir_adapter/sink.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../../ir"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module IRAdapter
+        # Collects the IR nodes and edges an encoder emits and numbers them.
+        # Ids are synthetic ("n0", "e0") so no source spelling can collide.
+        class Sink
+          attr_reader :nodes, :edges
+
+          def initialize
+            @nodes = []
+            @edges = []
+          end
+
+          # @return [IR::Node] the node, already appended
+          def node(role, label = nil, parent: nil)
+            item = IR::Node.new(id: "n#{@nodes.size}", role: role,
+                                label: label, parent_id: parent&.id)
+            @nodes << item
+            item
+          end
+
+          # Appends a child of `parent` carrying `value`, unless it is nil.
+          def detail(parent, role, value)
+            return if value.nil?
+
+            node(role, value.to_s, parent: parent)
+          end
+
+          def details(parent, role, values)
+            values.each { |value| detail(parent, role, value) }
+          end
+
+          def edge(role, source, target, **attributes)
+            item = IR::Edge.new(id: "e#{@edges.size}", role: role,
+                                source_id: source.id, target_id: target.id,
+                                **attributes)
+            @edges << item
+            item
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ir_adapter/structure.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module IRAdapter
+        # Encodes packages, classes and their members.
+        module Structure
+          KIND_ROLES = {
+            class: "class", abstract: "abstract_class",
+            interface: "interface", enum: "enum", annotation: "annotation"
+          }.freeze
+          private_constant :KIND_ROLES
+
+          module_function
+
+          # A relation may end on a package, so the result names both.
+          # @return [Hash{String => IR::Node}] the node by class name or
+          #   package id
+          def call(diagram, sink)
+            packages = package_nodes(diagram.packages, sink)
+            classes = diagram.classes.to_h do |klass|
+              [klass.name, class_node(klass, sink, packages)]
+            end
+            packages.merge(classes)
+          end
+
+          # A package is written after the package it sits inside, so the
+          # parent node exists by the time the child is built.
+          def package_nodes(packages, sink)
+            packages.each_with_object({}) do |package, nodes|
+              nodes[package.id] = package_node(package, sink, nodes)
+            end
+          end
+
+          def package_node(package, sink, nodes)
+            node = sink.node("package", package.title,
+                             parent: nodes[package.parent])
+            sink.detail(node, "source_id", package.id)
+            sink.detail(node, "shape", package.shape)
+            sink.detail(node, "icon", ("true" if package.icon))
+            sink.detail(node, "color", package.color)
+            node
+          end
+
+          def class_node(klass, sink, packages)
+            container = packages[klass.package]
+            node = sink.node(KIND_ROLES.fetch(klass.kind), klass.name,
+                             parent: container)
+            class_details(klass, node, sink)
+            klass.body.each { |member| member_node(member, node, sink) }
+            node
+          end
+
+          def class_details(klass, node, sink)
+            sink.details(node, "stereotype", klass.stereotypes)
+            sink.detail(node, "generics", klass.generics)
+            sink.details(node, "tag", klass.tags)
+          end
+
+          def member_node(member, parent, sink)
+            node = sink.node(member.kind.to_s, member.name, parent: parent)
+            sink.detail(node, "visibility", member.visibility)
+            sink.detail(node, "type", member.type)
+            sink.detail(node, "parameters", member.parameters)
+            sink.details(node, "modifier", member.modifiers)
+            type_details(member, node, sink)
+          end
+
+          def type_details(member, node, sink)
+            sink.detail(node, "type_position", declared_type_position(member))
+            sink.detail(node, "type_separator", declared_separator(member))
+          end
+
+          def declared_separator(member)
+            member.type_separator unless member.type_separator == ": "
+          end
+
+          def declared_type_position(member)
+            member.type_position unless member.type_position == :suffix
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "ir_adapter/sink"
+require_relative "ir_adapter/structure"
+require_relative "ir_adapter/links"
+require_relative "ir_adapter/annotations"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Maps the private class Diagram to a notation-neutral IR::Graph:
+      # classes, packages, notes and association classes are nodes, members
+      # and every remaining fact are child nodes, and relations, note
+      # attachments and association-class ends are edges. {IRReader} is the
+      # inverse; layout still owns measuring, placing and routing.
+      module IRAdapter
+        module_function
+
+        # @param diagram [Diagram] a parsed class diagram
+        # @return [IR::Graph]
+        def call(diagram)
+          sink = Sink.new
+          ids = Structure.call(diagram, sink)
+          Links.call(diagram, sink, ids)
+          Annotations.call(diagram, sink)
+          IR::Graph.new(id: "class_diagram", role: "class_diagram",
+                        nodes: sink.nodes, edges: sink.edges)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ir_reader/annotations.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../caption"
+require_relative "../style_sheet"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module IRReader
+        # Rebuilds the captions, the style sheet and the directives.
+        module Annotations
+          module_function
+
+          # @return [Array<Caption>]
+          def captions(index)
+            index.with_role(*Caption::KINDS.map(&:to_s)).map do |node|
+              Caption.new(node.role.to_sym, node.label)
+            end
+          end
+
+          # @return [Array<String>]
+          def directives(index)
+            index.with_role("directive").map(&:label)
+          end
+
+          # @return [StyleSheet]
+          def style(index)
+            node = index.with_role("style").first
+            return StyleSheet.new unless node
+
+            StyleSheet.new(background: index.detail(node, "background"),
+                           rules: rules(node, index))
+          end
+
+          def rules(style, index)
+            index.children(style, "style_rule").to_h do |node|
+              [node.label.to_sym, rule(node, index)]
+            end
+          end
+
+          def rule(node, index)
+            index.children(node, "background", "colour", "size").to_h do |item|
+              value = item.label
+              [item.role.to_sym, item.role == "size" ? value.to_i : value]
+            end
+          end
+        end
+      end
+    end
+  end
+end