etassia 0.1.0

data/lib/etassia/diagram/sequence_frame.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "sequence_frame_section"
+
+module Etassia
+  module Diagram
+    # A control block in a sequence diagram: loop, alt, opt, par, critical,
+    # break or rect. It covers the messages whose index is in
+    # `start_index...end_index`.
+    class SequenceFrame < Lutaml::Model::Serializable
+      KINDS = %w[loop alt opt par critical break rect].freeze
+
+      attribute :kind, :string
+
+      # Text after the keyword; the colour for a `rect`
+      attribute :label, :string
+
+      # Index of the first message inside the frame
+      attribute :start_index, :integer
+
+      # Index of the first message after the frame
+      attribute :end_index, :integer
+
+      # Number of frames that enclose this one
+      attribute :depth, :integer, default: -> { 0 }
+
+      # Positions of the opening and closing edge among the other frame
+      # edges, dividers and notes, in source order
+      attribute :open_order, :integer
+      attribute :close_order, :integer
+
+      attribute :sections, SequenceFrameSection, collection: true,
+                                                 default: -> { [] }
+    end
+  end
+end

data/lib/etassia/diagram/sequence_frame_section.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Diagram
+    # One `else`, `and` or `option` divider inside a sequence frame.
+    class SequenceFrameSection < Lutaml::Model::Serializable
+      # Divider keyword: else, and or option
+      attribute :kind, :string
+
+      # Text after the keyword
+      attribute :label, :string
+
+      # Index of the first message that follows the divider
+      attribute :start_index, :integer
+
+      # Position of the divider among the frame edges and notes, in
+      # source order
+      attribute :order, :integer
+    end
+  end
+end

data/lib/etassia/diagram/sequence_text.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Diagram
+    # Mermaid draws a sequence message without its `wrap:`/`nowrap:` prefix
+    # and with `<br>` as a line break. `decode` is its character-reference
+    # step, which mermaid applies to every piece of sequence text: actor
+    # ids, `as` aliases, messages and notes.
+    module SequenceText
+      WRAP_PREFIX = /\A\s*(?:no)?wrap:\s*/i
+      LINE_BREAK = %r{<br\s*/?>}i
+      ENTITY = /#(\w+);/
+      REPLACEMENT = "�"
+      SCALARS = (1..0x10FFFF)
+      SURROGATES = (0xD800..0xDFFF)
+      C1_CONTROLS = (0x80..0x9F)
+      NAMED = {
+        "amp" => "&", "AMP" => "&",
+        "lt" => "<", "LT" => "<",
+        "gt" => ">", "GT" => ">",
+        "quot" => '"', "QUOT" => '"',
+        "apos" => "'", "nbsp" => "\u00A0",
+        "infin" => "∞", "hearts" => "♥",
+        "copy" => "©", "reg" => "®", "deg" => "°",
+        "trade" => "™", "euro" => "€",
+        "mdash" => "—", "ndash" => "–", "hellip" => "…",
+        "larr" => "←", "rarr" => "→", "uarr" => "↑", "darr" => "↓",
+        "times" => "×", "divide" => "÷", "plusmn" => "±",
+        "laquo" => "«", "raquo" => "»", "bull" => "•"
+      }.freeze
+
+      # @param text [String] message text as written in the source
+      # @return [String] the text as mermaid draws it
+      def self.display(text)
+        decode(text.sub(WRAP_PREFIX, "").gsub(LINE_BREAK, " "))
+      end
+
+      # One pass, like mermaid: `#35;59;` gives `#59;`, never `;`. A
+      # numeric reference becomes its character, a known name its
+      # character, any other name stays as the literal `&name;` (hex
+      # `#x41;` included).
+      #
+      # @param text [String] text as written in the source
+      # @return [String] the text with character references decoded
+      def self.decode(text)
+        text.gsub(ENTITY) do
+          name = Regexp.last_match(1)
+          next codepoint(name.to_i) if name.match?(/\A\d+\z/)
+
+          NAMED.fetch(name) { "&#{name};" }
+        end
+      end
+
+      # HTML numeric rules: NUL, surrogates and out-of-range values are
+      # U+FFFD, and 0x80-0x9F read as Windows-1252.
+      def self.codepoint(number)
+        return REPLACEMENT unless SCALARS.cover?(number)
+        return REPLACEMENT if SURROGATES.cover?(number)
+
+        character = [number].pack("U")
+        return character unless C1_CONTROLS.cover?(number)
+
+        [number].pack("C").force_encoding(Encoding::Windows_1252)
+          .encode(Encoding::UTF_8, undef: :replace, replace: character)
+      end
+      private_class_method :codepoint
+    end
+  end
+end

