etassia 0.1.0

data/lib/etassia/notation/mermaid/ir_adapters/xychart.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "../../../ir"
+
+module Etassia
+  module Notation
+    module Mermaid
+      module IRAdapters
+        # Maps an XY chart model to ordered axis and series constraints.
+        module XyChart
+          module_function
+
+          def call(diagram)
+            root_id = diagram.id || "xychart"
+            occupied = [root_id]
+            IR::Prepositioned.new(
+              id: root_id, label: diagram.title, role: "coordinate_series",
+              items: items_for(diagram, occupied)
+            )
+          end
+
+          def items_for(diagram, occupied)
+            horizontal = axis_item(
+              diagram.x_axis, "horizontal", occupied, default_range: [0, 10]
+            )
+            vertical = axis_item(
+              diagram.y_axis, "vertical", occupied, default_range: [0, 100]
+            )
+            items = [horizontal, *category_items(
+              diagram.x_axis, horizontal.id, occupied
+            ), vertical]
+            items.concat(series_items(diagram.datasets, occupied))
+          end
+
+          def axis_item(axis, direction, occupied, default_range:)
+            minimum, maximum = axis_range(axis, default_range)
+            type = axis&.type || :numeric
+            IR::PrepositionedItem.new(
+              id: reserve_id("#{direction}_axis", occupied),
+              label: axis&.label, role: "#{direction}_axis",
+              placements: [
+                placement("axis_direction", 0, direction),
+                placement("axis_kind", 0, type),
+                placement("minimum", 0, minimum),
+                placement("maximum", 0, maximum),
+              ]
+            )
+          end
+
+          def axis_range(axis, default_range)
+            return default_range unless axis
+
+            axis.range
+          end
+
+          def category_items(axis, parent_id, occupied)
+            return [] unless axis&.categorical?
+
+            axis.values.map.with_index do |value, index|
+              IR::PrepositionedItem.new(
+                id: reserve_id("category_#{index}", occupied),
+                label: value.to_s, role: "category", parent_id: parent_id,
+                placements: [placement("category", index, value)]
+              )
+            end
+          end
+
+          def series_items(datasets, occupied)
+            datasets.flat_map.with_index do |dataset, index|
+              series = series_item(dataset, index, occupied)
+              [series, *sample_items(dataset, series.id, occupied)]
+            end
+          end
+
+          def series_item(dataset, index, occupied)
+            IR::PrepositionedItem.new(
+              id: reserve_id(dataset.id || "series_#{index}", occupied),
+              label: dataset.label, role: "data_series",
+              placements: series_placements(dataset, index)
+            )
+          end
+
+          def series_placements(dataset, index)
+            { series_order: index, chart_kind: dataset.chart_type,
+              series_color: dataset.color }.filter_map do |dimension, value|
+                placement(dimension.to_s, index, value) unless value.nil?
+              end
+          end
+
+          def sample_items(dataset, parent_id, occupied)
+            dataset.values.map.with_index do |value, index|
+              IR::PrepositionedItem.new(
+                id: reserve_id("#{parent_id}_sample_#{index}", occupied),
+                role: "sample", parent_id: parent_id,
+                placements: [placement("value", index, value)]
+              )
+            end
+          end
+
+          def placement(dimension, ordinal, value)
+            IR::Placement.new(
+              dimension: dimension, ordinal: ordinal, value: scalar(value),
+            )
+          end
+
+          def scalar(value)
+            return IR::Scalar.new(number: value) if value.is_a?(Numeric)
+
+            IR::Scalar.new(text: value.to_s)
+          end
+
+          def reserve_id(preferred, occupied)
+            candidate = preferred.to_s
+            suffix = 2
+            while occupied.include?(candidate)
+              candidate = "#{preferred}_#{suffix}"
+              suffix += 1
+            end
+            occupied << candidate
+            candidate
+          end
+          private_class_method :items_for, :axis_item, :axis_range,
+                               :category_items,
+                               :series_items, :series_item, :sample_items,
+                               :series_placements, :placement, :scalar,
+                               :reserve_id
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/mermaid.rb

