graphomaton 1.0.0 → 1.1.0

data/lib/graphomaton/exporters/webp.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+require_relative 'svg'
+
+class Graphomaton
+  module Exporters
+    class Webp
+      include Graphomaton::ExporterIntrospection
+      class ConversionError < Graphomaton::ConversionError; end
+
+      DEFAULT_CONVERTER = :auto
+      DEFAULT_TIMEOUT = ProcessRunner::DEFAULT_TIMEOUT
+      DEFAULT_MAX_OUTPUT_BYTES = ProcessRunner::DEFAULT_MAX_STDOUT_BYTES
+      PNG_SIGNATURE = "\x89PNG\r\n\x1A\n".b.freeze
+
+      CONVERTER_COMMANDS = {
+        rsvg_magick: [
+          ['rsvg-convert', '--format', 'png', '-'],
+          ['magick', 'png:-', 'webp:-']
+        ],
+        magick: ['magick', 'svg:-', 'webp:-'],
+        convert: ['convert', 'svg:-', 'webp:-']
+      }.freeze
+      CONVERTER_OPTIONS = ([:auto] + CONVERTER_COMMANDS.keys).freeze
+
+      def self.available?(converter: DEFAULT_CONVERTER)
+        !available_command(converter: converter).nil?
+      end
+
+      def self.available_command(converter: DEFAULT_CONVERTER)
+        resolved_converter = resolve_converter(converter)
+        if resolved_converter != :auto
+          command = CONVERTER_COMMANDS[resolved_converter]
+          return command if command_available?(command)
+        end
+        return nil if resolved_converter != :auto
+
+        CONVERTER_COMMANDS.values.find { |command| command_available?(command) }
+      end
+
+      def initialize(automaton)
+        @automaton = automaton
+      end
+
+      def export(width = 800, height = 600, theme: Svg::DEFAULT_THEME, converter: DEFAULT_CONVERTER,
+                 timeout: DEFAULT_TIMEOUT, max_output_bytes: DEFAULT_MAX_OUTPUT_BYTES, **svg_options)
+        export_result(
+          width,
+          height,
+          theme: theme,
+          converter: converter,
+          timeout: timeout,
+          max_output_bytes: max_output_bytes,
+          **svg_options
+        ).output
+      end
+
+      def export_result(width = 800, height = 600, theme: Svg::DEFAULT_THEME, converter: DEFAULT_CONVERTER,
+                        timeout: DEFAULT_TIMEOUT, max_output_bytes: DEFAULT_MAX_OUTPUT_BYTES, **svg_options)
+        command = available_command(converter: converter)
+        raise ConversionError, missing_converter_message(converter) unless command
+
+        svg_result = Svg.new(@automaton).export_result(width, height, theme: theme, **svg_options)
+        webp, error, status = run_conversion(
+          command,
+          svg_result.output,
+          timeout: timeout,
+          max_output_bytes: max_output_bytes
+        )
+        webp = webp.b
+
+        if status.success? && webp?(webp)
+          return RenderResult.new(
+            output: webp.freeze,
+            diagnostics: svg_result.diagnostics,
+            bounds: svg_result.bounds,
+            layout: svg_result.layout
+          )
+        end
+        raise ConversionError, invalid_webp_message(command, error) if status.success?
+
+        raise ConversionError, failed_conversion_message(command, error)
+      rescue ProcessRunner::Error => e
+        raise ConversionError, failed_conversion_message(command, e.message)
+      end
+
+      private
+
+      def available_command(converter: DEFAULT_CONVERTER)
+        self.class.available_command(converter: converter)
+      end
+
+      def self.executable?(command)
+        !ProcessRunner.which(command).nil?
+      end
+
+      def self.command_available?(command)
+        stages = command.first.is_a?(Array) ? command : [command]
+        stages.all? { |stage| executable?(stage.first) }
+      end
+
+      def self.resolve_converter(converter)
+        resolved = converter.to_sym
+        return resolved if CONVERTER_OPTIONS.include?(resolved)
+
+        raise ArgumentError, "Unknown WebP converter: #{converter.inspect}. Available converters: #{CONVERTER_OPTIONS.join(', ')}"
+      end
+
+      def webp?(data)
+        data.start_with?('RIFF') && data.byteslice(8, 4) == 'WEBP'
+      end
+
+      def run_conversion(command, svg, timeout:, max_output_bytes:)
+        unless command.first.is_a?(Array)
+          return ProcessRunner.capture3(
+            *command,
+            stdin_data: svg,
+            binmode: true,
+            timeout: timeout,
+            max_stdout_bytes: max_output_bytes
+          )
+        end
+
+        raster_command, webp_command = command
+        png, raster_error, raster_status = ProcessRunner.capture3(
+          *raster_command,
+          stdin_data: svg,
+          binmode: true,
+          timeout: timeout,
+          max_stdout_bytes: max_output_bytes
+        )
+        unless raster_status.success? && png.b.start_with?(PNG_SIGNATURE)
+          detail = raster_error.to_s.strip
+          detail = 'converter did not produce PNG data' if detail.empty?
+          raise ConversionError, "Failed to rasterize SVG using #{raster_command.first}: #{detail}"
+        end
+
+        ProcessRunner.capture3(
+          *webp_command,
+          stdin_data: png,
+          binmode: true,
+          timeout: timeout,
+          max_stdout_bytes: max_output_bytes
+        )
+      end
+
+      def missing_converter_message(converter)
+        resolved_converter = self.class.resolve_converter(converter)
+        required = if resolved_converter == :auto
+                     'magick or convert (optionally with rsvg-convert)'
+                   else
+                     CONVERTER_COMMANDS[resolved_converter].first
+                   end
+
+        "WebP export requires #{required} to be installed. #{install_hint}"
+      end
+
+      def install_hint
+        'Install hints: macOS: brew install imagemagick librsvg; Debian/Ubuntu: apt install imagemagick librsvg2-bin; Windows: install ImageMagick.'
+      end
+
+      def failed_conversion_message(command, error)
+        detail = error.to_s.strip
+        detail = 'unknown error' if detail.empty?
+
+        "Failed to convert SVG to WebP using #{converter_name(command)}: #{detail}"
+      end
+
+      def invalid_webp_message(command, error)
+        detail = error.to_s.strip
+        return "Failed to convert SVG to WebP using #{converter_name(command)}: converter did not produce WebP data" if detail.empty?
+
+        "Failed to convert SVG to WebP using #{converter_name(command)}: converter did not produce WebP data (#{detail})"
+      end
+
+      def converter_name(command)
+        return command.first unless command.first.is_a?(Array)
+
+        command.map(&:first).join(' + ')
+      end
+    end
+  end
+end

