sirena 0.1.0

data/lib/sirena/diagram/treemap.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Sirena
+  module Diagram
+    # Represents a treemap diagram showing hierarchical data
+    class TreemapDiagram < Base
+      attr_accessor :title, :root_nodes, :class_defs
+
+      def initialize
+        super
+        @root_nodes = []
+        @class_defs = {}
+      end
+
+      def type
+        :treemap
+      end
+
+      # Add a root-level node
+      def add_root_node(node)
+        @root_nodes << node
+      end
+
+      # Add a class definition
+      def add_class_def(name, styles)
+        @class_defs[name] = styles
+      end
+
+      # Calculate total value of all nodes
+      def total_value
+        @root_nodes.sum(&:total_value)
+      end
+    end
+
+    # Represents a node in a treemap (can be a branch or leaf)
+    class TreemapNode
+      attr_accessor :label, :value, :children, :css_class, :parent
+
+      def initialize(label, value = nil)
+        @label = label
+        @value = value&.to_f
+        @children = []
+        @css_class = nil
+        @parent = nil
+      end
+
+      # Add a child node
+      def add_child(node)
+        node.parent = self
+        @children << node
+      end
+
+      # Check if this is a leaf node (has a value)
+      def leaf?
+        !@value.nil?
+      end
+
+      # Check if this is a branch node (has children)
+      def branch?
+        !@children.empty?
+      end
+
+      # Calculate total value including children
+      def total_value
+        if leaf?
+          @value
+        elsif branch?
+          @children.sum(&:total_value)
+        else
+          0.0
+        end
+      end
+
+      # Get the depth level of this node (root = 0)
+      def depth
+        return 0 unless @parent
+
+        1 + @parent.depth
+      end
+    end
+  end
+end

data/lib/sirena/diagram/user_journey.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'base'
+
+module Sirena
+  module Diagram
+    # Represents a task in a user journey.
+    #
+    # A task has a name, score (1-5 indicating satisfaction), and a
+    # collection of actors involved in performing the task.
+    class JourneyTask < Lutaml::Model::Serializable
+      # Task name/description
+      attribute :name, :string
+
+      # Task satisfaction score (1-5 range)
+      attribute :score, :integer
+
+      # Collection of actor names involved in this task
+      attribute :actors, :string, collection: true, default: -> { [] }
+
+      # Validates the task has required fields.
+      #
+      # @return [Boolean] true if task is valid
+      def valid?
+        !name.nil? && !name.empty? &&
+          !score.nil? &&
+          score >= 1 && score <= 5 &&
+          !actors.nil? && !actors.empty?
+      end
+
+      # Returns the color for this task based on score.
+      #
+      # @return [String] color indicator (:red, :yellow, :green)
+      def score_color
+        case score
+        when 1..2
+          :red
+        when 3
+          :yellow
+        when 4..5
+          :green
+        else
+          :yellow
+        end
+      end
+    end
+
+    # Represents a section grouping in a user journey.
+    #
+    # A section groups related tasks together, representing a phase
+    # or stage in the user journey.
+    class JourneySection < Lutaml::Model::Serializable
+      # Section name/title
+      attribute :name, :string
+
+      # Collection of tasks in this section
+      attribute :tasks, JourneyTask, collection: true,
+                                     default: -> { [] }
+
+      # Validates the section has required fields.
+      #
+      # @return [Boolean] true if section is valid
+      def valid?
+        !name.nil? && !name.empty? && tasks.all?(&:valid?)
+      end
+    end
+
+    # User Journey diagram model.
+    #
+    # Represents a complete user journey diagram showing the tasks users
+    # perform, grouped into sections, with satisfaction scores and actor
+    # involvement.
+    #
+    # @example Creating a simple user journey
+    #   diagram = UserJourney.new
+    #   diagram.title = "Customer Shopping Journey"
+    #   section = JourneySection.new.tap do |s|
+    #     s.name = "Shopping"
+    #   end
+    #   task = JourneyTask.new.tap do |t|
+    #     t.name = "Browse products"
+    #     t.score = 5
+    #     t.actors = ["Customer"]
+    #   end
+    #   section.tasks << task
+    #   diagram.sections << section
+    class UserJourney < Base
+      # Optional diagram title
+      attribute :title, :string
+
+      # Collection of journey sections
+      attribute :sections, JourneySection, collection: true,
+                                           default: -> { [] }
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :user_journey
+      def diagram_type
+        :user_journey
+      end
+
+      # Validates the user journey structure.
+      #
+      # A user journey is valid if:
+      # - It has at least one section
+      # - All sections are valid
+      # - All tasks within sections are valid
+      #
+      # @return [Boolean] true if user journey is valid
+      def valid?
+        return false if sections.nil? || sections.empty?
+        return false unless sections.all?(&:valid?)
+
+        true
+      end
+
+      # Returns all tasks across all sections.
+      #
+      # @return [Array<JourneyTask>] all tasks in the journey
+      def all_tasks
+        sections.flat_map(&:tasks)
+      end
+
+      # Returns all unique actors involved in the journey.
+      #
+      # @return [Array<String>] unique actor names
+      def all_actors
+        all_tasks.flat_map(&:actors).uniq
+      end
+
+      # Finds tasks by score.
+      #
+      # @param score [Integer] the score to filter by (1-5)
+      # @return [Array<JourneyTask>] tasks with the given score
+      def tasks_by_score(score)
+        all_tasks.select { |t| t.score == score }
+      end
+
+      # Finds tasks by actor.
+      #
+      # @param actor [String] the actor name
+      # @return [Array<JourneyTask>] tasks involving the actor
+      def tasks_by_actor(actor)
+        all_tasks.select { |t| t.actors.include?(actor) }
+      end
+    end
+  end
+end