@@ -0,0 +1,399 @@
+# frozen_string_literal: true
+
+require_relative "../source"
+require_relative "../diagram/sequence_wrap"
+require_relative "../error/diagram_type_error"
+require_relative "../error/pipeline_error"
+require_relative "parsed"
+require_relative "mermaid/ir_adapter"
+require_relative "mermaid/git_graph_config"
+require_relative "mermaid/class_diagram_config"
+
+module Etassia
+  module Notation
+    # The Mermaid notation: detects which of its diagram types a source is,
+    # applies the preamble rules, and parses it into a diagram model.
+    #
+    # A diagram type is one row of {TYPES}: the regex detection reads and the
+    # word the error message prints. Its parser, layout, renderer and model
+    # are the classes named after the type in {Parser}, {Layout}, {Renderer}
+    # and {Diagram} (`:pie` is `Parser::Pie`, ...); a row whose class name is
+    # not the camelised type carries it as `name:` (`:xychart` -> `XyChart`).
+    module Mermaid
+      extend self
+
+      # Every Mermaid diagram type, in detection order. The keyword is what a
+      # source actually starts with, for the "must start with one of" message:
+      # the type name (`:sequence`) is not what a user types.
+      #
+      # A direction glyph needs no gap after the flowchart keyword. mmdc
+      # draws `graph>`, `graph<` and `graph^`, and the grammar takes them.
+      # Detection used to demand whitespace, so those headers died here
+      # with DiagramTypeError before the parser saw the line.
+      #
+      # The `-elk` suffix is deliberately excluded from the outer `/i`: mmdc's
+      # own detector (`/^\s*flowchart-elk/`, no `i` flag) only recognises the
+      # lowercase spelling, while its bare `flowchart`/`graph` detector is
+      # also case-sensitive but Etassia already treats those case-insensitively
+      # (pre-existing, unrelated to this suffix). Matching the outer `/i` to
+      # `-elk` too let `flowchart-ELK` reach detection as a flowchart, then
+      # fail in the grammar (which only defines lowercase `flowchart-elk`)
+      # with ParseError instead of the DiagramTypeError an unsupported header
+      # should raise.
+      TYPES = {
+        flowchart: {
+          pattern: /\A\s*(?:flowchart-elk|(?i:graph|flowchart))([\s<>^]|\z)/,
+          keyword: "graph, flowchart, or flowchart-elk",
+          ir_adapter: true,
+        },
+        sequence: {
+          pattern: /\A\s*sequenceDiagram/i,
+          keyword: "sequenceDiagram",
+          ir_adapter: true,
+        },
+        class_diagram: {
+          pattern: /\A\s*classDiagram/i,
+          keyword: "classDiagram",
+          ir_adapter: true,
+        },
+        state_diagram: {
+          pattern: /\A\s*stateDiagram(-v2)?/i,
+          keyword: "stateDiagram or stateDiagram-v2",
+          ir_adapter: true,
+        },
+        er_diagram: {
+          pattern: /\A\s*erDiagram/i,
+          keyword: "erDiagram",
+          ir_adapter: true,
+        },
+        user_journey: {
+          pattern: /\A\s*journey/i,
+          keyword: "journey",
+          ir_adapter: true,
+        },
+        gantt: {
+          pattern: /\A\s*gantt(\s|\z)/i,
+          keyword: "gantt",
+          ir_adapter: true,
+        },
+        pie: {
+          pattern: /\A\s*pie(\s|\z)/i,
+          keyword: "pie",
+          ir_adapter: true,
+        },
+        timeline: {
+          pattern: /\A\s*timeline(\s|$)/i,
+          keyword: "timeline",
+          ir_adapter: true,
+        },
+        quadrant: {
+          pattern: /\A\s*quadrantChart/i,
+          keyword: "quadrantChart",
+          ir_adapter: true,
+        },
+        git_graph: {
+          pattern: /\A\s*gitGraph/i,
+          keyword: "gitGraph",
+          ir_adapter: true,
+        },
+        mindmap: {
+          pattern: /\A\s*mindmap/i,
+          keyword: "mindmap",
+          ir_adapter: true,
+        },
+        kanban: {
+          pattern: /\A\s*kanban/i,
+          keyword: "kanban",
+          ir_adapter: true,
+        },
+        radar: {
+          pattern: /\A\s*radar-beta/i,
+          keyword: "radar-beta",
+          ir_adapter: true,
+        },
+        block: {
+          pattern: /\A\s*block-beta/i,
+          keyword: "block-beta",
+          ir_adapter: true,
+        },
+        requirement: {
+          pattern: /\A\s*requirementDiagram/i,
+          keyword: "requirementDiagram",
+          ir_adapter: true,
+        },
+        xychart: {
+          pattern: /\A\s*xychart-beta/i,
+          keyword: "xychart-beta",
+          name: "XyChart",
+          ir_adapter: true,
+        },
+        architecture: {
+          pattern: /\A\s*architecture-beta/i,
+          keyword: "architecture-beta",
+          ir_adapter: true,
+        },
+        sankey: {
+          pattern: /\A\s*sankey-beta/i,
+          keyword: "sankey-beta",
+          ir_adapter: true,
+        },
+        packet: {
+          pattern: /\A\s*packet-beta/i,
+          keyword: "packet-beta",
+          ir_adapter: true,
+        },
+        treemap: {
+          pattern: /\A\s*treemap(-beta)?/i,
+          keyword: "treemap or treemap-beta",
+          ir_adapter: true,
+        },
+        c4: {
+          pattern: /\A\s*(C4Context|C4Container|C4Component|C4Dynamic|
+            C4Deployment|C4\s+diagram)/ix,
+          keyword: "C4Context, C4Container, C4Component, C4Dynamic, " \
+                   "C4Deployment, or a C4 diagram",
+          ir_adapter: true,
+        },
+        info: {
+          pattern: /\A\s*info/i,
+          keyword: "info",
+          ir_adapter: true,
+        },
+        error: {
+          pattern: /\A\s*(error|Error)/i,
+          keyword: "error",
+          ir_adapter: true,
+        },
+      }.freeze
+
+      # @deprecated Read {TYPES}; kept because specs and callers use these.
+      DIAGRAM_TYPE_PATTERNS =
+        TYPES.transform_values { |row| row[:pattern] }.freeze
+
+      # @deprecated Read {TYPES}.
+      DIAGRAM_TYPE_KEYWORDS =
+        TYPES.transform_values { |row| row[:keyword] }.freeze
+
+      # An empty preamble item — a bare `%%`, or a `%%{...}%%` with no
+      # directive header — is not universally invalid. Every type was probed
+      # with both, and these eight refuse both.
+      REFUSES_BARE_COMMENT = %i[
+        flowchart er_diagram user_journey gantt timeline block
+        sankey requirement
+      ].freeze
+      private_constant :REFUSES_BARE_COMMENT
+
+      # stateDiagram is the odd one out: it draws a bare `%%` and refuses a
+      # directive with no header.
+      REFUSES_HEADERLESS_DIRECTIVE = (
+        REFUSES_BARE_COMMENT + [:state_diagram]
+      ).freeze
+      private_constant :REFUSES_HEADERLESS_DIRECTIVE
+
+      # A fence that is not the first thing in the file is not frontmatter
+      # to mermaid. It stays in the text, and the diagram's own parser meets
+      # it: these seventeen stop on it, and pie, gitGraph, radar,
+      # architecture, packet and info skip the lines and draw the diagram.
+      REFUSES_LATE_FRONTMATTER = %i[
+        flowchart sequence class_diagram state_diagram er_diagram
+        user_journey gantt timeline quadrant mindmap kanban
+        block requirement xychart sankey treemap c4
+      ].freeze
+      private_constant :REFUSES_LATE_FRONTMATTER
+
+      # What each preamble item mermaid cannot make sense of costs, and how
+      # to say so.
+      REFUSED_PREAMBLE = {
+        comment: ["an empty comment", REFUSES_BARE_COMMENT],
+        directive: ["a directive with no header", REFUSES_HEADERLESS_DIRECTIVE],
+        frontmatter: [
+          "frontmatter behind another item",
+          REFUSES_LATE_FRONTMATTER,
+        ],
+      }.freeze
+      private_constant :REFUSED_PREAMBLE
+
+      EXTENSIONS = [".mmd"].freeze
+      private_constant :EXTENSIONS
+
+      FRONTMATTER_LAYOUT_ENGINES = {
+        "dagre" => :grid,
+        "elk" => :elk,
+      }.freeze
+      FLOWCHART_ELK_HEADER = /\A\s*flowchart-elk(?:[\s<>^]|\z)/
+      private_constant :FRONTMATTER_LAYOUT_ENGINES, :FLOWCHART_ELK_HEADER
+
+      # @return [Symbol]
+      def id
+        :mermaid
+      end
+
+      # @return [Array<String>] file extensions this notation reads
+      def extensions
+        EXTENSIONS
+      end
+
+      # Whether the source, past its preamble, opens with a Mermaid type
+      # keyword. `Source.split` accepts any String, binary and invalid UTF-8
+      # included.
+      #
+      # @param source [String]
+      # @return [Boolean]
+      def claims?(source)
+        !matching_type(Source.split(source)[:body]).nil?
+      end
+
+      # @return [Hash, nil] the classes serving a type, nil when not in
+      #   {TYPES}
+      def type_handlers(type)
+        return unless type_registered?(type)
+
+        {
+          parser: layer_class(Parser, type, Parser::ParseError),
+          transform: layer_class(Layout, type, Layout::LayoutError),
+          renderer: layer_class(Renderer, type, Renderer::RenderError),
+          model: layer_class(Diagram, type, Parser::ParseError),
+        }
+      end
+
+      # @return [Array<Symbol>] the diagram types, in detection order
+      def types
+        TYPES.keys
+      end
+
+      def type_registered?(type)
+        TYPES.key?(type)
+      end
+
+      # The class a layer module holds for a type, by naming convention.
+      #
+      # @param layer [Module] Parser, Layout, Renderer or Diagram
+      # @param error [Class] raised when the class does not exist, so a broken
+      #   lookup fails as that layer and never as a bare NameError
+      # @raise [Engine::DiagramTypeError] when the type is not in {TYPES}
+      def layer_class(layer, type, error)
+        row = TYPES.fetch(type) do
+          raise Engine::DiagramTypeError, "Unknown diagram type: #{type}"
+        end
+        name = row[:name] || type.to_s.split("_").map(&:capitalize).join
+        return layer.const_get(name, false) if layer.const_defined?(name, false)
+
+        raise error, "No #{layer}::#{name} class for diagram type: #{type}"
+      end
+
+      # Parses Mermaid source into a {Parsed}.
+      #
+      # @param source [String] Mermaid source
+      # @param logger [#debug, nil] receives the progress lines the engine
+      #   prints under `verbose`
+      # @raise [Engine::DiagramTypeError] when the source is not Mermaid or
+      #   its type has no handlers
+      # @raise [Engine::PipelineError] when the preamble is degenerate
+      def parse(source, logger: nil)
+        preamble = Source.split(source)
+        frontmatter = parsed_frontmatter(preamble[:frontmatter])
+        type = detect_type(preamble[:body])
+        logger&.debug("Detected diagram type: #{type}")
+        reject_degenerate_preamble(type, preamble[:degenerate])
+        diagram = adapted_diagram(type, preamble, frontmatter, source, logger)
+        parsed(type, diagram,
+               layout_engine(frontmatter, preamble[:body]))
+      end
+
+      def adapted_diagram(type, preamble, frontmatter, source, logger)
+        diagram = parse_diagram(type, preamble, frontmatter&.title, logger)
+        IRAdapter.call(type, with_wrap(type, diagram, source))
+      end
+
+      def parsed(type, diagram, layout_engine = nil)
+        Parsed.new(type: type, diagram: diagram,
+                   transform: layer_class(Layout, type, Layout::LayoutError),
+                   renderer: layer_class(Renderer, type, Renderer::RenderError),
+                   layout_engine: layout_engine)
+      end
+
+      # @return [Symbol] the first type whose pattern matches the body
+      def detect_type(source)
+        type = matching_type(source)
+        return type if type
+
+        raise Engine::DiagramTypeError,
+              "Unable to detect diagram type from source. " \
+              "Source must start with one of: #{registered_type_names}"
+      end
+
+      private
+
+      def parsed_frontmatter(source)
+        Source::Frontmatter.new(source) if source
+      end
+
+      def layout_engine(frontmatter, body)
+        return :elk if body.match?(FLOWCHART_ELK_HEADER)
+
+        FRONTMATTER_LAYOUT_ENGINES[frontmatter&.config_layout]
+      end
+
+      def matching_type(body)
+        TYPES.each do |type, row|
+          return type if body.match?(row[:pattern])
+        end
+        nil
+      end
+
+      def with_wrap(type, diagram, source)
+        diagram.wrap = true if sequence_wrap?(type, source)
+        diagram
+      end
+
+      def sequence_wrap?(type, source)
+        type == :sequence && Diagram::SequenceWrap.on?(source)
+      end
+
+      def parse_diagram(type, preamble, title, logger)
+        logger&.debug("Retrieved handlers for #{type}")
+        logger&.debug("Parsing diagram...")
+        diagram = parse_body(type, preamble)
+        apply_class_font(type, diagram, preamble)
+        logger&.debug("Parse complete: #{diagram.class.name}")
+        diagram.title = title if title && diagram.title.nil?
+        diagram
+      end
+
+      def apply_class_font(type, diagram, preamble)
+        return unless type == :class_diagram
+
+        diagram.font_family =
+          ClassDiagramConfig.font_family(preamble[:directives])
+      end
+
+      def parse_body(type, preamble)
+        parser = Parser.for(type)
+        return parser.parse(preamble[:body]) unless type == :git_graph
+
+        parser.parse(
+          preamble[:body],
+          main_branch_name: GitGraphConfig.main_branch_name(
+            preamble[:directives],
+          ),
+        )
+      end
+
+      def registered_type_names
+        types.sort.map { |type| DIAGRAM_TYPE_KEYWORDS.fetch(type, type.to_s) }
+          .join(", ")
+      end
+
+      def reject_degenerate_preamble(diagram_type, degenerate)
+        kind = degenerate.find do |item|
+          REFUSED_PREAMBLE.fetch(item).last.include?(diagram_type)
+        end
+        return unless kind
+
+        raise Engine::PipelineError,
+              "A #{diagram_type} diagram does not accept " \
+              "#{REFUSED_PREAMBLE.fetch(kind).first}."
+      end
+    end
+  end
+end