data/lib/graphomaton/exporters.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'exporters/svg'
-require_relative 'exporters/mermaid'
-require_relative 'exporters/dot'
-require_relative 'exporters/plantuml'
+class Graphomaton
+  module Exporters
+    autoload :Svg, File.expand_path('exporters/svg', __dir__)
+    autoload :Png, File.expand_path('exporters/png', __dir__)
+    autoload :Pdf, File.expand_path('exporters/pdf', __dir__)
+    autoload :Webp, File.expand_path('exporters/webp', __dir__)
+    autoload :Mermaid, File.expand_path('exporters/mermaid', __dir__)
+    autoload :Dot, File.expand_path('exporters/dot', __dir__)
+    autoload :Plantuml, File.expand_path('exporters/plantuml', __dir__)
+  end
+end

data/lib/graphomaton/identifier_allocator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Graphomaton
+  # Assigns deterministic, collision-free identifiers within one export.
+  class IdentifierAllocator
+    def initialize(reserved: [])
+      @identifiers = {}
+      @used = reserved.to_h { |identifier| [identifier.to_s, true] }
+      @counters = Hash.new(0)
+    end
+
+    def allocate(key, preferred: nil, prefix: 'id')
+      return @identifiers[key] if @identifiers.key?(key)
+
+      candidate = preferred.to_s unless preferred.nil?
+      candidate = nil if candidate&.empty? || @used.key?(candidate)
+      candidate ||= next_identifier(prefix)
+
+      @used[candidate] = true
+      @identifiers[key] = candidate
+    end
+
+    private
+
+    def next_identifier(prefix)
+      loop do
+        @counters[prefix] += 1
+        candidate = "#{prefix}_#{@counters[prefix]}"
+        return candidate unless @used.key?(candidate)
+      end
+    end
+  end
+end

