etassia 0.1.0

data/lib/etassia/diagram/requirement.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  module Diagram
+    # Represents a requirement in the diagram
+    class RequirementNode < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :type, :string, default: -> { "requirement" }
+      attribute :id, :string
+      attribute :text, :string
+      attribute :risk, :string # Low, Medium, High
+      # Verification methods: Analysis, Inspection, Test, or Demonstration.
+      attribute :verifymethod, :string
+      attribute :classes, :string, collection: true, default: -> { [] }
+
+      def add_class(class_name)
+        classes << class_name
+      end
+    end
+
+    # Represents an element in the diagram
+    class RequirementElement < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :type, :string
+      attribute :docref, :string
+      attribute :classes, :string, collection: true, default: -> { [] }
+
+      def add_class(class_name)
+        classes << class_name
+      end
+    end
+
+    # Represents a relationship between requirements/elements
+    class RequirementRelationship < Lutaml::Model::Serializable
+      attribute :source, :string
+      attribute :target, :string
+      # Relationship types: contains, copies, derives, satisfies, verifies,
+      # refines, or traces.
+      attribute :type, :string
+
+      VALID_TYPES = %w[
+        contains
+        copies
+        derives
+        satisfies
+        verifies
+        refines
+        traces
+      ].freeze
+
+      def valid?
+        VALID_TYPES.include?(type)
+      end
+    end
+
+    # Represents styling for a requirement or element
+    class RequirementStyle < Lutaml::Model::Serializable
+      attribute :target_ids, :string, collection: true, default: -> { [] }
+      attribute :fill, :string
+      attribute :stroke, :string
+      attribute :stroke_width, :string
+      attribute :properties, :string, collection: true, default: -> { [] }
+
+      def add_target(id)
+        target_ids << id
+      end
+
+      def add_property(property)
+        properties << property
+      end
+    end
+
+    # Represents a CSS class definition
+    class RequirementClass < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :fill, :string
+      attribute :stroke, :string
+      attribute :stroke_width, :string
+      attribute :properties, :string, collection: true, default: -> { [] }
+
+      def add_property(property)
+        properties << property
+      end
+    end
+
+    # Represents a class assignment to requirements/elements
+    class RequirementClassAssignment < Lutaml::Model::Serializable
+      attribute :target_ids, :string, collection: true, default: -> { [] }
+      attribute :class_names, :string, collection: true, default: -> { [] }
+
+      def add_target(id)
+        target_ids << id
+      end
+
+      def add_class(class_name)
+        class_names << class_name
+      end
+    end
+
+    # Represents a Mermaid requirement diagram
+    class Requirement < Base
+      attribute :requirements,
+                RequirementNode,
+                collection: true,
+                default: -> { [] }
+      attribute :elements,
+                RequirementElement,
+                collection: true,
+                default: -> { [] }
+      attribute :relationships,
+                RequirementRelationship,
+                collection: true,
+                default: -> { [] }
+      attribute :styles, RequirementStyle, collection: true, default: -> { [] }
+      attribute :classes, RequirementClass, collection: true, default: -> { [] }
+      attribute :class_assignments,
+                RequirementClassAssignment,
+                collection: true,
+                default: -> { [] }
+      attribute :acc_title, :string
+      attribute :acc_description, :string
+
+      def add_requirement(requirement)
+        requirements << requirement
+      end
+
+      def add_element(element)
+        elements << element
+      end
+
+      def add_relationship(relationship)
+        relationships << relationship
+      end
+
+      def add_style(style)
+        styles << style
+      end
+
+      def add_class(klass)
+        classes << klass
+      end
+
+      def add_class_assignment(assignment)
+        class_assignments << assignment
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :requirement
+      def diagram_type
+        :requirement
+      end
+
+      # Requirement diagrams have no top-level validation rules yet — the
+      # relationship type check lives on RequirementRelationship#valid?
+      # above, and nothing here calls it. See TODO.foundation's corpus
+      # burndown for real validation; this is deliberately trivial.
+      #
+      # @return [Boolean] true
+      def valid?
+        true
+      end
+    end
+  end
+end

