sirena 0.1.0

data/lib/sirena/diagram/sequence.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'base'
+
+module Sirena
+  module Diagram
+    # Represents a sequence diagram participant.
+    #
+    # A participant represents an actor or entity in the sequence diagram
+    # that can send and receive messages.
+    class SequenceParticipant < Lutaml::Model::Serializable
+      # Unique identifier for the participant
+      attribute :id, :string
+
+      # Display text/label for the participant
+      attribute :label, :string
+
+      # Participant type: :participant, :actor
+      attribute :actor_type, :string
+
+      # Initialize with default actor type
+      def initialize(*args)
+        super
+        self.actor_type ||= 'participant'
+      end
+
+      # Validates the participant has required attributes.
+      #
+      # @return [Boolean] true if participant is valid
+      def valid?
+        !id.nil? && !id.empty? && !label.nil?
+      end
+    end
+
+    # Represents a sequence diagram message.
+    #
+    # A message represents communication between participants in a
+    # sequence diagram, with various arrow types and optional text.
+    class SequenceMessage < Lutaml::Model::Serializable
+      # Source participant identifier
+      attribute :from_id, :string
+
+      # Target participant identifier
+      attribute :to_id, :string
+
+      # Message text content
+      attribute :message_text, :string
+
+      # Arrow type: :solid, :dotted, :async, :async_dotted,
+      # :solid_cross, :dotted_cross
+      attribute :arrow_type, :string
+
+      # Initialize with default arrow type
+      def initialize(*args)
+        super
+        self.arrow_type ||= 'solid'
+      end
+
+      # Validates the message has required attributes.
+      #
+      # @return [Boolean] true if message is valid
+      def valid?
+        !from_id.nil? && !from_id.empty? &&
+          !to_id.nil? && !to_id.empty?
+      end
+    end
+
+    # Represents an activation box (lifecycle) in a sequence diagram.
+    #
+    # An activation shows when a participant is active or processing.
+    class SequenceActivation < Lutaml::Model::Serializable
+      # Participant identifier
+      attribute :participant_id, :string
+
+      # Start message index (position in messages array)
+      attribute :start_index, :integer
+
+      # End message index (position in messages array)
+      attribute :end_index, :integer
+
+      # Validates the activation has required attributes.
+      #
+      # @return [Boolean] true if activation is valid
+      def valid?
+        !participant_id.nil? && !participant_id.empty? &&
+          !start_index.nil? && !end_index.nil? &&
+          start_index <= end_index
+      end
+    end
+
+    # Represents a note in a sequence diagram.
+    #
+    # A note provides additional context or information in the diagram.
+    class SequenceNote < Lutaml::Model::Serializable
+      # Note text content
+      attribute :text, :string
+
+      # Position: :left_of, :right_of, :over
+      attribute :position, :string
+
+      # Participant identifier(s) - array for :over with multiple
+      attribute :participant_ids, :string, collection: true,
+                                           default: -> { [] }
+
+      # Message index where the note appears
+      attribute :message_index, :integer
+
+      # Validates the note has required attributes.
+      #
+      # @return [Boolean] true if note is valid
+      def valid?
+        !text.nil? && !text.empty? &&
+          !position.nil? && !participant_ids.empty?
+      end
+    end
+
+    # Sequence diagram model.
+    #
+    # Represents a complete sequence diagram with participants, messages,
+    # activations, and notes. Sequence diagrams show interactions between
+    # participants over time in a vertical timeline format.
+    #
+    # @example Creating a simple sequence diagram
+    #   sequence = Sequence.new
+    #   sequence.participants << SequenceParticipant.new(
+    #     id: 'Alice',
+    #     label: 'Alice',
+    #     actor_type: 'actor'
+    #   )
+    #   sequence.participants << SequenceParticipant.new(
+    #     id: 'Bob',
+    #     label: 'Bob',
+    #     actor_type: 'actor'
+    #   )
+    #   sequence.messages << SequenceMessage.new(
+    #     from_id: 'Alice',
+    #     to_id: 'Bob',
+    #     message_text: 'Hello Bob',
+    #     arrow_type: 'solid'
+    #   )
+    class Sequence < Base
+      # Collection of participants in the sequence diagram
+      attribute :participants, SequenceParticipant, collection: true,
+                                                    default: -> { [] }
+
+      # Collection of messages between participants
+      attribute :messages, SequenceMessage, collection: true,
+                                            default: -> { [] }
+
+      # Collection of activation boxes
+      attribute :activations, SequenceActivation, collection: true,
+                                                  default: -> { [] }
+
+      # Collection of notes
+      attribute :notes, SequenceNote, collection: true,
+                                      default: -> { [] }
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :sequence
+      def diagram_type
+        :sequence
+      end
+
+      # Validates the sequence diagram structure.
+      #
+      # A sequence diagram is valid if:
+      # - It has at least one participant
+      # - All participants are valid
+      # - All messages are valid
+      # - All message references point to existing participants
+      # - All activations are valid
+      # - All notes are valid
+      #
+      # @return [Boolean] true if sequence diagram is valid
+      def valid?
+        return false if participants.nil? || participants.empty?
+        return false unless participants.all?(&:valid?)
+        return false unless messages.nil? || messages.all?(&:valid?)
+        return false unless activations.nil? || activations.all?(&:valid?)
+        return false unless notes.nil? || notes.all?(&:valid?)
+
+        # Validate message references
+        participant_ids = participants.map(&:id)
+        messages&.each do |message|
+          return false unless participant_ids.include?(message.from_id)
+          return false unless participant_ids.include?(message.to_id)
+        end
+
+        # Validate activation references
+        activations&.each do |activation|
+          return false unless participant_ids.include?(
+            activation.participant_id
+          )
+        end
+
+        # Validate note references
+        notes&.each do |note|
+          note.participant_ids.each do |pid|
+            return false unless participant_ids.include?(pid)
+          end
+        end
+
+        true
+      end
+
+      # Finds a participant by its identifier.
+      #
+      # @param id [String] the participant identifier to find
+      # @return [SequenceParticipant, nil] the participant or nil if not
+      #   found
+      def find_participant(id)
+        participants.find { |p| p.id == id }
+      end
+
+      # Finds all messages from a specific participant.
+      #
+      # @param participant_id [String] the source participant identifier
+      # @return [Array<SequenceMessage>] messages from the participant
+      def messages_from(participant_id)
+        messages.select { |m| m.from_id == participant_id }
+      end
+
+      # Finds all messages to a specific participant.
+      #
+      # @param participant_id [String] the target participant identifier
+      # @return [Array<SequenceMessage>] messages to the participant
+      def messages_to(participant_id)
+        messages.select { |m| m.to_id == participant_id }
+      end
+
+      # Finds activations for a specific participant.
+      #
+      # @param participant_id [String] the participant identifier
+      # @return [Array<SequenceActivation>] activations for the participant
+      def activations_for(participant_id)
+        activations.select { |a| a.participant_id == participant_id }
+      end
+    end
+  end
+end

