diagram 0.3.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4af5a1be5db0b92fbdd6a3c6d41eec3d78dd3bd36c6ba6bb70897f552bfdf27
-  data.tar.gz: 967838b7e5d58ee6ffa188cfc623a130fdb0223e586118c3e11ea1c66fff16cc
+  metadata.gz: c99defb74ddced6d50a0dd2bd5cf61b90ce2edab9192c5f119586442eb625d12
+  data.tar.gz: 1bd666eed832e6052f789c3a37fd634d2cb4c198468281bafc17bc1ca500d05a
 SHA512:
-  metadata.gz: 90b0513c6e57596f3c769f01a693b1615cbd9044f8dfc2d97a17432073b9f5415b23b0724c91f121219b767f892d4977eac598e33159d4ca83cd892bf00235f3
-  data.tar.gz: 1dac456dbecc729f32da2a863bd0605e9ee4b830982920b56c54b68dae4ce27ad635e0ad68bd6fc5029838a5f994553da9592dd09390301f465b1f4ceea09ca9
+  metadata.gz: f9d0b5269c5093821a09140273590af586dc35e4a21b9aed5c45a5201db8ebcfdb769e3764038fe0a74e467eea3d18e1f1fc970c295e69fefbdc686230106b48
+  data.tar.gz: 7a53a67aecab0fa28adee1e6f826114ad0f0184e994e31c346d9b3224a4fd72e255ed4eaea714327c467664cef766ae2da1cbded21c58d620d7cb5862c65617d

data/lib/diagram.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'diagrams'

data/lib/diagrams/base.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require 'digest'
-require 'json'
-require 'dry-equalizer'
-
 module Diagrams
   # Abstract base class for all diagram types.
   # Provides common functionality like versioning, checksum calculation,
@@ -69,12 +65,14 @@ module Diagrams
         self_collection = self_elements[type] || []
         other_collection = other_elements[type] || []
 
-        # Determine identifier method (prefer id, then name, fallback to object itself)
+        # Determine identifier method (prefer id, then name, then title, then label, fallback to object itself)
         identifier_method = if self_collection.first.respond_to?(:id)
                               :id
                             elsif self_collection.first.respond_to?(:name)
                               :name
-                            elsif self_collection.first.respond_to?(:label) # For Slice
+                            elsif self_collection.first.respond_to?(:title) # For TimelineSection
+                              :title
+                            elsif self_collection.first.respond_to?(:label) # For Slice, TimelinePeriod
                               :label
                             else
                               :itself # Fallback to object identity/equality
@@ -198,6 +196,10 @@ module Diagrams
       # Simple helper to convert snake_case to CamelCase
       # (Avoids ActiveSupport dependency)
       def snake_to_camel_case(string)
+        # Handle specific acronyms first
+        return 'ERDiagram' if string == 'er_diagram'
+
+        # Default conversion
         string.split('_').collect(&:capitalize).join
       end
     end

data/lib/diagrams/class_diagram.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/class_entity'
-require_relative 'elements/relationship'
-
 module Diagrams
   # Represents a UML Class Diagram consisting of classes and relationships between them.
   class ClassDiagram < Base

data/lib/diagrams/elements/class_entity.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a class entity in a UML Class Diagram.
     class ClassEntity < Dry::Struct

data/lib/diagrams/elements/edge.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents an edge or link between two nodes in a diagram.
     # Typically connects nodes via their IDs and can have an optional label.

data/lib/diagrams/elements/erd_attribute.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents an attribute within an ERD entity.
+    class ERDAttribute < Dry::Struct
+      include Elements::Types
+
+      attribute :type, Types::Strict::String.constrained(min_size: 1)
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+      attribute :keys, Types::Strict::Array.of(Types::Strict::Symbol.enum(:PK, :FK, :UK)).default([].freeze)
+      attribute :comment, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Symbol>}]
+      def to_h
+        hash = {
+          type:,
+          name:,
+          keys: keys.map(&:to_s) # Convert symbols to strings for serialization
+        }
+        hash[:comment] = comment if comment
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/erd_entity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents an entity (table) in an ER Diagram.
+    class ERDEntity < Dry::Struct
+      include Elements::Types
+
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+      attribute :entity_attributes, Types::Strict::Array.of(ERDAttribute).default([].freeze)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          name: name,
+          attributes: entity_attributes.map(&:to_h) # Renamed variable
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/erd_relationship.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a relationship between two entities in an ER Diagram.
+    class ERDRelationship < Dry::Struct
+      include Elements::Types
+
+      # Cardinality symbols (Crow's Foot notation mapping)
+      CARDINALITY = Types::Strict::Symbol.enum(
+        :ZERO_OR_ONE,  # |o
+        :ONE_ONLY,     # ||
+        :ZERO_OR_MORE, # }o
+        :ONE_OR_MORE   # }|
+      )
+
+      attribute :entity1, Types::Strict::String.constrained(min_size: 1)
+      attribute :entity2, Types::Strict::String.constrained(min_size: 1)
+      attribute :cardinality1, CARDINALITY # Cardinality of entity1 relative to entity2
+      attribute :cardinality2, CARDINALITY # Cardinality of entity2 relative to entity1
+      attribute :identifying, Types::Strict::Bool.default(false) # Is it an identifying relationship? (solid vs dashed line)
+      attribute :label, Types::Strict::String.optional.default(nil) # Optional action/verb phrase
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Symbol | Bool}]
+      def to_h
+        hash = {
+          entity1: entity1,
+          entity2: entity2,
+          cardinality1: cardinality1.to_s, # Convert symbol to string
+          cardinality2: cardinality2.to_s, # Convert symbol to string
+          identifying: identifying
+        }
+        hash[:label] = label if label
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/event.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents an event, potentially used in State Diagrams or others.
     class Event < Dry::Struct

