etassia 0.1.0

data/lib/etassia/diagram/architecture.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+require_relative "containment"
+
+module Etassia
+  module Diagram
+    # Architecture diagram model representing system architecture visualization
+    class Architecture < Base
+      # Group (boundary) in architecture diagram
+      class Group < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :label, :string
+        attribute :icon, :string
+        attribute :parent_id, :string
+      end
+
+      # Service/component in architecture diagram
+      class Service < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :label, :string
+        attribute :icon, :string
+        attribute :group_id, :string
+      end
+
+      # Junction (routing point) in architecture diagram. Carries no icon
+      # or label - it exists only so edges can bend between services.
+      class Junction < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :group_id, :string
+      end
+
+      # Edge (relationship) between services
+      class Edge < Lutaml::Model::Serializable
+        attribute :from_id, :string
+        attribute :to_id, :string
+        attribute :from_position, :string
+        attribute :to_position, :string
+        attribute :label, :string
+      end
+
+      attribute :title, :string
+      attribute :acc_title, :string
+      attribute :acc_descr, :string
+      attribute :groups, Group, collection: true, default: -> { [] }
+      attribute :services, Service, collection: true, default: -> { [] }
+      attribute :junctions, Junction, collection: true, default: -> { [] }
+      attribute :edges, Edge, collection: true, default: -> { [] }
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :architecture
+      def diagram_type
+        :architecture
+      end
+
+      # A group cannot be its own ancestor, and every group_id a service,
+      # junction, or another group's parent_id names must belong to a
+      # declared group. Neither the grammar nor the parser refuses either
+      # shape. Left unchecked, a parent_id cycle poisons
+      # Architecture's bounding-box arithmetic with
+      # Infinity/-Infinity that later NaNs a comparison, and an undeclared
+      # group_id is silently dropped from the render along with whatever
+      # was placed in it — this stops both at the door instead.
+      #
+      # @return [Boolean] true if the diagram is valid
+      def valid?
+        return false if group_parent_cycle?
+        return false unless group_references_resolve?
+
+        true
+      end
+
+      private
+
+      # Mirrors Flowchart#parent_cycle? — a group is its own ancestor.
+      #
+      # @return [Boolean] true when some group is its own ancestor
+      def group_parent_cycle?
+        graph = groups.each_with_object({}) do |group, acc|
+          next if group.parent_id.nil?
+
+          acc[group.id] = acc.fetch(group.id, []) | [group.parent_id]
+        end
+
+        !Containment.looping_pair(graph).nil?
+      end
+
+      # @return [Boolean] true when every parent_id and group_id names a
+      #   group actually declared in the diagram
+      def group_references_resolve?
+        known = groups.map(&:id)
+
+        references_resolve?(groups, :parent_id, known) &&
+          references_resolve?(services, :group_id, known) &&
+          references_resolve?(junctions, :group_id, known)
+      end
+
+      def references_resolve?(items, attribute, known)
+        items.all? do |item|
+          reference = item.public_send(attribute)
+          reference.nil? || known.include?(reference)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/diagram/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Diagram
+    # Abstract base class for all diagram models.
+    #
+    # This class provides common attributes and functionality shared across
+    # all diagram types. Specific diagram types (Flowchart, Sequence, etc.)
+    # inherit from this base and add their type-specific attributes.
+    #
+    # All diagram models use Lutaml::Model for serialization support.
+    #
+    # @example Define a custom diagram type
+    #   class Flowchart < Diagram::Base
+    #     attribute :nodes, :array
+    #     attribute :edges, :array
+    #   end
+    #
+    # @abstract Subclass and add diagram-specific attributes
+    class Base < Lutaml::Model::Serializable
+      # Unique identifier for the diagram
+      attribute :id, :string
+
+      # Optional title for the diagram
+      attribute :title, :string
+
+      # Direction or orientation of the diagram
+      # (e.g., 'TB' for top-to-bottom, 'LR' for left-to-right)
+      attribute :direction, :string
+
+      # Optional theme or style configuration
+      attribute :theme, :string
+
+      # Validates that required diagram structure is present.
+      #
+      # This method should be overridden by subclasses to implement
+      # diagram-specific validation logic.
+      #
+      # @return [Boolean] true if diagram is valid
+      # @raise [NotImplementedError] if not implemented by subclass
+      def valid?
+        raise NotImplementedError,
+              "#{self.class} must implement #valid?"
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # This method should be overridden by subclasses to return their
+      # specific diagram type.
+      #
+      # @return [Symbol] the diagram type identifier
+      # @raise [NotImplementedError] if not implemented by subclass
+      def diagram_type
+        raise NotImplementedError,
+              "#{self.class} must implement #diagram_type"
+      end
+    end
+  end
+end