data/lib/graphomaton/input_policy.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class Graphomaton
+  # Validates untrusted model input before it reaches exporters or graph analysis.
+  class InputPolicy
+    XML_INVALID_CHARACTERS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\uFFFE\uFFFF]/
+    TOP_LEVEL_KEYS = %i[version states transitions initial initial_state final final_states].freeze
+    STATE_KEYS = %i[id name x y label style metadata shape kind initial final accepting].freeze
+    TRANSITION_KEYS = %i[from to label style metadata line_style].freeze
+
+    def self.text!(value, context:, max_bytes: nil)
+      return value unless value.is_a?(String)
+
+      unless value.encoding == Encoding::UTF_8 ? value.valid_encoding? : value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+        raise ArgumentError, "#{context} must be valid UTF-8"
+      end
+      utf8 = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
+      raise ArgumentError, "#{context} contains characters that are invalid in XML" if utf8.match?(XML_INVALID_CHARACTERS)
+      if max_bytes && utf8.bytesize > max_bytes
+        raise ArgumentError, "#{context} exceeds max_label_length (#{max_bytes})"
+      end
+
+      value
+    end
+
+    def self.identifier!(value, context:)
+      raise ArgumentError, "#{context} cannot be nil" if value.nil?
+
+      text!(value, context: context)
+      value
+    end
+
+    def self.label!(value, context:, max_bytes: nil)
+      if value.is_a?(Hash) || value.is_a?(Array)
+        raise ArgumentError, "#{context} must be scalar text or a Graphomaton::Label"
+      end
+
+      text!(value.to_s, context: context, max_bytes: max_bytes) unless value.nil?
+      value
+    end
+
+    def self.mapping!(value, context:)
+      return value if value.nil? || value.is_a?(Hash)
+
+      raise ArgumentError, "#{context} must be a Hash"
+    end
+
+    def self.boolean!(value, context:)
+      return value if value == true || value == false || value.nil?
+
+      raise ArgumentError, "#{context} must be true or false"
+    end
+
+    def self.known_keys!(hash, allowed, context:, strict:)
+      return unless strict
+
+      unknown = hash.keys.reject { |key| allowed.include?(key.to_s.to_sym) }
+      return if unknown.empty?
+
+      raise ArgumentError, "Unknown #{context} keys: #{unknown.join(', ')}"
+    end
+
+    def self.nested_depth!(value, maximum:, context:, max_string_bytes: nil)
+      raise ArgumentError, 'max_metadata_depth must be a positive Integer' unless maximum.is_a?(Integer) && maximum.positive?
+
+      stack = [[value, 1]]
+      visited = {}
+      until stack.empty?
+        current, depth = stack.pop
+        text!(current, context: context, max_bytes: max_string_bytes) if current.is_a?(String)
+        next unless current.is_a?(Hash) || current.is_a?(Array)
+        next if visited[current.object_id]
+
+        raise ArgumentError, "#{context} exceeds max_metadata_depth (#{maximum})" if depth > maximum
+
+        visited[current.object_id] = true
+        children = current.is_a?(Hash) ? current.flat_map { |key, item| [key, item] } : current
+        children.each { |child| stack << [child, depth + 1] }
+      end
+    end
+  end
+end