data/lib/diagrams/elements/gantt_section.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a section within a Gantt chart, grouping multiple tasks.
+    class GanttSection < Dry::Struct
+      include Elements::Types
+
+      attribute :title, Types::Strict::String.constrained(min_size: 1)
+      attribute :tasks, Types::Strict::Array.of(Task).default([].freeze)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          title:,
+          tasks: tasks.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/git_branch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a branch in a Gitgraph diagram.
+    class GitBranch < Dry::Struct
+      include Elements::Types
+
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+      # head_commit_id can be nil initially if the branch is created before any commits
+      attribute :head_commit_id, Types::Strict::String.optional.default(nil)
+      attribute :start_commit_id, Types::Strict::String.constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+      def to_h
+        hash = {
+          name:,
+          start_commit_id:
+        }
+        hash[:head_commit_id] = head_commit_id if head_commit_id
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/git_commit.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a commit in a Gitgraph diagram.
+    class GitCommit < Dry::Struct
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :parent_ids, Types::Strict::Array.of(Types::Strict::String).default([].freeze)
+      attribute :branch_name, Types::Strict::String.constrained(min_size: 1)
+      attribute :message, Types::Strict::String.optional.default(nil)
+      attribute :tag, Types::Strict::String.optional.default(nil)
+      attribute :type, Types::Strict::Symbol.default(:NORMAL).enum(:NORMAL, :REVERSE, :HIGHLIGHT, :MERGE, :CHERRY_PICK)
+      attribute :cherry_pick_source_id, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      # Dry::Struct provides to_h, but explicit definition ensures desired keys/structure.
+      # Optional attributes are included only if they have non-nil values.
+      #
+      # @return [Hash{Symbol => String | Array<String> | Symbol}]
+      def to_h
+        hash = {
+          id:,
+          parent_ids:,
+          branch_name:,
+          type:
+        }
+        hash[:message] = message if message
+        hash[:tag] = tag if tag
+        hash[:cherry_pick_source_id] = cherry_pick_source_id if cherry_pick_source_id
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/node.rb

@@ -1,17 +1,9 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require 'dry-types'
-
 module Diagrams
   # Namespace for diagram element value objects.
 
   module Elements
-    # Common Dry::Types definitions for elements.
-    module Types
-      include Dry.Types()
-    end
-
     # Represents a node in various diagram types (e.g., Flowchart).
     # Typically has an identifier and a display label.
     class Node < Dry::Struct

data/lib/diagrams/elements/relationship.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a relationship (e.g., association, inheritance) between two classes
     # in a UML Class Diagram.

data/lib/diagrams/elements/slice.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a slice in a Pie Diagram.
     class Slice < Dry::Struct

data/lib/diagrams/elements/state.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a state in a State Diagram.
     class State < Dry::Struct

data/lib/diagrams/elements/task.rb

@@ -1,27 +1,35 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a task in a Gantt Diagram.
     class Task < Dry::Struct
       # Use the shared Types module
       include Elements::Types
 