data/lib/sirena/diagram/xy_chart.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Sirena
+  module Diagram
+    # Represents an XY chart diagram (scatter/line/bar chart)
+    class XYChart < Base
+      attr_accessor :title, :x_axis, :y_axis, :datasets, :options
+
+      def initialize
+        super
+        @datasets = []
+        @options = {}
+      end
+
+      def type
+        :xychart
+      end
+
+      # Add a dataset to the chart
+      def add_dataset(dataset)
+        @datasets << dataset
+      end
+    end
+
+    # Represents an axis configuration
+    class XYAxis
+      attr_accessor :label, :values, :min, :max, :type
+
+      def initialize
+        @type = :numeric # :numeric or :categorical
+        @values = []
+      end
+
+      # Check if axis has categorical values
+      def categorical?
+        @type == :categorical
+      end
+
+      # Check if axis has numeric range
+      def numeric?
+        @type == :numeric
+      end
+
+      # Get the range of the axis
+      def range
+        if numeric?
+          [@min || 0, @max || 100]
+        else
+          [0, values.length - 1]
+        end
+      end
+    end
+
+    # Represents a dataset in an XY chart
+    class XYDataset
+      attr_accessor :id, :label, :chart_type, :values, :color
+
+      def initialize(id, label = nil, chart_type = :line)
+        @id = id
+        @label = label || id
+        @chart_type = chart_type # :line, :bar, :scatter
+        @values = []
+      end
+
+      # Add a value to the dataset
+      def add_value(value)
+        @values << value.to_f
+      end
+
+      # Set all values at once
+      def values=(vals)
+        @values = vals.map(&:to_f)
+      end
+    end
+  end
+end

data/lib/sirena/diagram.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'diagram/base'
+
+module Sirena
+  module Diagram
+  end
+end