data/lib/etassia/diagram/sankey.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  module Diagram
+    # Represents a node in a Sankey diagram.
+    #
+    # A node can be a source, target, or intermediate point in the flow.
+    # Nodes are automatically discovered from flow definitions.
+    class SankeyNode < Lutaml::Model::Serializable
+      # Unique identifier for the node
+      attribute :id, :string
+
+      # Display label for the node (defaults to id if not set)
+      attribute :label, :string
+
+      def initialize(id = nil, label = nil)
+        super()
+        @id = id
+        @label = label || id
+      end
+
+      # Validates the node has required attributes.
+      #
+      # @return [Boolean] true if node is valid
+      def valid?
+        !id.nil? && !id.empty?
+      end
+
+      # Get display label, falling back to id.
+      #
+      # @return [String] the label to display
+      def display_label
+        label && !label.empty? ? label : id
+      end
+    end
+
+    # Represents a flow/link between two nodes in a Sankey diagram.
+    #
+    # A flow connects a source node to a target node with a value
+    # that determines the width of the flow arrow.
+    class SankeyFlow < Lutaml::Model::Serializable
+      # Source node identifier
+      attribute :source, :string
+
+      # Target node identifier
+      attribute :target, :string
+
+      # Flow value (determines arrow width)
+      attribute :value, :float
+
+      # Optional label for the flow
+      attribute :label, :string
+
+      def initialize(source = nil, target = nil, value = 0.0)
+        super()
+        @source = source
+        @target = target
+        @value = value.to_f
+      end
+
+      # Validates the flow has required attributes.
+      #
+      # @return [Boolean] true if flow is valid
+      def valid?
+        !source.nil? && !source.empty? &&
+          !target.nil? && !target.empty? &&
+          value.positive?
+      end
+
+      # Check if this is a self-loop.
+      #
+      # @return [Boolean] true if source equals target
+      def self_loop?
+        source == target
+      end
+    end
+
+    # Sankey diagram model.
+    #
+    # Represents a Sankey diagram showing flows between nodes where
+    # the width of arrows is proportional to flow values. Used for
+    # visualizing energy flows, material flows, cost distributions, etc.
+    #
+    # @example Creating a Sankey diagram
+    #   sankey = Sankey.new
+    #   sankey.title = 'Energy Flow'
+    #
+    #   flow1 = SankeyFlow.new('Source', 'Process', 100)
+    #   flow2 = SankeyFlow.new('Process', 'Output', 70)
+    #   flow3 = SankeyFlow.new('Process', 'Waste', 30)
+    #   sankey.flows << flow1 << flow2 << flow3
+    class Sankey < Base
+      # Collection of explicitly defined nodes (optional)
+      attribute :nodes, SankeyNode, collection: true,
+                                    default: -> { [] }
+
+      # Collection of flows between nodes
+      attribute :flows, SankeyFlow, collection: true,
+                                    default: -> { [] }
+
+      # Accessibility title (for screen readers)
+      attribute :acc_title, :string
+
+      # Accessibility description (for screen readers)
+      attribute :acc_description, :string
+
+      def initialize
+        @nodes = []
+        @flows = []
+        super
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :sankey
+      def diagram_type
+        :sankey
+      end
+
+      # Validates the diagram structure.
+      #
+      # A Sankey diagram is valid if it has at least one flow.
+      #
+      # @return [Boolean] true if diagram is valid
+      def valid?
+        !flows.empty? && flows.all?(&:valid?)
+      end
+
+      # Get all unique node IDs from flows and explicit nodes.
+      #
+      # @return [Array<String>] array of unique node IDs
+      def all_node_ids
+        node_ids_from_flows = flows.flat_map { |f| [f.source, f.target] }
+        explicit_node_ids = nodes.map(&:id)
+        (node_ids_from_flows + explicit_node_ids).uniq
+      end
+
+      # Get or create node by ID.
+      #
+      # @param id [String] node identifier
+      # @return [SankeyNode] the node
+      def node_by_id(id)
+        nodes.find { |n| n.id == id } || SankeyNode.new(id)
+      end
+
+      # Get all flows from a specific node.
+      #
+      # @param node_id [String] the source node ID
+      # @return [Array<SankeyFlow>] flows from this node
+      def flows_from(node_id)
+        flows.select { |f| f.source == node_id }
+      end
+
+      # Get all flows to a specific node.
+      #
+      # @param node_id [String] the target node ID
+      # @return [Array<SankeyFlow>] flows to this node
+      def flows_to(node_id)
+        flows.select { |f| f.target == node_id }
+      end
+
+      # Calculate total outflow from a node.
+      #
+      # @param node_id [String] the node ID
+      # @return [Float] sum of all outgoing flow values
+      def total_outflow(node_id)
+        flows_from(node_id).sum(&:value)
+      end
+
+      # Calculate total inflow to a node.
+      #
+      # @param node_id [String] the node ID
+      # @return [Float] sum of all incoming flow values
+      def total_inflow(node_id)
+        flows_to(node_id).sum(&:value)
+      end
+
+      # Get source nodes (nodes with no inflow).
+      #
+      # @return [Array<String>] source node IDs
+      def source_nodes
+        all_node_ids.select { |id| total_inflow(id).zero? }
+      end
+
+      # Get sink nodes (nodes with no outflow).
+      #
+      # @return [Array<String>] sink node IDs
+      def sink_nodes
+        all_node_ids.select { |id| total_outflow(id).zero? }
+      end
+
+      # Get total flow value in the diagram.
+      #
+      # @return [Float] sum of all flow values
+      def total_flow
+        flows.sum(&:value)
+      end
+
+      # Get maximum flow value.
+      #
+      # @return [Float] maximum single flow value
+      def max_flow
+        flows.map(&:value).max || 0.0
+      end
+
+      # Get minimum flow value.
+      #
+      # @return [Float] minimum single flow value
+      def min_flow
+        flows.map(&:value).min || 0.0
+      end
+    end
+  end
+end