-      attribute :id, Types::Strict::String.constrained(min_size: 1)
-      attribute :name, Types::Strict::String.constrained(min_size: 1)
-      # Using String for dates initially for simplicity.
-      # Consider Types::Strict::Date or custom coercible types later.
-      attribute :start_date, Types::Strict::String.constrained(min_size: 1) # Basic check
-      attribute :end_date, Types::Strict::String.constrained(min_size: 1)   # Basic check
-      # TODO: Add dependencies attribute (e.g., Types::Strict::Array.of(Types::Strict::String))
+      # Status symbols allowed by Mermaid Gantt
+      STATUS = Types::Strict::Symbol.enum(:done, :active, :crit)
+
+      # Attributes
+      attribute :id, Types::Strict::String.constrained(min_size: 1) # Unique ID for dependencies
+      attribute :label, Types::Strict::String.constrained(min_size: 1) # Display name
+      attribute :status, STATUS.optional.default(nil) # Task status (nil implies default/future)
+      attribute :start, Types::Strict::String.constrained(min_size: 1) # Start date, task ID, or 'after taskX[, taskY]'
+      attribute :duration, Types::Strict::String.constrained(min_size: 1) # Duration string (e.g., '7d', '2w')
 
       # Returns a hash representation suitable for serialization.
       #
-      # @return [Hash{Symbol => String}]
+      # @return [Hash{Symbol => String | Symbol | nil}]
+      def to_h
+        hash = {
+          id: id,
+          label: label,
+          start: start,
+          duration: duration
+        }
+        hash[:status] = status if status # Include status only if set
+        hash
+      end
     end
   end
 end