data/lib/etassia/notation/parsed.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    # What a notation's `parse` hands to the engine: the detected type, the
+    # parsed diagram model, and the classes that lay it out and draw it.
+    class Parsed
+      attr_reader :type, :diagram, :transform, :renderer, :layout_engine, :name
+
+      def initialize(type:, diagram:, transform:, renderer:,
+                     layout_engine: nil)
+        @type = type
+        @diagram = diagram
+        @transform = transform
+        @renderer = renderer
+        @layout_engine = layout_engine
+        freeze
+      end
+
+      # @param name [String, nil] what the source's opener named the
+      #   diagram (PlantUML's `@startuml foo`); untrusted text that never
+      #   changes the drawing
+      # @return [Parsed] a copy of this result carrying `name`
+      def with_name(name)
+        copy = clone(freeze: false)
+        copy.instance_variable_set(:@name, name)
+        copy.freeze
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/arrow_head.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # The triangle at the end of an edge.
+        module ArrowHead
+          module_function
+
+          LENGTH = 9.0
+          HALF_WIDTH = 3.5
+          private_constant :LENGTH, :HALF_WIDTH
+
+          # @param segment [Array<Array(Float, Float)>] the last two
+          #   points of the edge
+          # @return [Array<Array(Float, Float)>] tip, then the two corners
+          def points(segment)
+            tip = segment.last
+            unit = unit_vector(segment)
+            [tip, *corners(tip, unit)]
+          end
+
+          def corners(tip, unit)
+            base = shifted(tip, unit, -LENGTH)
+            side = [-unit.last, unit.first]
+            [shifted(base, side, HALF_WIDTH), shifted(base, side, -HALF_WIDTH)]
+          end
+
+          def unit_vector(segment)
+            run = segment.last.first - segment.first.first
+            rise = segment.last.last - segment.first.last
+            length = Math.hypot(run, rise)
+            [run / length, rise / length]
+          end
+
+          def shifted(base, vector, scale)
+            [base.first + (scale * vector.first),
+             base.last + (scale * vector.last)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/arrow_style.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Reads the `[#blue,dashed]` part of an arrow.
+        module ArrowStyle
+          module_function
+
+          STYLES = { "dashed" => :dashed, "dotted" => :dotted,
+                     "bold" => :bold, "plain" => nil }.freeze
+          HEX = /\A(?:\h{3}|\h{6})\z/
+          private_constant :STYLES, :HEX
+
+          # @return [Hash] `:colour` and `:style`, either possibly nil
+          def parse(spec, line:)
+            result = { colour: nil, style: nil }
+            spec.to_s.split(",").map(&:strip).each do |word|
+              apply(result, word, line, spec)
+            end
+            result
+          end
+
+          # `#pink` is a colour name, `#ccf` and `#33668E` are hex.
+          # @return [String, nil]
+          def colour(word)
+            name = word.delete_prefix("#")
+            return nil if name.empty?
+
+            HEX.match?(name) ? "##{name}" : name
+          end
+
+          def apply(result, word, line, spec)
+            if word.start_with?("#")
+              result[:colour] = colour(word)
+            elsif STYLES.key?(word.downcase)
+              result[:style] = STYLES.fetch(word.downcase)
+            else
+              raise UnsupportedConstructError.new(
+                construct: "arrow style #{word.inspect}", line: line,
+                text: spec
+              )
+            end
+          end
+          private_class_method :apply
+        end
+      end
+    end
+  end
+end