data/lib/graphomaton/layout/force_tree.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+class Graphomaton
+  module Layout
+    class ForceTree
+      DEFAULT_THETA = 0.6
+      LEAF_CAPACITY = 4
+      MAX_DEPTH = 20
+
+      Node = Struct.new(
+        :left, :top, :size, :mass, :center_x, :center_y, :points, :children,
+        keyword_init: true
+      )
+
+      def initialize(positions)
+        @root = build_root(positions)
+        positions.each { |name, position| insert(@root, name, position, 0) }
+      end
+
+      def force_on(name, position, coefficient, theta: DEFAULT_THETA, &coincident_delta)
+        force_from_node(@root, name, position, coefficient.to_f, theta.to_f, coincident_delta)
+      end
+
+      private
+
+      def build_root(positions)
+        coordinates = positions.values
+        return Node.new(left: 0.0, top: 0.0, size: 1.0, mass: 0, center_x: 0.0, center_y: 0.0, points: []) if coordinates.empty?
+
+        xs = coordinates.map { |position| position[:x].to_f }
+        ys = coordinates.map { |position| position[:y].to_f }
+        min_x, max_x = xs.minmax
+        min_y, max_y = ys.minmax
+        size = [max_x - min_x, max_y - min_y, 1.0].max
+        Node.new(left: min_x, top: min_y, size: size, mass: 0, center_x: 0.0, center_y: 0.0, points: [])
+      end
+
+      def insert(node, name, position, depth)
+        x = position[:x].to_f
+        y = position[:y].to_f
+        previous_mass = node.mass
+        node.mass += 1
+        node.center_x = ((node.center_x * previous_mass) + x) / node.mass
+        node.center_y = ((node.center_y * previous_mass) + y) / node.mass
+
+        if node.children
+          insert(child_for(node, x, y), name, position, depth + 1)
+        elsif node.points.size < LEAF_CAPACITY || depth >= MAX_DEPTH
+          node.points << [name, position]
+        else
+          existing = node.points
+          node.points = []
+          node.children = subdivide(node)
+          existing.each { |point_name, point| insert_without_mass(child_for(node, point[:x], point[:y]), point_name, point, depth + 1) }
+          insert_without_mass(child_for(node, x, y), name, position, depth + 1)
+        end
+      end
+
+      def insert_without_mass(node, name, position, depth)
+        insert(node, name, position, depth)
+      end
+
+      def subdivide(node)
+        half = node.size / 2.0
+        [
+          Node.new(left: node.left, top: node.top, size: half, mass: 0, center_x: 0.0, center_y: 0.0, points: []),
+          Node.new(left: node.left + half, top: node.top, size: half, mass: 0, center_x: 0.0, center_y: 0.0, points: []),
+          Node.new(left: node.left, top: node.top + half, size: half, mass: 0, center_x: 0.0, center_y: 0.0, points: []),
+          Node.new(left: node.left + half, top: node.top + half, size: half, mass: 0, center_x: 0.0, center_y: 0.0, points: [])
+        ]
+      end
+
+      def child_for(node, x, y)
+        horizontal = x.to_f >= node.left + (node.size / 2.0) ? 1 : 0
+        vertical = y.to_f >= node.top + (node.size / 2.0) ? 1 : 0
+        node.children[(vertical * 2) + horizontal]
+      end
+
+      def force_from_node(node, name, position, coefficient, theta, coincident_delta)
+        return [0.0, 0.0] if node.mass.zero?
+
+        if node.children.nil?
+          return node.points.each_with_object([0.0, 0.0]) do |(other_name, other_position), force|
+            next if other_name == name
+
+            delta_x = position[:x].to_f - other_position[:x].to_f
+            delta_y = position[:y].to_f - other_position[:y].to_f
+            if delta_x.zero? && delta_y.zero?
+              delta_x, delta_y = coincident_delta.call(name, other_name)
+            end
+            add_repulsion(force, delta_x, delta_y, coefficient, 1)
+          end
+        end
+
+        delta_x = position[:x].to_f - node.center_x
+        delta_y = position[:y].to_f - node.center_y
+        distance = Math.hypot(delta_x, delta_y)
+        contains_target = contains?(node, position[:x].to_f, position[:y].to_f)
+        if !contains_target && distance.positive? && (node.size / distance) < theta
+          force = [0.0, 0.0]
+          add_repulsion(force, delta_x, delta_y, coefficient, node.mass)
+          return force
+        end
+
+        node.children.each_with_object([0.0, 0.0]) do |child, force|
+          child_force = force_from_node(child, name, position, coefficient, theta, coincident_delta)
+          force[0] += child_force[0]
+          force[1] += child_force[1]
+        end
+      end
+
+      def contains?(node, x, y)
+        x >= node.left && x <= node.left + node.size && y >= node.top && y <= node.top + node.size
+      end
+
+      def add_repulsion(force, delta_x, delta_y, coefficient, mass)
+        distance = Math.hypot(delta_x, delta_y)
+        return force unless distance.positive?
+
+        magnitude = coefficient * mass / distance
+        force[0] += (delta_x / distance) * magnitude
+        force[1] += (delta_y / distance) * magnitude
+        force
+      end
+    end
+  end
+end