data/lib/diagrams/elements/timeline_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a single event description within a timeline period.
+    class TimelineEvent < Dry::Struct
+      include Elements::Types
+
+      attribute :description, Types::Strict::String.constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+      def to_h
+        {
+          description:
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/timeline_period.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a specific time period on the timeline, containing one or more events.
+    class TimelinePeriod < Dry::Struct
+      include Elements::Types
+
+      attribute :label, Types::Strict::String.constrained(min_size: 1)
+      attribute :events, Types::Strict::Array.of(TimelineEvent).constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          label:,
+          events: events.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/timeline_section.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a section or age within the timeline, grouping multiple time periods.
+    class TimelineSection < Dry::Struct
+      include Elements::Types
+
+      attribute :title, Types::Strict::String.constrained(min_size: 1)
+      attribute :periods, Types::Strict::Array.of(TimelinePeriod).default([].freeze)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          title:,
+          periods: periods.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/transition.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry-struct'
-require_relative 'node' # Load Types module defined in node.rb
-
 module Diagrams
-
   module Elements
     # Represents a transition between two states in a State Diagram.
     class Transition < Dry::Struct

data/lib/diagrams/elements.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Diagrams
+  # Namespace for diagram element value objects.
+
+  module Elements
+    # Common Dry::Types definitions for elements.
+    module Types
+      include Dry.Types()
+    end
+  end
+end

data/lib/diagrams/er_diagram.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Diagrams
+  # Represents an Entity Relationship Diagram (ERD).
+  class ERDiagram < Base
+    attr_reader :entities, :relationships
+
+    # Initializes a new ERDiagram.
+    #
+    # @param entities [Array<Element::ERDEntity>] Initial entities (optional).
+    # @param relationships [Array<Element::ERDRelationship>] Initial relationships (optional).
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(entities: [], relationships: [], version: 1)
+      super(version:)
+      @entities = (entities.is_a?(Array) ? entities : []).each_with_object({}) { |e, h| h[e.name] = e }
+      @relationships = relationships.is_a?(Array) ? relationships : []
+      validate_relationships!
+      update_checksum!
+    end
+
+    # Adds an entity to the diagram.
+    #
+    # @param name [String] The unique name of the entity.
+    # @param attributes [Array<Hash>] Array of attribute definitions (hashes like { type:, name:, keys:, comment: }).
+    # @raise [ArgumentError] if an entity with the same name already exists.
+    # @return [Elements::ERDEntity] The added entity.
+    def add_entity(name:, attributes: [])
+      raise ArgumentError, "Entity name '#{name}' cannot be empty" if name.nil? || name.strip.empty?
+      raise ArgumentError, "Entity with name '#{name}' already exists" if @entities.key?(name)
+
+      entity_attributes = attributes.map do |attr_hash|
+        Elements::ERDAttribute.new(attr_hash.transform_keys(&:to_sym))
+      end
+      new_entity = Elements::ERDEntity.new(name:, entity_attributes: entity_attributes) # Use renamed attribute
+
+      @entities[name] = new_entity
+      update_checksum!
+      new_entity
+    end
+
+    # Adds a relationship between two entities.
+    #
+    # @param entity1 [String] Name of the first entity.
+    # @param entity2 [String] Name of the second entity.
+    # @param cardinality1 [Symbol] Cardinality of entity1 relative to entity2 (e.g., :ONE_ONLY).
+    # @param cardinality2 [Symbol] Cardinality of entity2 relative to entity1 (e.g., :ZERO_OR_MORE).
+    # @param identifying [Boolean] Whether the relationship is identifying (default: false).
+    # @param label [String, nil] Optional label describing the relationship action.
+    # @raise [ArgumentError] if either entity does not exist.
+    # @return [Elements::ERDRelationship] The added relationship.
+    def add_relationship(entity1:, entity2:, cardinality1:, cardinality2:, identifying: false, label: nil)
+      unless @entities.key?(entity1) && @entities.key?(entity2)
+        raise ArgumentError, "One or both entities ('#{entity1}', '#{entity2}') not found for relationship."
+      end
+
+      new_relationship = Elements::ERDRelationship.new(
+        entity1:,
+        entity2:,
+        cardinality1:,
+        cardinality2:,
+        identifying:,
+        label:
+      )
+      @relationships << new_relationship
+      update_checksum!
+      new_relationship
+    end
+
+    # Finds an entity by its name.
+    #
+    # @param entity_name [String] The name of the entity to find.
+    # @return [Elements::ERDEntity, nil] The found entity or nil.
+    def find_entity(entity_name)
+      @entities[entity_name]
+    end
+
+    # --- Base Class Implementation ---
+
+    def to_h_content
+      {
+        entities: @entities.values.map(&:to_h),
+        relationships: @relationships.map(&:to_h)
+      }
+    end
+
+    def identifiable_elements
+      {
+        entities: @entities.values,
+        relationships: @relationships # Relationships don't have a simple unique ID, rely on object equality for diff
+      }
+    end
+
+    def self.from_h(data_hash, version:, checksum:)
+      entities_data = data_hash[:entities] || data_hash['entities'] || []
+      relationships_data = data_hash[:relationships] || data_hash['relationships'] || []
+
+      entities = entities_data.map do |entity_h|
+        entity_data = entity_h.transform_keys(&:to_sym)
+        attributes_data = entity_data[:entity_attributes] || entity_data[:attributes] || [] # Accept both old and new key for now
+        attributes = attributes_data.map do |attr_h|
+          attr_data = attr_h.transform_keys(&:to_sym)
+          # Convert keys back to symbols if they are strings
+          # Convert keys back to symbols
+          attr_data[:keys] = attr_data[:keys].map(&:to_sym) if attr_data[:keys].is_a?(Array)
+          Elements::ERDAttribute.new(attr_data)
+        end
+        # Use the correct attribute name when creating the entity
+        Elements::ERDEntity.new(entity_data.merge(entity_attributes: attributes))
+      end
+
+      relationships = relationships_data.map do |rel_h|
+        rel_data = rel_h.transform_keys(&:to_sym)
+        # Convert cardinalities back to symbols if they are strings
+        rel_data[:cardinality1] = rel_data[:cardinality1].to_sym if rel_data[:cardinality1].is_a?(String)
+        rel_data[:cardinality2] = rel_data[:cardinality2].to_sym if rel_data[:cardinality2].is_a?(String)
+        Elements::ERDRelationship.new(rel_data)
+      end
+
+      diagram = new(entities:, relationships:, version:)
+
+      # Optional: Verify checksum
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded ERDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Validates that all relationships refer to existing entities during initialization.
+    def validate_relationships!
+      @relationships.each do |rel|
+        unless @entities.key?(rel.entity1) && @entities.key?(rel.entity2)
+          raise ArgumentError, "Relationship refers to non-existent entity IDs ('#{rel.entity1}' or '#{rel.entity2}')"
+        end
+      end
+    end
+
+    # Protected method access
+    protected :update_checksum!
+  end
+end

data/lib/diagrams/flowchart_diagram.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/node'
-require_relative 'elements/edge'
-
 module Diagrams
   # Represents a flowchart diagram consisting of nodes and edges connecting them.
   class FlowchartDiagram < Base
@@ -28,7 +24,6 @@ module Diagrams
     # @raise [ArgumentError] if a node with the same ID already exists.
     # @return [Element::Node] The added node.
     def add_node(node)
-
       raise ArgumentError, 'Node must be a Diagrams::Element::Node' unless node.is_a?(Diagrams::Elements::Node)
       raise ArgumentError, "Node with ID '#{node.id}' already exists" if find_node(node.id)
 
@@ -43,7 +38,6 @@ module Diagrams
     # @raise [ArgumentError] if the edge refers to non-existent node IDs.
     # @return [Element::Edge] The added edge.
     def add_edge(edge)
-
       raise ArgumentError, 'Edge must be a Diagrams::Element::Edge' unless edge.is_a?(Diagrams::Elements::Edge)
       unless find_node(edge.source_id) && find_node(edge.target_id)
         raise ArgumentError, "Edge refers to non-existent node IDs ('#{edge.source_id}' or '#{edge.target_id}')"