data/lib/sirena/diagram_registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Sirena
+  # Registry for diagram type handlers.
+  #
+  # This class implements the registry pattern to manage diagram type
+  # handlers without hardcoding type checks. Each diagram type registers
+  # its parser, transform, and renderer components, which can be retrieved
+  # dynamically during diagram processing.
+  #
+  # @example Registering a diagram type
+  #   DiagramRegistry.register(
+  #     :flowchart,
+  #     parser: Parser::FlowchartGrammar,
+  #     transform: Transform::FlowchartTransform,
+  #     renderer: Renderer::FlowchartRenderer
+  #   )
+  #
+  # @example Retrieving handlers for a type
+  #   handlers = DiagramRegistry.get(:flowchart)
+  #   # => { parser: Parser::FlowchartGrammar,
+  #   #      transform: Transform::FlowchartTransform,
+  #   #      renderer: Renderer::FlowchartRenderer }
+  #
+  # @example Listing registered types
+  #   DiagramRegistry.types
+  #   # => [:flowchart, :sequence, :class_diagram]
+  class DiagramRegistry
+    @handlers = {}
+
+    class << self
+      # Registers handlers for a diagram type.
+      #
+      # @param type [Symbol] the diagram type identifier
+      # @param parser [Class] the parser class for this diagram type
+      # @param transform [Class] the transform class for this diagram type
+      # @param renderer [Class] the renderer class for this diagram type
+      # @return [Hash] the registered handler hash
+      #
+      # @example Register a new diagram type
+      #   DiagramRegistry.register(
+      #     :flowchart,
+      #     parser: Parser::FlowchartGrammar,
+      #     transform: Transform::FlowchartTransform,
+      #     renderer: Renderer::FlowchartRenderer
+      #   )
+      def register(type, parser:, transform:, renderer:)
+        @handlers[type] = {
+          parser: parser,
+          transform: transform,
+          renderer: renderer
+        }
+      end
+
+      # Retrieves handlers for a diagram type.
+      #
+      # @param type [Symbol] the diagram type identifier
+      # @return [Hash, nil] hash with :parser, :transform, and :renderer
+      #   keys, or nil if type not registered
+      #
+      # @example Get handlers for a type
+      #   handlers = DiagramRegistry.get(:flowchart)
+      #   parser_class = handlers[:parser]
+      def get(type)
+        @handlers[type]
+      end
+
+      # Returns all registered diagram types.
+      #
+      # @return [Array<Symbol>] list of registered diagram type identifiers
+      #
+      # @example List all types
+      #   DiagramRegistry.types
+      #   # => [:flowchart, :sequence, :class_diagram]
+      def types
+        @handlers.keys
+      end
+
+      # Checks if a diagram type is registered.
+      #
+      # @param type [Symbol] the diagram type identifier
+      # @return [Boolean] true if type is registered
+      #
+      # @example Check if type is registered
+      #   DiagramRegistry.registered?(:flowchart)
+      #   # => true
+      def registered?(type)
+        @handlers.key?(type)
+      end
+
+      # Clears all registered handlers.
+      #
+      # This method is primarily useful for testing purposes.
+      #
+      # @return [Hash] empty handler hash
+      def clear
+        @handlers = {}
+      end
+    end
+  end
+end