data/lib/graphomaton/model.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'set'
+
+class Graphomaton
+  module ModelValue
+    def self.copy(value, copies = {})
+      case value
+      when Hash
+        return copies[value.object_id] if copies.key?(value.object_id)
+
+        duplicate = {}
+        copies[value.object_id] = duplicate
+        value.each { |key, item| duplicate[copy(key, copies)] = copy(item, copies) }
+        duplicate.freeze
+      when Array
+        return copies[value.object_id] if copies.key?(value.object_id)
+
+        duplicate = []
+        copies[value.object_id] = duplicate
+        value.each { |item| duplicate << copy(item, copies) }
+        duplicate.freeze
+      when Set
+        return copies[value.object_id] if copies.key?(value.object_id)
+
+        duplicate = Set.new
+        copies[value.object_id] = duplicate
+        value.each { |item| duplicate << copy(item, copies) }
+        duplicate.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+  end
+  private_constant :ModelValue
+
+  Label = Data.define(:kind, :value) do
+    KINDS = %i[text symbols epsilon uml].freeze
+
+    def initialize(kind:, value: nil)
+      resolved_kind = kind.to_sym
+      raise ArgumentError, "Unknown label kind: #{kind.inspect}" unless KINDS.include?(resolved_kind)
+
+      normalized_value = case resolved_kind
+                         when :text
+                           value.to_s
+                         when :symbols
+                           symbols = Array(value).map(&:to_s)
+                           raise ArgumentError, 'Symbol label requires at least one symbol' if symbols.empty?
+
+                           symbols
+                         when :epsilon
+                           value.nil? ? Graphomaton::DEFAULT_EPSILON_LABEL : value.to_s
+                         when :uml
+                           raise ArgumentError, 'UML label value must be a Hash' unless value.is_a?(Hash)
+
+                           uml_value = {
+                             event: value.key?(:event) ? value[:event] : value['event'],
+                             guard: value.key?(:guard) ? value[:guard] : value['guard'],
+                             action: value.key?(:action) ? value[:action] : value['action']
+                           }.compact
+                           raise ArgumentError, 'UML label requires an event' unless uml_value.key?(:event)
+
+                           uml_value
+                         end
+      super(kind: resolved_kind, value: ModelValue.copy(normalized_value))
+    end
+
+    def self.text(value)
+      new(kind: :text, value: value)
+    end
+
+    def self.symbols(*values)
+      new(kind: :symbols, value: values.flatten)
+    end
+
+    def self.epsilon(display = Graphomaton::DEFAULT_EPSILON_LABEL)
+      new(kind: :epsilon, value: display)
+    end
+
+    def self.uml(event:, guard: nil, action: nil)
+      new(kind: :uml, value: { event: event, guard: guard, action: action }.compact)
+    end
+
+    def to_s
+      case kind
+      when :symbols
+        value.join(', ')
+      when :epsilon
+        value
+      when :uml
+        event = value.fetch(:event).to_s
+        guard = value[:guard] ? " [#{value[:guard]}]" : ''
+        action = value[:action] ? " / #{value[:action]}" : ''
+        "#{event}#{guard}#{action}"
+      else
+        value.to_s
+      end
+    end
+
+    def to_h
+      { type: kind, value: value }.compact
+    end
+  end
+
+  State = Data.define(:id, :x, :y, :label, :style, :metadata, :shape, :kind) do
+    MISSING = Object.new.freeze
+
+    def initialize(id:, x:, y:, label:, style:, metadata:, shape:, kind:)
+      super(
+        id: ModelValue.copy(id),
+        x: x,
+        y: y,
+        label: ModelValue.copy(label),
+        style: ModelValue.copy(style),
+        metadata: ModelValue.copy(metadata),
+        shape: ModelValue.copy(shape),
+        kind: kind.nil? ? nil : kind.to_sym
+      )
+    end
+
+    def [](key)
+      return id if key == :name || key == :id
+
+      public_send(key)
+    rescue NoMethodError
+      nil
+    end
+
+    def fetch(key, default = MISSING)
+      value = self[key]
+      return value unless value.nil?
+      return default unless default.equal?(MISSING)
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    def to_h
+      output = { name: id, x: x, y: y }
+      output[:label] = label unless label.nil?
+      output[:style] = style unless style.nil?
+      output[:metadata] = metadata unless metadata.nil?
+      output[:shape] = shape unless shape.nil?
+      output[:kind] = kind unless kind.nil?
+      output
+    end
+  end
+
+  Transition = Data.define(:id, :from, :to, :label, :style, :metadata, :line_style) do
+    def initialize(id:, from:, to:, label:, style:, metadata:, line_style:)
+      super(
+        id: id,
+        from: ModelValue.copy(from),
+        to: ModelValue.copy(to),
+        label: ModelValue.copy(label),
+        style: ModelValue.copy(style),
+        metadata: ModelValue.copy(metadata),
+        line_style: ModelValue.copy(line_style)
+      )
+    end
+
+    def [](key)
+      public_send(key)
+    rescue NoMethodError
+      nil
+    end
+
+    def to_h
+      output = { from: from, to: to, label: label.is_a?(Label) ? label.to_s : label }
+      output[:style] = style unless style.nil?
+      output[:metadata] = metadata unless metadata.nil?
+      output[:line_style] = line_style unless line_style.nil?
+      output
+    end
+  end
+
+  Diagnostic = Data.define(:code, :severity, :path, :message, :hint) do
+    def initialize(code:, severity:, path:, message:, hint: nil)
+      super(
+        code: ModelValue.copy(code.to_s),
+        severity: severity.to_sym,
+        path: ModelValue.copy(Array(path)),
+        message: ModelValue.copy(message.to_s),
+        hint: hint.nil? ? nil : ModelValue.copy(hint.to_s)
+      )
+    end
+
+    def to_h
+      { code: code, severity: severity, path: path, message: message, hint: hint }.compact
+    end
+  end
+
+
+  RenderOptions = Data.define(:format, :width, :height, :options) do
+    def initialize(format: :svg, width: 800, height: 600, options: {})
+      super(format: format.to_sym, width: width, height: height, options: ModelValue.copy(options))
+    end
+  end
+
+  SvgOptions = Data.define(:width, :height, :options) do
+    def initialize(width: 800, height: 600, **options)
+      super(width: width, height: height, options: ModelValue.copy(options))
+    end
+  end
+
+  RenderResult = Data.define(:output, :diagnostics, :bounds, :layout) do
+    def initialize(output:, diagnostics:, bounds:, layout:)
+      super(
+        output: ModelValue.copy(output),
+        diagnostics: ModelValue.copy(Array(diagnostics)),
+        bounds: ModelValue.copy(bounds),
+        layout: ModelValue.copy(layout)
+      )
+    end
+  end
+end