data/lib/etassia/diagram/sequence.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+require_relative "sequence_frame"
+require_relative "sequence_box"
+
+module Etassia
+  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
+
+      # Declared with `create participant|actor`: the box is drawn at the
+      # creating message's row, not at the top of the diagram.
+      attribute :created, :boolean, default: -> { false }
+
+      # Type named by `@{ "type": ... }` (boundary, control, entity,
+      # database, collections, queue); nil for a plain box or stick figure.
+      attribute :shape_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
+
+      # Line style: 'solid' or 'dotted'
+      attribute :line_style, :string
+
+      # Marker shape: 'none', 'filled', 'open', 'cross', 'half_top',
+      # 'half_bottom', 'stick_top' or 'stick_bottom'
+      attribute :head_style, :string
+
+      # Which end of the line carries the marker: 'target', 'source', or
+      # 'both' for mermaid's <<->> arrows. Mermaid spells the same head at
+      # the source end by reversing the arrow: `-\\` against `\\-`.
+      attribute :head_side, :string
+
+      def initialize(*args)
+        super
+        self.line_style ||= "solid"
+        self.head_style ||= "filled"
+        self.head_side ||= "target"
+      end
+
+      # @return [Boolean] true when the marker is drawn at both ends
+      def bidirectional?
+        head_side == "both"
+      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
+
+      # Position among the frame edges, dividers and notes, in source
+      # order; tells which side of a frame edge at the same message
+      # index the note sits on
+      attribute :order, :integer
+
+      # Validates the note has required attributes.
+      #
+      # Text may be empty — mmdc renders `Note over A:` with no trailing
+      # content as an empty label, not a malformed note.
+      #
+      # @return [Boolean] true if note is valid
+      def valid?
+        !text.nil? && !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',
+    #     line_style: 'solid',
+    #     head_style: 'filled'
+    #   )
+    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: -> { [] }
+
+      # Whether `%%{wrap}%%` made every message and note wrap
+      attribute :wrap, :boolean, default: -> { false }
+
+      # Control blocks (loop, alt, opt, par, critical, break, rect)
+      attribute :frames, SequenceFrame, collection: true,
+                                        default: -> { [] }
+
+      # `box` groups around participants
+      attribute :boxes, SequenceBox, 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:
+      # - All participants are valid
+      # - All messages are valid
+      # - All message references point to existing participants
+      # - All activations are valid
+      # - All notes are valid
+      #
+      # Zero participants is valid: `sequenceDiagram` with no body is a
+      # diagram mmdc renders (an empty canvas, no lifelines), not a rejection.
+      #
+      # @return [Boolean] true if sequence diagram is valid
+      def valid?
+        return false unless components_valid?
+
+        references_valid?(participants.map(&:id))
+      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
+
+      private
+
+      def components_valid?
+        !participants.nil? && participants.all?(&:valid?) &&
+          collection_valid?(messages) && collection_valid?(activations) &&
+          collection_valid?(notes)
+      end
+
+      def collection_valid?(collection)
+        collection.nil? || collection.all?(&:valid?)
+      end
+
+      def references_valid?(participant_ids)
+        message_references_valid?(participant_ids) &&
+          activation_references_valid?(participant_ids) &&
+          note_references_valid?(participant_ids)
+      end
+
+      def message_references_valid?(participant_ids)
+        messages.nil? || messages.all? do |message|
+          participant_ids.include?(message.from_id) &&
+            participant_ids.include?(message.to_id)
+        end
+      end
+
+      def activation_references_valid?(participant_ids)
+        activations.nil? || activations.all? do |activation|
+          participant_ids.include?(activation.participant_id)
+        end
+      end
+
+      def note_references_valid?(participant_ids)
+        notes.nil? || notes.all? do |note|
+          note.participant_ids.all? { |id| participant_ids.include?(id) }
+        end
+      end
+    end
+  end
+end

data/lib/etassia/diagram/sequence_box.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Diagram
+    # A `box` group around the participants declared inside it.
+    class SequenceBox < Lutaml::Model::Serializable
+      # Fill colour; nil when the box has none
+      attribute :color, :string
+
+      attribute :title, :string
+
+      attribute :participant_ids, :string, collection: true,
+                                           default: -> { [] }
+    end
+  end
+end