data/lib/sirena/diagram/state_diagram.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'base'
+
+module Sirena
+  module Diagram
+    # Represents a state node in a state diagram.
+    #
+    # A state node can represent different types of states in a state
+    # machine, including normal states, start/end states, choice points,
+    # and fork/join nodes.
+    class StateNode < Lutaml::Model::Serializable
+      # Unique identifier for the state
+      attribute :id, :string
+
+      # Display label for the state
+      attribute :label, :string
+
+      # State type: :normal, :start, :end, :choice, :fork, :join
+      attribute :state_type, :string
+
+      # Optional description for composite states
+      attribute :description, :string
+
+      # Child states for composite/nested states
+      attribute :children, StateNode, collection: true, default: -> { [] }
+
+      # Initialize with default state type
+      def initialize(*args)
+        super
+        self.state_type ||= 'normal'
+      end
+
+      # Validates the state node has required attributes.
+      #
+      # @return [Boolean] true if state node is valid
+      def valid?
+        !id.nil? && !id.empty? &&
+          !state_type.nil? && !state_type.empty?
+      end
+
+      # Checks if this is a start state.
+      #
+      # @return [Boolean] true if start state
+      def start_state?
+        state_type == 'start'
+      end
+
+      # Checks if this is an end state.
+      #
+      # @return [Boolean] true if end state
+      def end_state?
+        state_type == 'end'
+      end
+
+      # Checks if this is a choice state.
+      #
+      # @return [Boolean] true if choice state
+      def choice_state?
+        state_type == 'choice'
+      end
+
+      # Checks if this is a fork state.
+      #
+      # @return [Boolean] true if fork state
+      def fork_state?
+        state_type == 'fork'
+      end
+
+      # Checks if this is a join state.
+      #
+      # @return [Boolean] true if join state
+      def join_state?
+        state_type == 'join'
+      end
+
+      # Checks if this is a composite state.
+      #
+      # @return [Boolean] true if has child states
+      def composite_state?
+        !children.nil? && !children.empty?
+      end
+    end
+
+    # Represents a state transition in a state diagram.
+    #
+    # A transition connects two states with optional trigger event
+    # and guard condition.
+    class StateTransition < Lutaml::Model::Serializable
+      # Source state identifier
+      attribute :from_id, :string
+
+      # Target state identifier
+      attribute :to_id, :string
+
+      # Optional trigger event for the transition
+      attribute :trigger, :string
+
+      # Optional guard condition for the transition
+      attribute :guard_condition, :string
+
+      # Validates the transition has required attributes.
+      #
+      # @return [Boolean] true if transition is valid
+      def valid?
+        !from_id.nil? && !from_id.empty? &&
+          !to_id.nil? && !to_id.empty?
+      end
+
+      # Returns the full transition label.
+      #
+      # @return [String] formatted label with trigger and guard
+      def label
+        parts = []
+        parts << trigger if trigger && !trigger.empty?
+        parts << "[#{guard_condition}]" if guard_condition && !guard_condition.empty?
+        parts.join(' ')
+      end
+    end
+
+    # State diagram model.
+    #
+    # Represents a complete state machine diagram with states and
+    # transitions. State diagrams show the dynamic behavior of a
+    # system through states, events, and transitions.
+    #
+    # @example Creating a simple state diagram
+    #   diagram = StateDiagram.new(direction: 'TB')
+    #   diagram.states << StateNode.new(
+    #     id: 'start',
+    #     label: '[*]',
+    #     state_type: 'start'
+    #   )
+    #   diagram.states << StateNode.new(
+    #     id: 'idle',
+    #     label: 'Idle',
+    #     state_type: 'normal'
+    #   )
+    #   diagram.transitions << StateTransition.new(
+    #     from_id: 'start',
+    #     to_id: 'idle'
+    #   )
+    class StateDiagram < Base
+      # Collection of states in the diagram
+      attribute :states, StateNode, collection: true, default: -> { [] }
+
+      # Collection of transitions between states
+      attribute :transitions, StateTransition, collection: true,
+                                               default: -> { [] }
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :state_diagram
+      def diagram_type
+        :state_diagram
+      end
+
+      # Validates the state diagram structure.
+      #
+      # A state diagram is valid if:
+      # - It has at least one state
+      # - All states are valid
+      # - All transitions are valid
+      # - All transition references point to existing states
+      #
+      # @return [Boolean] true if state diagram is valid
+      def valid?
+        return false if states.nil? || states.empty?
+        return false unless states.all?(&:valid?)
+        return false unless transitions.nil? ||
+                            transitions.all?(&:valid?)
+
+        # Validate transition references
+        state_ids = states.map(&:id)
+        transitions&.each do |transition|
+          return false unless state_ids.include?(transition.from_id)
+          return false unless state_ids.include?(transition.to_id)
+        end
+
+        true
+      end
+
+      # Finds a state by its identifier.
+      #
+      # @param id [String] the state identifier to find
+      # @return [StateNode, nil] the state or nil if not found
+      def find_state(id)
+        states.find { |s| s.id == id }
+      end
+
+      # Finds all transitions originating from a specific state.
+      #
+      # @param state_id [String] the source state identifier
+      # @return [Array<StateTransition>] transitions from the state
+      def transitions_from(state_id)
+        transitions.select { |t| t.from_id == state_id }
+      end
+
+      # Finds all transitions targeting a specific state.
+      #
+      # @param state_id [String] the target state identifier
+      # @return [Array<StateTransition>] transitions to the state
+      def transitions_to(state_id)
+        transitions.select { |t| t.to_id == state_id }
+      end
+
+      # Finds the start state.
+      #
+      # @return [StateNode, nil] the start state or nil if not found
+      def start_state
+        states.find(&:start_state?)
+      end
+
+      # Finds all end states.
+      #
+      # @return [Array<StateNode>] end states
+      def end_states
+        states.select(&:end_state?)
+      end
+
+      # Finds all composite states.
+      #
+      # @return [Array<StateNode>] composite states
+      def composite_states
+        states.select(&:composite_state?)
+      end
+
+      # Finds all choice states.
+      #
+      # @return [Array<StateNode>] choice states
+      def choice_states
+        states.select(&:choice_state?)
+      end
+    end
+  end
+end