data/lib/etassia/diagram/block.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  module Diagram
+    # Represents a block in the diagram
+    class BlockNode < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :label, :string
+      attribute :width, :integer, default: -> { 1 }
+      attribute :shape, :string, default: -> { "rect" }
+      attribute :children, BlockNode, collection: true, default: -> { [] }
+      attribute :block_type, :string # "block", "space", "arrow"
+      # Arrow block directions: "up", "down", "left", or "right".
+      attribute :direction, :string
+      attribute :is_compound, :boolean, default: -> { false }
+
+      def compound?
+        is_compound
+      end
+
+      def space?
+        block_type == "space"
+      end
+
+      def arrow?
+        block_type == "arrow"
+      end
+
+      def add_child(child)
+        children << child
+        self.is_compound = true
+      end
+    end
+
+    # Represents a connection between blocks
+    class BlockConnection < Lutaml::Model::Serializable
+      attribute :from, :string
+      attribute :to, :string
+      attribute :connection_type, :string # "arrow" or "line"
+      attribute :label, :string
+
+      def arrow?
+        connection_type == "arrow"
+      end
+
+      def line?
+        connection_type == "line"
+      end
+    end
+
+    # Represents styling for a block
+    class BlockStyle < Lutaml::Model::Serializable
+      attribute :block_id, :string
+      attribute :fill, :string
+      attribute :stroke, :string
+      attribute :stroke_width, :string
+      attribute :properties, :string, collection: true, default: -> { [] }
+    end
+
+    # Represents a Mermaid block diagram
+    class Block < Base
+      attribute :columns, :integer
+      attribute :blocks, BlockNode, collection: true, default: -> { [] }
+      attribute :connections,
+                BlockConnection,
+                collection: true,
+                default: -> { [] }
+      attribute :styles, BlockStyle, collection: true, default: -> { [] }
+
+      def add_block(block)
+        blocks << block
+      end
+
+      def add_connection(connection)
+        connections << connection
+      end
+
+      def add_style(style)
+        styles << style
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :block
+      def diagram_type
+        :block
+      end
+
+      # Block diagrams have no validation rules yet. 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/c4.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+
+module Etassia
+  module Diagram
+    # Represents a C4 element (Person, System, Container, Component).
+    #
+    # Elements are the nodes in C4 diagrams representing various architectural
+    # entities like people, systems, containers, and components.
+    class C4Element < Lutaml::Model::Serializable
+      # Unique identifier for the element
+      attribute :id, :string
+
+      # Display label
+      attribute :label, :string
+
+      # Element type: Person, Person_Ext, System, System_Ext, SystemDb,
+      # SystemDb_Ext, SystemQueue, SystemQueue_Ext, Container, ContainerDb,
+      # ContainerQueue, Component
+      attribute :element_type, :string
+
+      # Description text
+      attribute :description, :string
+
+      # Technology stack (for Containers and Components)
+      attribute :technology, :string
+
+      # Sprite icon name
+      attribute :sprite, :string
+
+      # Link URL
+      attribute :link, :string
+
+      # Tags (comma-separated)
+      attribute :tags, :string
+
+      # Whether element is external (_Ext suffix)
+      attribute :external, :boolean, default: -> { false }
+
+      # Parent boundary ID (if nested)
+      attribute :boundary_id, :string
+
+      # Validates the element has required attributes.
+      #
+      # @return [Boolean] true if element is valid
+      def valid?
+        [id, label].all? { |value| value && !value.empty? } &&
+          !element_type.nil?
+      end
+
+      # Returns base type without _Ext suffix
+      #
+      # @return [String] base element type
+      def base_type
+        element_type&.gsub(/_Ext$/, "") || element_type
+      end
+
+      # Check if element is a person
+      #
+      # @return [Boolean] true if person
+      def person?
+        base_type == "Person"
+      end
+
+      # Check if element is a system
+      #
+      # @return [Boolean] true if system
+      def system?
+        %w[System SystemDb SystemQueue].include?(base_type)
+      end
+
+      # Check if element is a container
+      #
+      # @return [Boolean] true if container
+      def container?
+        %w[Container ContainerDb ContainerQueue].include?(base_type)
+      end
+
+      # Check if element is a component
+      #
+      # @return [Boolean] true if component
+      def component?
+        base_type == "Component"
+      end
+    end
+
+    # Represents a C4 relationship between elements.
+    #
+    # Relationships show interactions or dependencies between architectural
+    # elements.
+    class C4Relationship < Lutaml::Model::Serializable
+      # Source element identifier
+      attribute :from_id, :string
+
+      # Target element identifier
+      attribute :to_id, :string
+
+      # Relationship label
+      attribute :label, :string
+
+      # Technology used in relationship
+      attribute :technology, :string
+
+      # Relationship type: Rel, BiRel
+      attribute :rel_type, :string
+
+      # Initialize with default type
+      def initialize(*args)
+        super
+        self.rel_type ||= "Rel"
+      end
+
+      # Validates the relationship has required attributes.
+      #
+      # @return [Boolean] true if relationship is valid
+      def valid?
+        !from_id.nil? && !from_id.empty? &&
+          !to_id.nil? && !to_id.empty?
+      end
+
+      # Check if bidirectional relationship
+      #
+      # @return [Boolean] true if bidirectional
+      def bidirectional?
+        rel_type == "BiRel"
+      end
+    end
+
+    # Represents a C4 boundary grouping.
+    #
+    # Boundaries group related elements together, representing enterprise
+    # boundaries, system boundaries, or custom boundaries.
+    class C4Boundary < Lutaml::Model::Serializable
+      # Unique identifier for the boundary
+      attribute :id, :string
+
+      # Display label
+      attribute :label, :string
+
+      # Boundary type: Enterprise_Boundary, System_Boundary, Boundary
+      attribute :boundary_type, :string
+
+      # Additional type parameter (for generic Boundary)
+      attribute :type_param, :string
+
+      # Link URL
+      attribute :link, :string
+
+      # Tags (comma-separated)
+      attribute :tags, :string
+
+      # Nested elements (element IDs)
+      attribute :element_ids, :string, collection: true, default: -> { [] }
+
+      # Nested boundaries (boundary IDs)
+      attribute :boundary_ids, :string, collection: true, default: -> { [] }
+
+      # Parent boundary ID (if nested)
+      attribute :parent_id, :string
+
+      # Initialize with default type
+      def initialize(*args)
+        super
+        self.boundary_type ||= "Boundary"
+      end
+
+      # Validates the boundary has required attributes.
+      #
+      # @return [Boolean] true if boundary is valid
+      def valid?
+        !id.nil? && !id.empty? &&
+          !label.nil? && !label.empty?
+      end
+
+      # Check if enterprise boundary
+      #
+      # @return [Boolean] true if enterprise boundary
+      def enterprise?
+        boundary_type == "Enterprise_Boundary"
+      end
+
+      # Check if system boundary
+      #
+      # @return [Boolean] true if system boundary
+      def system?
+        boundary_type == "System_Boundary"
+      end
+    end
+
+    # C4 diagram model.
+    #
+    # Represents a complete C4 diagram showing software architecture at
+    # different levels of abstraction: Context, Container, Component, or Code.
+    #
+    # @example Creating a C4 Context diagram
+    #   c4 = C4.new(level: 'Context')
+    #   c4.title = 'System Context diagram'
+    #   c4.elements << C4Element.new(
+    #     id: 'customer',
+    #     label: 'Customer',
+    #     element_type: 'Person',
+    #     description: 'A user of the system'
+    #   )
+    #   c4.elements << C4Element.new(
+    #     id: 'system',
+    #     label: 'Banking System',
+    #     element_type: 'System',
+    #     description: 'Main banking application'
+    #   )
+    #   c4.relationships << C4Relationship.new(
+    #     from_id: 'customer',
+    #     to_id: 'system',
+    #     label: 'Uses'
+    #   )
+    class C4 < Base
+      # C4 level: Context, Container, Component, Dynamic, Deployment
+      attribute :level, :string
+
+      # Diagram title
+      attribute :title, :string
+
+      # Collection of elements
+      attribute :elements, C4Element, collection: true, default: -> { [] }
+
+      # Collection of relationships
+      attribute :relationships, C4Relationship, collection: true,
+                                                default: -> { [] }
+
+      # Collection of boundaries
+      attribute :boundaries, C4Boundary, collection: true, default: -> { [] }
+
+      # Layout configuration
+      attribute :layout_config, :string
+
+      # Initialize with default level
+      def initialize(*args)
+        super
+        self.level ||= "Context"
+      end
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :c4
+      def diagram_type
+        :c4
+      end
+
+      # Validates the C4 diagram structure.
+      #
+      # A C4 diagram is valid if:
+      # - It has a valid level
+      # - All elements are valid
+      # - All relationships are valid
+      # - All boundaries are valid
+      # - All relationship references point to existing elements
+      #
+      # @return [Boolean] true if C4 diagram is valid
+      def valid?
+        valid_level? && valid_collections? && relationship_references_resolve?
+      end
+
+      # Finds an element by its identifier.
+      #
+      # @param id [String] the element identifier to find
+      # @return [C4Element, nil] the element or nil if not found
+      def find_element(id)
+        elements.find { |e| e.id == id }
+      end
+
+      # Finds a boundary by its identifier.
+      #
+      # @param id [String] the boundary identifier to find
+      # @return [C4Boundary, nil] the boundary or nil if not found
+      def find_boundary(id)
+        boundaries.find { |b| b.id == id }
+      end
+
+      # Finds relationships from a specific element.
+      #
+      # @param element_id [String] the source element identifier
+      # @return [Array<C4Relationship>] relationships from the element
+      def relationships_from(element_id)
+        relationships.select { |r| r.from_id == element_id }
+      end
+
+      # Finds relationships to a specific element.
+      #
+      # @param element_id [String] the target element identifier
+      # @return [Array<C4Relationship>] relationships to the element
+      def relationships_to(element_id)
+        relationships.select { |r| r.to_id == element_id }
+      end
+
+      # Finds elements within a boundary.
+      #
+      # @param boundary_id [String] the boundary identifier
+      # @return [Array<C4Element>] elements in the boundary
+      def elements_in_boundary(boundary_id)
+        elements.select { |e| e.boundary_id == boundary_id }
+      end
+
+      # Finds child boundaries within a parent boundary.
+      #
+      # @param boundary_id [String] the parent boundary identifier
+      # @return [Array<C4Boundary>] child boundaries
+      def boundaries_in_boundary(boundary_id)
+        boundaries.select { |b| b.parent_id == boundary_id }
+      end
+
+      private
+
+      def valid_level?
+        %w[Context Container Component Dynamic Deployment].include?(level)
+      end
+
+      def valid_collections?
+        valid_collection?(elements) && valid_collection?(relationships) &&
+          valid_collection?(boundaries)
+      end
+
+      def valid_collection?(items)
+        items.nil? || items.all?(&:valid?)
+      end
+
+      def relationship_references_resolve?
+        element_ids = elements.map(&:id)
+
+        relationships.nil? || relationships.all? do |relationship|
+          element_ids.include?(relationship.from_id) &&
+            element_ids.include?(relationship.to_id)
+        end
+      end
+    end
+  end
+end