etassia 0.1.0

data/lib/etassia/diagram/class_diagram.rb

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "base"
+require_relative "generic_text"
+require_relative "class_note"
+require_relative "class_namespace"
+
+module Etassia
+  module Diagram
+    # Represents a class attribute in a UML class diagram.
+    #
+    # An attribute has a name, type, and visibility modifier that
+    # controls its access level.
+    class ClassAttribute < Lutaml::Model::Serializable
+      VISIBILITY_SYMBOLS = {
+        "private" => "-",
+        "protected" => "#",
+        "package" => "~",
+      }.freeze
+
+      # Attribute name
+      attribute :name, :string
+
+      # Attribute type (e.g., 'string', 'int', 'List~String~')
+      attribute :type, :string
+
+      # Visibility: :public (+), :private (-), :protected (#),
+      # :package (~)
+      attribute :visibility, :string
+
+      # The member as written in the source, when it came from a parser
+      attribute :text, :string
+
+      # Initialize with default visibility
+      def initialize(*args)
+        super
+        self.visibility ||= "public"
+      end
+
+      # The text a row draws: the source text as written, with generics shown
+      # as `<T>` and the `*`/`$` classifier mark left off.
+      #
+      # @return [String] the row text
+      def display_text
+        return fallback_text unless text
+
+        GenericText.display_member(text.sub(/\s*[*$]\z/, "").gsub(/\s+/, " "))
+      end
+
+      # Validates the attribute has required fields.
+      #
+      # @return [Boolean] true if attribute is valid
+      def valid?
+        !name.nil? && !name.empty?
+      end
+
+      # Returns the UML visibility symbol.
+      #
+      # @return [String] the visibility symbol (+, -, #, ~)
+      def visibility_symbol
+        VISIBILITY_SYMBOLS.fetch(visibility, "+")
+      end
+
+      private
+
+      def fallback_text
+        row = "#{visibility_symbol} #{name}"
+        row += ": #{type}" if type && !type.empty?
+        row
+      end
+    end
+
+    # Represents a class method in a UML class diagram.
+    #
+    # A method has a name, optional parameters, optional return type,
+    # and visibility modifier.
+    class ClassMethod < Lutaml::Model::Serializable
+      VISIBILITY_SYMBOLS = ClassAttribute::VISIBILITY_SYMBOLS
+
+      # Method name
+      attribute :name, :string
+
+      # Method parameters (e.g., 'x: int, y: int')
+      attribute :parameters, :string
+
+      # Return type (e.g., 'string', 'void')
+      attribute :return_type, :string
+
+      # Visibility: :public (+), :private (-), :protected (#),
+      # :package (~)
+      attribute :visibility, :string
+
+      # The member as written in the source, when it came from a parser
+      attribute :text, :string
+
+      # Initialize with default visibility
+      def initialize(*args)
+        super
+        self.visibility ||= "public"
+      end
+
+      # The text a row draws: the source up to the `(` as written, then the
+      # parameters, then ` : ` and the return type, generics shown as `<T>`.
+      #
+      # @return [String] the row text
+      def display_text
+        return fallback_text unless text
+
+        head = text[/\A[^(]*/].gsub(/\s+/, " ").rstrip
+        row = "#{head}(#{parameters})"
+        row += " : #{return_type}" if return_type
+        GenericText.display_member(row)
+      end
+
+      # Validates the method has required fields.
+      #
+      # @return [Boolean] true if method is valid
+      def valid?
+        !name.nil? && !name.empty?
+      end
+
+      # Returns the UML visibility symbol.
+      #
+      # @return [String] the visibility symbol (+, -, #, ~)
+      def visibility_symbol
+        VISIBILITY_SYMBOLS.fetch(visibility, "+")
+      end
+
+      # Returns the full method signature.
+      #
+      # @return [String] method signature with parameters and return type
+      def signature
+        sig = name
+        sig += "(#{parameters})" if parameters && !parameters.empty?
+        sig += " #{return_type}" if return_type && !return_type.empty?
+        sig
+      end
+
+      private
+
+      def fallback_text
+        row = "#{visibility_symbol} #{name}"
+        row += "(#{parameters})" if parameters
+        row += ": #{return_type}" if return_type
+        row
+      end
+    end
+
+    # Represents a class/entity in a UML class diagram.
+    #
+    # A class entity has an identifier, name, optional stereotype,
+    # collection of attributes, and collection of methods.
+    class ClassEntity < Lutaml::Model::Serializable
+      # Unique identifier for the class
+      attribute :id, :string
+
+      # Display name for the class
+      attribute :name, :string
+
+      # Optional stereotype (e.g., 'interface', 'abstract', 'enum')
+      attribute :stereotype, :string
+
+      # Collection of class attributes
+      attribute :attributes, ClassAttribute, collection: true,
+                                             default: -> { [] }
+
+      # Collection of class methods
+      attribute :class_methods, ClassMethod, collection: true,
+                                             default: -> { [] }
+
+      # Validates the class entity has required fields.
+      #
+      # @return [Boolean] true if class entity is valid
+      def valid?
+        present?(id) && present?(name) && attributes.all?(&:valid?) &&
+          class_methods.all?(&:valid?)
+      end
+
+      # Checks if this is an interface.
+      #
+      # @return [Boolean] true if stereotype is 'interface'
+      def interface?
+        stereotype == "interface"
+      end
+
+      # Checks if this is an abstract class.
+      #
+      # @return [Boolean] true if stereotype is 'abstract'
+      def abstract?
+        stereotype == "abstract"
+      end
+
+      # Checks if this is an enum.
+      #
+      # @return [Boolean] true if stereotype is 'enum'
+      def enum?
+        stereotype == "enum"
+      end
+
+      private
+
+      def present?(value)
+        !value.nil? && !value.empty?
+      end
+    end
+
+    # Represents a relationship between classes in a UML class diagram.
+    #
+    # A relationship connects two classes with a specific type
+    # (inheritance, composition, aggregation, or association) and
+    # optional label and cardinality.
+    class ClassRelationship < Lutaml::Model::Serializable
+      # Source class identifier
+      attribute :from_id, :string
+
+      # Target class identifier
+      attribute :to_id, :string
+
+      # Relationship type: :inheritance, :composition, :aggregation,
+      # :association, :dependency, :realization
+      attribute :relationship_type, :string
+
+      # Optional relationship label
+      attribute :label, :string
+
+      # Optional cardinality for source end (e.g., '1', '0..1', '1..*')
+      attribute :source_cardinality, :string
+
+      # Optional cardinality for target end (e.g., '1', '0..1', '1..*')
+      attribute :target_cardinality, :string
+
+      # Marker drawn at the from_id end, independent of relationship_type.
+      # Only set for mixed-marker operators (e.g. `o--|>`) where each end
+      # carries its own marker; nil for the single-type operators, which
+      # render entirely from relationship_type. One of 'inheritance',
+      # 'composition', 'aggregation', 'dependency', or nil (no marker).
+      attribute :start_marker, :string
+
+      # Marker drawn at the to_id end. Same rules as start_marker.
+      attribute :end_marker, :string
+
+      # True when the source wrote the ends the other way round (`A <|-- B`
+      # is stored B -> A). mmdc ranks the written order, so layout needs it.
+      attribute :written_reversed, :boolean
+
+      # Line style override for mixed-marker operators (nil elsewhere):
+      # true renders a dashed line, matching the operator's own line type
+      # rather than relationship_type's usual dash rule.
+      attribute :dashed, :boolean
+
+      # Initialize with default relationship type
+      def initialize(*args)
+        super
+        self.relationship_type ||= "association"
+      end
+
+      # Validates the relationship has required fields.
+      #
+      # @return [Boolean] true if relationship is valid
+      def valid?
+        [from_id, to_id, relationship_type].all? do |value|
+          value && !value.empty?
+        end
+      end
+
+      # Checks if this is an inheritance relationship.
+      #
+      # @return [Boolean] true if inheritance type
+      def inheritance?
+        relationship_type == "inheritance"
+      end
+
+      # Checks if this is a composition relationship.
+      #
+      # @return [Boolean] true if composition type
+      def composition?
+        relationship_type == "composition"
+      end
+
+      # Checks if this is an aggregation relationship.
+      #
+      # @return [Boolean] true if aggregation type
+      def aggregation?
+        relationship_type == "aggregation"
+      end
+
+      # Checks if this is an association relationship.
+      #
+      # @return [Boolean] true if association type
+      def association?
+        relationship_type == "association"
+      end
+
+      # Checks if this is a dependency relationship.
+      #
+      # @return [Boolean] true if dependency type
+      def dependency?
+        relationship_type == "dependency"
+      end
+
+      # Checks if this is a realization relationship.
+      #
+      # @return [Boolean] true if realization type
+      def realization?
+        relationship_type == "realization"
+      end
+    end
+
+    # Class diagram model.
+    #
+    # Represents a complete UML class diagram with classes and their
+    # relationships. Class diagrams show the static structure of a
+    # system with classes, attributes, methods, and relationships.
+    #
+    # @example Creating a simple class diagram
+    #   diagram = ClassDiagram.new(direction: 'TB')
+    #   diagram.entities << ClassEntity.new(
+    #     id: 'Animal',
+    #     name: 'Animal'
+    #   ).tap do |entity|
+    #     entity.attributes << ClassAttribute.new(
+    #       name: 'age',
+    #       type: 'int',
+    #       visibility: 'protected'
+    #     )
+    #     entity.class_methods << ClassMethod.new(
+    #       name: 'breathe',
+    #       visibility: 'public'
+    #     )
+    #   end
+    #   diagram.entities << ClassEntity.new(
+    #     id: 'Dog',
+    #     name: 'Dog'
+    #   ).tap do |entity|
+    #     entity.class_methods << ClassMethod.new(
+    #       name: 'bark',
+    #       visibility: 'public'
+    #     )
+    #   end
+    #   diagram.relationships << ClassRelationship.new(
+    #     from_id: 'Dog',
+    #     to_id: 'Animal',
+    #     relationship_type: 'inheritance'
+    #   )
+    class ClassDiagram < Base
+      # Collection of class entities in the diagram
+      attribute :entities, ClassEntity, collection: true,
+                                        default: -> { [] }
+
+      # Collection of relationships between entities
+      attribute :relationships, ClassRelationship, collection: true,
+                                                   default: -> { [] }
+
+      # Notes written with `note` / `note for`, in source order
+      attribute :notes, ClassNote, collection: true, default: -> { [] }
+
+      # Namespace blocks, in source order
+      attribute :namespaces, ClassNamespace, collection: true,
+                                             default: -> { [] }
+
+      # Diagram-wide font from a Mermaid init `fontFamily`, e.g. "courier"
+      attribute :font_family, :string
+
+      # Returns the diagram type identifier.
+      #
+      # @return [Symbol] :class_diagram
+      def diagram_type
+        :class_diagram
+      end
+
+      # Validates the class diagram structure.
+      #
+      # A class diagram is valid if:
+      # - All entities are valid
+      # - All relationships are valid
+      # - All relationship references point to existing entities
+      #
+      # @return [Boolean] true if class diagram is valid
+      def valid?
+        entities.all?(&:valid?) && valid_relationships?
+      end
+
+      # Finds an entity by its identifier.
+      #
+      # @param id [String] the entity identifier to find
+      # @return [ClassEntity, nil] the entity or nil if not found
+      def find_entity(id)
+        entities.find { |e| e.id == id }
+      end
+
+      # Finds all relationships from a specific entity.
+      #
+      # @param entity_id [String] the source entity identifier
+      # @return [Array<ClassRelationship>] relationships from the entity
+      def relationships_from(entity_id)
+        relationships.select { |r| r.from_id == entity_id }
+      end
+
+      # Finds all relationships to a specific entity.
+      #
+      # @param entity_id [String] the target entity identifier
+      # @return [Array<ClassRelationship>] relationships to the entity
+      def relationships_to(entity_id)
+        relationships.select { |r| r.to_id == entity_id }
+      end
+
+      # Finds all inheritance relationships.
+      #
+      # @return [Array<ClassRelationship>] inheritance relationships
+      def inheritance_relationships
+        relationships.select(&:inheritance?)
+      end
+
+      # Finds all composition relationships.
+      #
+      # @return [Array<ClassRelationship>] composition relationships
+      def composition_relationships
+        relationships.select(&:composition?)
+      end
+
+      # Finds all aggregation relationships.
+      #
+      # @return [Array<ClassRelationship>] aggregation relationships
+      def aggregation_relationships
+        relationships.select(&:aggregation?)
+      end
+
+      # Finds parent classes for a given entity.
+      #
+      # @param entity_id [String] the entity identifier
+      # @return [Array<ClassEntity>] parent entities
+      def parent_entities(entity_id)
+        parent_ids = relationships
+          .select { |r| r.from_id == entity_id && r.inheritance? }
+          .map(&:to_id)
+        entities.select { |e| parent_ids.include?(e.id) }
+      end
+
+      # Finds child classes for a given entity.
+      #
+      # @param entity_id [String] the entity identifier
+      # @return [Array<ClassEntity>] child entities
+      def child_entities(entity_id)
+        child_ids = relationships
+          .select { |r| r.to_id == entity_id && r.inheritance? }
+          .map(&:from_id)
+        entities.select { |e| child_ids.include?(e.id) }
+      end
+
+      private
+
+      def valid_relationships?
+        relationships.nil? || relationships.all? do |relationship|
+          relationship.valid? && relationship_references_resolve?(relationship)
+        end
+      end
+
+      def relationship_references_resolve?(relationship)
+        entity_ids = entities.map(&:id)
+        entity_ids.include?(relationship.from_id) &&
+          entity_ids.include?(relationship.to_id)
+      end
+    end
+  end
+end

data/lib/etassia/diagram/class_namespace.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Diagram
+    # A `namespace Name { ... }` block of a class diagram: the box mmdc
+    # draws around the classes written inside it.
+    class ClassNamespace < Lutaml::Model::Serializable
+      # The namespace name, as written
+      attribute :name, :string
+
+      # The ids of the entities declared inside the block
+      attribute :class_ids, :string, collection: true, default: -> { [] }
+    end
+  end
+end

data/lib/etassia/diagram/class_note.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Diagram
+    # A `note "text"` or `note for Class "text"` statement of a class
+    # diagram.
+    class ClassNote < Lutaml::Model::Serializable
+      # The note text, without its surrounding quotes
+      attribute :text, :string
+
+      # The id of the class the note is attached to; nil for a general note
+      attribute :target_id, :string
+    end
+  end
+end

data/lib/etassia/diagram/containment.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Diagram
+    # Cycle detection over a graph of box ids.
+    #
+    # Two callers, and their graphs run in OPPOSITE directions. The
+    # parser transform passes what each subgraph's SOURCE encloses —
+    # id to the ids inside it — before any model exists, so it can
+    # refuse `a` inside `b` inside `a` the way mmdc does. The flowchart
+    # model passes the `parent_id` graph — id to the id above it — of a
+    # model somebody built by hand, where the same loop hangs those
+    # boxes off each other and none of them is ever placed.
+    #
+    # So this reads edges, not parentage. It says whether following the
+    # arrows returns you to where you started; what an arrow MEANS is
+    # the caller's business, including which way round to read the pair
+    # that comes back.
+    #
+    # @api private
+    module Containment
+      module_function
+
+      # One walk over the whole graph, not one per box. Asking each box
+      # in turn whether it reaches itself re-walks the same subtree once
+      # per ancestor, which on the parser's graph — where a box lists
+      # everything below it, not just its direct children — cost 2.6
+      # seconds for 200 nested boxes against 0.2 for this.
+      #
+      # A box already walked to the end is left alone, which is what
+      # makes it one pass — reaching it again cannot find a loop the
+      # first visit missed.
+      #
+      # Keys are visited in insertion order, so a graph closing more
+      # than one loop always reports the same one.
+      #
+      # @param graph [Hash{Object => Array}] id to the ids it points at
+      # @return [Array(Object, Object), nil] the edge that closed the
+      #   loop, as [from, to], or nil when there is none
+      def looping_pair(graph)
+        colour = {}
+        graph.each_key do |root|
+          found = back_edge(graph, root, colour)
+          return found unless found.nil?
+        end
+        nil
+      end
+
+      # An explicit stack, not recursion. A flat chain of 4,000 boxes is
+      # a source mmdc draws, and the recursive form raised a bare
+      # SystemStackError out of the parse and into the caller.
+      #
+      # `colour` is threaded through the whole walk rather than reset
+      # per root, which is what keeps it to one pass.
+      #
+      # Grey is on the path being walked, black is finished. Meeting a
+      # grey box closes the loop, and BOTH ends get named rather than
+      # just the one we arrived at: the parser turns the pair into
+      # mermaid's "Setting b as parent of a", and naming one box twice
+      # misreported every two-box loop.
+      def back_edge(graph, root, colour)
+        return nil if colour.key?(root)
+
+        colour[root] = :grey
+        stack = [[root, 0]]
+        until stack.empty?
+          found = advance_walk(graph, colour, stack)
+          return found unless found.nil?
+        end
+        nil
+      end
+
+      def advance_walk(graph, colour, stack)
+        box, taken = stack.last
+        children = graph.fetch(box, [])
+        return finish_box(colour, stack, box) if taken >= children.size
+
+        child = take_child(stack, children, taken)
+        return [box, child] if colour[child] == :grey
+
+        visit_child(colour, stack, child) unless colour.key?(child)
+        nil
+      end
+
+      def finish_box(colour, stack, box)
+        colour[box] = :black
+        stack.pop
+        nil
+      end
+
+      def take_child(stack, children, taken)
+        stack.last[1] = taken + 1
+        children[taken]
+      end
+
+      def visit_child(colour, stack, child)
+        colour[child] = :grey
+        stack << [child, 0]
+      end
+      private_class_method :back_edge
+      private_class_method :advance_walk
+      private_class_method :finish_box
+      private_class_method :take_child
+      private_class_method :visit_child
+    end
+  end
+end