data/lib/etassia/diagram/sequence_wrap.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Diagram
+    # Mermaid's global sequence wrap switch: the bare `%%{wrap}%%`
+    # directive, or an `init` directive with `wrap: true` at the top level
+    # or under `sequence`. The directive may sit before or after the
+    # `sequenceDiagram` line.
+    module SequenceWrap
+      DIRECTIVE = /%%\{(.*?)\}%%/m
+      BARE = /\A\s*wrap\s*\z/
+      INIT_WRAP = /\A\s*init(?:ialize)?\s*:.*["']?\bwrap["']?\s*:\s*true\b/mi
+
+      # @param source [String] the whole Mermaid source
+      # @return [Boolean] whether every sequence text wraps by default
+      def self.on?(source)
+        source.scrub.scan(DIRECTIVE).flatten.any? do |body|
+          body.match?(BARE) || body.match?(INIT_WRAP)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/diagram/state_diagram.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  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
+
+      # Most recently declared description for this state, if any
+      attribute :description, :string
+
+      # Ordered display text declared by aliases and descriptions
+      attribute :descriptions, :string, collection: true, default: -> { [] }
+
+      # Child states for composite/nested states
+      attribute :children, StateNode, collection: true, default: -> { [] }
+
+      # A bare `state ID` declaration exists in Mermaid's database but is not
+      # drawn until another statement gives it display semantics or uses it.
+      attribute :declaration_only, :boolean, default: -> { false }
+
+      # 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?
+        if guard_condition && !guard_condition.empty?
+          parts << "[#{guard_condition}]"
+        end
+        parts.join(" ")
+      end
+    end
+
+    # A note attached to a state in a state diagram.
+    class StateNote < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :text, :string
+      attribute :target_id, :string
+      attribute :position, :string
+
+      def valid?
+        [id, text, target_id].all? { |value| value && !value.empty? }
+      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: -> { [] }
+
+      # Collection of notes attached to states
+      attribute :notes, StateNote, 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 a states collection, empty or not
+      # - All states are valid
+      # - All transitions are valid
+      # - All transition references point to existing states
+      #
+      # An EMPTY collection is fine: mmdc 11.12.0 draws a bare
+      # `stateDiagram-v2` as an empty picture rather than refusing it. A
+      # MISSING one is not, because the attribute defaults to `[]` and only
+      # a caller clearing it can produce nil.
+      #
+      # @return [Boolean] true if state diagram is valid
+      def valid?
+        return false if states.nil?
+
+        all_states.all?(&:valid?) && valid_transitions? && valid_notes?
+      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)
+        all_states.find { |state| state.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
+        all_states.find(&:start_state?)
+      end
+
+      # Finds all end states.
+      #
+      # @return [Array<StateNode>] end states
+      def end_states
+        all_states.select(&:end_state?)
+      end
+
+      # Finds all composite states.
+      #
+      # @return [Array<StateNode>] composite states
+      def composite_states
+        all_states.select(&:composite_state?)
+      end
+
+      # Finds all choice states.
+      #
+      # @return [Array<StateNode>] choice states
+      def choice_states
+        all_states.select(&:choice_state?)
+      end
+
+      private
+
+      def all_states(collection = states)
+        Array(collection).flat_map do |state|
+          [state, *all_states(state.children)]
+        end
+      end
+
+      def valid_transitions?
+        transitions.nil? || transitions.all? do |transition|
+          transition.valid? && transition_references_resolve?(transition)
+        end
+      end
+
+      def valid_notes?
+        notes.nil? || notes.all? do |note|
+          note.valid? && !find_state(note.target_id).nil?
+        end
+      end
+
+      def transition_references_resolve?(transition)
+        state_ids = all_states.map(&:id)
+        state_ids.include?(transition.from_id) &&
+          state_ids.include?(transition.to_id)
+      end
+    end
+  end
+end

data/lib/etassia/diagram/timeline.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  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
+
+      # A period written without descriptions (a bare task line).
+      #
+      # @return [Boolean] true if there are no descriptions
+      def bare?
+        descriptions.empty?
+      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
+
+      # Periods in source order: events and bare tasks interleaved as
+      # written. A bare task is an event without descriptions.
+      attribute :events, TimelineEvent, collection: true,
+                                        default: -> { [] }
+
+      def initialize(name = nil)
+        super()
+        @name = name
+        @events = []
+      end
+
+      # Names of the bare tasks, in source order.
+      #
+      # @return [Array<String>] task names
+      def tasks
+        events.select(&:bare?).map(&:time)
+      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 with descriptions
+      def has_events?
+        events.any? { |event| !event.bare? }
+      end
+
+      # Check if section has tasks.
+      #
+      # @return [Boolean] true if section has tasks
+      def has_tasks?
+        events.any?(&:bare?)
+      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: -> { [] }
+
+      # Periods (events and bare tasks, in source order) written before
+      # the first 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.any? { |event| !event.bare? } || 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