data/lib/sirena/engine.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module Sirena
+  # Orchestrates the complete diagram rendering pipeline.
+  #
+  # The Engine class coordinates the parse → transform → layout → render
+  # pipeline for converting Mermaid source code into SVG output. It handles
+  # diagram type detection, retrieves appropriate handlers from the registry,
+  # and manages error handling throughout the process.
+  #
+  # @example Render a flowchart
+  #   engine = Sirena::Engine.new
+  #   svg = engine.render("graph TD\nA-->B")
+  #   puts svg
+  #
+  # @example Render with options
+  #   engine = Sirena::Engine.new
+  #   svg = engine.render(source, verbose: true)
+  class Engine
+    # Error raised when diagram type cannot be detected
+    class DiagramTypeError < Error; end
+
+    # Error raised during pipeline execution
+    class PipelineError < Error; end
+
+    # Mapping of diagram syntax prefixes to diagram types
+    DIAGRAM_TYPE_PATTERNS = {
+      flowchart: /\A\s*(graph|flowchart)\s+/i,
+      sequence: /\A\s*sequenceDiagram/i,
+      class_diagram: /\A\s*classDiagram/i,
+      state_diagram: /\A\s*stateDiagram(-v2)?/i,
+      er_diagram: /\A\s*erDiagram/i,
+      user_journey: /\A\s*journey/i,
+      gantt: /\A\s*gantt\s/i,
+      pie: /\A\s*pie\s/i,
+      timeline: /\A\s*timeline(\s|$)/i,
+      quadrant: /\A\s*quadrantChart/i,
+      git_graph: /\A\s*gitGraph/i,
+      mindmap: /\A\s*mindmap/i,
+      kanban: /\A\s*kanban/i,
+      radar: /\A\s*radar-beta/i,
+      block: /\A\s*block-beta/i,
+      requirement: /\A\s*requirementDiagram/i,
+      xychart: /\A\s*xychart-beta/i,
+      architecture: /\A\s*architecture-beta/i,
+      sankey: /\A\s*sankey-beta/i,
+      packet: /\A\s*packet-beta/i,
+      treemap: /\A\s*treemap(-beta)?/i,
+      c4: /\A\s*(C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|C4\s+diagram)/i,
+      info: /\A\s*info/i,
+      error: /\A\s*(error|Error)/i
+    }.freeze
+
+    attr_reader :verbose, :theme
+
+    # Creates a new Engine instance.
+    #
+    # @param verbose [Boolean] enable verbose output for debugging
+    # @param theme [String, Theme, Hash, nil] theme specification
+    def initialize(verbose: false, theme: nil)
+      @verbose = verbose
+      @theme = load_theme(theme)
+    end
+
+    # Renders Mermaid source code to SVG.
+    #
+    # @param mermaid_source [String] Mermaid diagram source code
+    # @param options [Hash] rendering options
+    # @option options [Boolean] :verbose enable verbose output
+    # @option options [String, Theme, Hash, nil] :theme theme override
+    # @return [String] SVG XML string
+    # @raise [DiagramTypeError] if diagram type cannot be detected
+    # @raise [PipelineError] if any pipeline stage fails
+    def render(mermaid_source, options = {})
+      @verbose = options[:verbose] if options.key?(:verbose)
+
+      # Override theme if specified in options
+      theme = options[:theme] ? load_theme(options[:theme]) : @theme
+
+      log 'Starting render pipeline...'
+
+      # Detect diagram type
+      diagram_type = detect_diagram_type(mermaid_source)
+      log "Detected diagram type: #{diagram_type}"
+
+      # Retrieve handlers
+      handlers = retrieve_handlers(diagram_type)
+      log "Retrieved handlers for #{diagram_type}"
+
+      # Execute pipeline
+      diagram = parse_diagram(mermaid_source, handlers[:parser])
+      graph = transform_diagram(diagram, handlers[:transform])
+      laid_out_graph = layout_graph(graph)
+      svg_document = render_svg(laid_out_graph, handlers[:renderer], theme)
+
+      # Return XML string
+      svg_xml = svg_document.to_xml
+      log "Render complete, #{svg_xml.length} bytes"
+
+      svg_xml
+    rescue DiagramTypeError
+      # Re-raise diagram type errors without wrapping
+      raise
+    rescue StandardError => e
+      raise PipelineError,
+            "Rendering failed: #{e.message}\n#{e.backtrace.join("\n")}"
+    end
+
+    private
+
+    # Detects diagram type from source code syntax.
+    #
+    # @param source [String] Mermaid source code
+    # @return [Symbol] diagram type identifier
+    # @raise [DiagramTypeError] if type cannot be detected
+    def detect_diagram_type(source)
+      DIAGRAM_TYPE_PATTERNS.each do |type, pattern|
+        return type if source.match?(pattern)
+      end
+
+      raise DiagramTypeError,
+            'Unable to detect diagram type from source. ' \
+            'Source must start with one of: graph, flowchart, ' \
+            'sequenceDiagram, classDiagram, stateDiagram, ' \
+            'erDiagram, journey, gantt, or pie'
+    end
+
+    # Retrieves handlers for a diagram type.
+    #
+    # @param type [Symbol] diagram type identifier
+    # @return [Hash] hash with :parser, :transform, :renderer keys
+    # @raise [DiagramTypeError] if type is not registered
+    def retrieve_handlers(type)
+      handlers = DiagramRegistry.get(type)
+
+      unless handlers
+        raise DiagramTypeError,
+              "No handlers registered for diagram type: #{type}"
+      end
+
+      handlers
+    end
+
+    # Parses source code into diagram model.
+    #
+    # @param source [String] Mermaid source code
+    # @param parser_class [Class] parser class
+    # @return [Diagram::Base] parsed diagram model
+    def parse_diagram(source, parser_class)
+      log 'Parsing diagram...'
+      parser = parser_class.new
+      diagram = parser.parse(source)
+      log "Parse complete: #{diagram.class.name}"
+      diagram
+    end
+
+    # Transforms diagram model to graph structure.
+    #
+    # @param diagram [Diagram::Base] diagram model
+    # @param transform_class [Class] transform class
+    # @return [Object] graph structure
+    def transform_diagram(diagram, transform_class)
+      log 'Transforming diagram to graph...'
+      transform = transform_class.new
+      graph = transform.to_graph(diagram)
+      log 'Transform complete'
+      graph
+    end
+
+    # Computes layout for graph.
+    #
+    # Currently uses a simple fallback layout since elkrb may not be
+    # available. In the future, this will attempt to use elkrb for
+    # proper graph layout computation.
+    #
+    # @param graph [Object] graph structure
+    # @return [Object] graph with computed positions
+    def layout_graph(graph)
+      log 'Computing layout...'
+
+      # TODO: Attempt to use elkrb when available
+      # For now, use simple fallback positioning
+      apply_fallback_layout(graph)
+
+      log 'Layout complete (using fallback positioning)'
+      graph
+    end
+
+    # Applies simple grid-based fallback layout.
+    #
+    # This is a placeholder for actual elkrb layout. It arranges
+    # nodes in a simple grid pattern. Handles both object-based
+    # and hash-based graph structures.
+    #
+    # @param graph [Object, Hash] graph structure
+    # @return [Object, Hash] graph with positions
+    def apply_fallback_layout(graph)
+      # Handle hash-based graph structure (elkrb-compatible)
+      if graph.is_a?(Hash) && graph[:children]
+        apply_fallback_layout_to_hash(graph)
+      # Handle object-based graph structure
+      elsif graph.respond_to?(:nodes)
+        nodes = graph.nodes
+        nodes.each_with_index do |node, index|
+          next unless node.respond_to?(:x=) && node.respond_to?(:y=)
+
+          # Simple grid layout: 3 columns
+          col = index % 3
+          row = index / 3
+
+          node.x = 50 + (col * 200)
+          node.y = 50 + (row * 150)
+        end
+      end
+
+      graph
+    end
+
+    # Applies fallback layout to hash-based graph structure.
+    #
+    # @param graph [Hash] graph hash with :children
+    # @return [Hash] graph with positions added
+    def apply_fallback_layout_to_hash(graph)
+      children = graph[:children] || []
+
+      # Apply layout to immediate children
+      children.each_with_index do |child, index|
+        # Skip if already has position
+        next if child[:x] && child[:y]
+
+        # Simple grid layout: 3 columns
+        col = index % 3
+        row = index / 3
+
+        child[:x] = 50 + (col * 250)
+        child[:y] = 50 + (row * 200)
+
+        # Recursively apply to nested children
+        apply_fallback_layout_to_hash(child) if child[:children]
+      end
+
+      graph
+    end
+
+    # Renders graph to SVG document.
+    #
+    # @param graph [Object] laid-out graph
+    # @param renderer_class [Class] renderer class
+    # @param theme [Theme] theme to use for rendering
+    # @return [Svg::Document] SVG document
+    def render_svg(graph, renderer_class, theme)
+      log 'Rendering to SVG...'
+      renderer = renderer_class.new(theme: theme)
+      svg = renderer.render(graph)
+      log 'SVG render complete'
+      svg
+    end
+
+    # Loads a theme from various specifications.
+    #
+    # @param theme_spec [String, Theme, Hash, nil] theme specification
+    # @return [Theme] loaded theme
+    def load_theme(theme_spec)
+      return Theme::Registry.get(:default) if theme_spec.nil?
+
+      case theme_spec
+      when String
+        # Could be theme name or path to file
+        if File.exist?(theme_spec)
+          Theme.load(theme_spec)
+        else
+          Theme::Registry.get(theme_spec.to_sym) ||
+            Theme::Registry.get(:default)
+        end
+      when Theme
+        theme_spec
+      when Hash
+        Theme.new(**theme_spec)
+      else
+        Theme::Registry.get(:default)
+      end
+    end
+
+    # Logs a message if verbose mode is enabled.
+    #
+    # @param message [String] message to log
+    # @return [void]
+    def log(message)
+      puts "[Sirena::Engine] #{message}" if verbose
+    end
+  end
+end