data/lib/sirena/diagram/timeline.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Sirena
+  module Diagram
+    # Represents an event in a timeline.
+    #
+    # An event represents a point in time with associated description(s).
+    # Events can have multiple descriptions (when multiple things happened
+    # at the same time).
+    class TimelineEvent < Lutaml::Model::Serializable
+      # The time/date/year for this event
+      attribute :time, :string
+
+      # Event descriptions (can be multiple for same time)
+      attribute :descriptions, :string, collection: true, default: -> { [] }
+
+      # Validates the event has required attributes.
+      #
+      # @return [Boolean] true if event is valid
+      def valid?
+        !time.nil? && !time.empty? && !descriptions.empty?
+      end
+
+      # Get primary description (first one).
+      #
+      # @return [String, nil] the first description or nil
+      def primary_description
+        descriptions.first
+      end
+
+      # Check if event has multiple descriptions.
+      #
+      # @return [Boolean] true if more than one description
+      def multiple_descriptions?
+        descriptions.size > 1
+      end
+    end
+
+    # Represents a section/period in a timeline.
+    #
+    # A section groups related events together, typically representing
+    # a period, category, or theme.
+    class TimelineSection < Lutaml::Model::Serializable
+      # Name/title of this section
+      attribute :name, :string
+
+      # Events within this section
+      attribute :events, TimelineEvent, collection: true,
+                default: -> { [] }
+
+      # Task names (for sections without timestamps)
+      attribute :tasks, :string, collection: true, default: -> { [] }
+
+      def initialize(name = nil)
+        super()
+        @name = name
+        @events = []
+        @tasks = []
+      end
+
+      # Validates the section.
+      #
+      # @return [Boolean] true if section has a name
+      def valid?
+        !name.nil? && !name.empty?
+      end
+
+      # Check if section has events.
+      #
+      # @return [Boolean] true if section has events
+      def has_events?
+        !events.empty?
+      end
+
+      # Check if section has tasks.
+      #
+      # @return [Boolean] true if section has tasks
+      def has_tasks?
+        !tasks.empty?
+      end
+    end
+
+    # Timeline diagram model.
+    #
+    # Represents a timeline showing chronological events, optionally
+    # grouped into sections. Timelines are useful for showing historical
+    # progression, project milestones, or any time-based sequence.
+    #
+    # @example Creating a simple timeline
+    #   timeline = Timeline.new
+    #   timeline.title = 'History of Computing'
+    #
+    #   section = TimelineSection.new('Early Era')
+    #   event = TimelineEvent.new
+    #   event.time = '1936'
+    #   event.descriptions << 'Turing machine'
+    #   section.events << event
+    #
+    #   timeline.sections << section
+    class Timeline < Base
+      # Collection of sections in the timeline
+      attribute :sections, TimelineSection, collection: true,
+                default: -> { [] }
+
+      # Collection of events not in any section
+      attribute :events, TimelineEvent, collection: true,
+                default: -> { [] }
+
+      # Accessibility title (for screen readers)
+      attribute :acc_title, :string
+
+      # Accessibility description (for screen readers)
+      attribute :acc_description, :string
+
+      def initialize
+        @sections = []
+        @events = []
+        super
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :timeline
+      def diagram_type
+        :timeline
+      end
+
+      # Validates the timeline structure.
+      #
+      # A timeline is always valid (can be empty for parsing tests).
+      # In practice, useful timelines would have events or sections.
+      #
+      # @return [Boolean] true if timeline is valid
+      def valid?
+        true
+      end
+
+      # Check if timeline has any events.
+      #
+      # @return [Boolean] true if has events (in sections or standalone)
+      def has_events?
+        !events.empty? || sections.any?(&:has_events?)
+      end
+
+      # Check if timeline has sections.
+      #
+      # @return [Boolean] true if has sections
+      def has_sections?
+        !sections.empty?
+      end
+
+      # Get all events across all sections and standalone.
+      #
+      # @return [Array<TimelineEvent>] all events
+      def all_events
+        section_events = sections.flat_map(&:events)
+        events + section_events
+      end
+
+      # Get all unique time values from events.
+      #
+      # @return [Array<String>] sorted array of unique times
+      def all_times
+        all_events.map(&:time).uniq.sort
+      end
+    end
+  end
+end