diagram 0.2.1 → 0.3.0

data/lib/diagrams/flowchart_diagram.rb

@@ -1,9 +1,130 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+require_relative 'elements/node'
+require_relative 'elements/edge'
+
 module Diagrams
-  class FlowchartDiagram < AbstractDiagram
-    attribute :id, Types::String
-    attribute :nodes, Types::Array.of(Node)
-    attribute :links, Types::Array.of(Link)
+  # Represents a flowchart diagram consisting of nodes and edges connecting them.
+  class FlowchartDiagram < Base
+    attr_reader :nodes, :edges
+
+    # Initializes a new FlowchartDiagram.
+    #
+    # @param nodes [Array<Element::Node>] An array of node objects.
+    # @param edges [Array<Element::Edge>] An array of edge objects.
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(nodes: [], edges: [], version: 1)
+      super(version:)
+      @nodes = nodes.is_a?(Array) ? nodes : []
+      @edges = edges.is_a?(Array) ? edges : []
+      validate_elements!
+      update_checksum!
+    end
+
+    # Adds a node to the diagram.
+    #
+    # @param node [Element::Node] The node object to add.
+    # @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)
+
+      @nodes << node
+      update_checksum!
+      node
+    end
+
+    # Adds an edge to the diagram.
+    #
+    # @param edge [Element::Edge] The edge object to add.
+    # @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}')"
+      end
+
+      @edges << edge
+      update_checksum!
+      edge
+    end
+
+    # Finds a node by its ID.
+    #
+    # @param node_id [String] The ID of the node to find.
+    # @return [Element::Node, nil] The found node or nil.
+    def find_node(node_id)
+      @nodes.find { |n| n.id == node_id }
+    end
+
+    # Returns the specific content of the flowchart diagram as a hash.
+    # Called by `Diagrams::Base#to_h`.
+    #
+    # @return [Hash{Symbol => Array<Hash>}]
+    def to_h_content
+      {
+        nodes: @nodes.map(&:to_h),
+        edges: @edges.map(&:to_h)
+      }
+    end
+
+    # Returns a hash mapping element types to their collections for diffing.
+    # @see Diagrams::Base#identifiable_elements
+    # @return [Hash{Symbol => Array<Diagrams::Elements::Node | Diagrams::Elements::Edge>}]
+    def identifiable_elements
+      {
+        nodes: @nodes,
+        edges: @edges
+      }
+    end
+
+    # Class method to create a FlowchartDiagram from a hash.
+    # Used by the deserialization factory in `Diagrams::Base`.
+    #
+    # @param data_hash [Hash] Hash containing `:nodes` and `:edges` arrays.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional, for verification).
+    # @return [FlowchartDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      nodes_data = data_hash[:nodes] || data_hash['nodes'] || []
+      edges_data = data_hash[:edges] || data_hash['edges'] || []
+
+      nodes =
+        nodes_data.map do |node_h|
+          Diagrams::Elements::Node.new(node_h.transform_keys(&:to_sym))
+        end
+      edges =
+        edges_data.map do |edge_h|
+          Diagrams::Elements::Edge.new(edge_h.transform_keys(&:to_sym))
+        end
+      diagram = new(nodes:, edges:, version:)
+
+      # Optional: Verify checksum if provided
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded FlowchartDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+        # Or raise an error: raise "Checksum mismatch..."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Validates the consistency of nodes and edges during initialization.
+    def validate_elements!
+      node_ids = @nodes.map(&:id)
+      raise ArgumentError, 'Duplicate node IDs found' unless node_ids.uniq.size == @nodes.size
+
+      @edges.each do |edge|
+        unless node_ids.include?(edge.source_id) && node_ids.include?(edge.target_id)
+          raise ArgumentError, "Edge refers to non-existent node IDs ('#{edge.source_id}' or '#{edge.target_id}')"
+        end
+      end
+    end
   end
 end

data/lib/diagrams/gantt_diagram.rb

@@ -1,8 +1,102 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+require_relative 'elements/task'
+
 module Diagrams
-  class GanttDiagram < AbstractDiagram
-    attribute :title, GanttDiagram::Types::String
-    attribute :sections, GanttDiagram::Types::Array.of(Section)
+  # Represents a Gantt Chart diagram consisting of tasks over time.
+  class GanttDiagram < Base
+    attr_reader :title, :tasks
+
+    # Initializes a new GanttDiagram.
+    #
+    # @param title [String] The title of the Gantt chart.
+    # @param tasks [Array<Element::Task>] An array of task objects.
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(title: '', tasks: [], version: 1)
+      super(version:)
+      @title = title.is_a?(String) ? title : ''
+      @tasks = tasks.is_a?(Array) ? tasks : []
+      validate_elements!
+      update_checksum!
+    end
+
+    # Adds a task to the diagram.
+    #
+    # @param task [Element::Task] The task object to add.
+    # @raise [ArgumentError] if a task with the same ID already exists.
+    # @return [Element::Task] The added task.
+    def add_task(task)
+      raise ArgumentError, 'Task must be a Diagrams::Elements::Task' unless task.is_a?(Diagrams::Elements::Task)
+      raise ArgumentError, "Task with ID '#{task.id}' already exists" if find_task(task.id)
+
+      @tasks << task
+      update_checksum!
+      task
+    end
+
+    # Finds a task by its ID.
+    #
+    # @param task_id [String] The ID of the task to find.
+    # @return [Element::Task, nil] The found task or nil.
+    def find_task(task_id)
+      @tasks.find { |t| t.id == task_id }
+    end
+
+    # Returns the specific content of the Gantt diagram as a hash.
+    # Called by `Diagrams::Base#to_h`.
+    #
+    # @return [Hash{Symbol => String | Array<Hash>}]
+    def to_h_content
+      {
+        title: @title,
+        tasks: @tasks.map(&:to_h)
+      }
+    end
+
+    # Returns a hash mapping element types to their collections for diffing.
+    # @see Diagrams::Base#identifiable_elements
+    # @return [Hash{Symbol => Array<Diagrams::Elements::Task>}]
+    def identifiable_elements
+      {
+        tasks: @tasks
+      }
+    end
+
+    # Class method to create a GanttDiagram from a hash.
+    # Used by the deserialization factory in `Diagrams::Base`.
+    #
+    # @param data_hash [Hash] Hash containing `:title` and `:tasks` array.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional, for verification).
+    # @return [GanttDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      title = data_hash[:title] || data_hash['title'] || ''
+      tasks_data = data_hash[:tasks] || data_hash['tasks'] || []
+
+      tasks = tasks_data.map { |task_h| Diagrams::Elements::Task.new(task_h.transform_keys(&:to_sym)) }
+
+      diagram = new(title:, tasks:, version:)
+
+      # Optional: Verify checksum if provided
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded GanttDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+        # Or raise an error: raise "Checksum mismatch..."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Validates the consistency of tasks during initialization.
+    def validate_elements!
+      task_ids = @tasks.map(&:id)
+      return if task_ids.uniq.size == @tasks.size
+
+      raise ArgumentError, 'Duplicate task IDs found'
+
+      # Add more validation if needed (e.g., date formats, dependencies)
+    end
   end
 end

data/lib/diagrams/pie_diagram.rb

@@ -1,48 +1,130 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+require_relative 'elements/slice'
+
 module Diagrams
-  class PieDiagram < AbstractDiagram
-    attribute :id, Types::String.optional.default(nil)
-    attribute :title, Types::String.optional.default('')
-    attribute :sections, Types::Array.of(Section).optional.default([].freeze)
+  # Represents a Pie Chart diagram consisting of slices.
+  class PieDiagram < Base
+    attr_reader :title, :slices
+
+    # Initializes a new PieDiagram.
+    #
+    # @param title [String] The title of the pie chart.
+    # @param slices [Array<Element::Slice>] An array of slice objects.
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(title: '', slices: [], version: 1)
+      super(version: version) # Corrected super call
+      @title = title.is_a?(String) ? title : ''
+      @slices = [] # Initialize empty
+      # Add initial slices using the corrected add_slice method
+      (slices.is_a?(Array) ? slices : []).each { |s| add_slice(s, update_checksum: false, initial_load: true) }
+      recalculate_percentages! # Calculate initial percentages
+      update_checksum! # Calculate final checksum after initial load
+    end
+
+    # Adds a slice to the diagram.
+    #
+    # @param slice [Element::Slice] The slice object to add.
+    # @raise [ArgumentError] if a slice with the same label already exists.
+    # @return [Element::Slice] The added slice.
+    # Added initial_load flag to skip checksum update during initialize loop
+    def add_slice(slice, update_checksum: true, initial_load: false)
+      raise ArgumentError, 'Slice must be a Diagrams::Elements::Slice' unless slice.is_a?(Diagrams::Elements::Slice)
+      raise ArgumentError, "Slice with label '#{slice.label}' already exists" if find_slice(slice.label)
 
-    def type
-      :pie
+      # Store a new instance to hold the calculated percentage later
+      # Ensure percentage is nil initially
+      new_slice_instance = slice.class.new(slice.attributes.except(:percentage))
+      @slices << new_slice_instance
+      recalculate_percentages! # Update percentages for all slices
+      update_checksum! if update_checksum && !initial_load # Avoid multiple checksums during init
+      new_slice_instance # Return the instance added to the array
     end
 
-    def validate!
-      raise EmptyDiagramError, 'Pie diagram must have at least one section' if sections.empty?
+    # Finds a slice by its label.
+    #
+    # @param label [String] The label of the slice to find.
+    # @return [Element::Slice, nil] The found slice or nil.
+    def find_slice(label)
+      @slices.find { |s| s.label == label }
+    end
+
+    # Calculates the total raw value of all slices.
+    # @return [Float]
+    def total_value
+      @slices.sum(&:value)
+    end
 
-      return true if sections.map(&:label).uniq.size == sections.size
+    # Returns the specific content of the pie diagram as a hash.
+    # Called by `Diagrams::Base#to_h`.
+    #
+    # @return [Hash{Symbol => String | Array<Hash>}]
+    def to_h_content
+      {
+        title: @title,
+        # Ensure slices include calculated percentage in their hash
+        slices: @slices.map(&:to_h)
+      }
+    end
 
-      raise DuplicateLabelError,
-            'Pie diagram sections must have unique labels'
+    # Returns a hash mapping element types to their collections for diffing.
+    # @see Diagrams::Base#identifiable_elements
+    # @return [Hash{Symbol => Array<Diagrams::Elements::Slice>}]
+    def identifiable_elements
+      {
+        slices: @slices
+      }
     end
 
-    def plot
-      circle_char = '*'
-      pie_diameter = 10
-      pie_radius = pie_diameter / 2.0
+    # Class method to create a PieDiagram from a hash.
+    # Used by the deserialization factory in `Diagrams::Base`.
+    #
+    # @param data_hash [Hash] Hash containing `:title` and `:slices` array.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional, for verification).
+    # @return [PieDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      title = data_hash[:title] || data_hash['title'] || ''
+      slices_data = data_hash[:slices] || data_hash['slices'] || []
 
-      (-pie_radius.to_i..pie_radius.to_i).each do |i|
-        (-pie_radius.to_i..pie_radius.to_i).each do |j|
-          distance_to_center = Math.sqrt((i**2) + (j**2))
-          if distance_to_center > pie_radius - 0.5 && distance_to_center < pie_radius + 0.5
-            print circle_char
-          else
-            print ' '
-          end
-        end
-        print "\n"
+      # Initialize with raw values, percentage will be recalculated by `new` -> `add_slice` -> `recalculate_percentages!`
+      slices = slices_data.map do |slice_h|
+        Diagrams::Elements::Slice.new(slice_h.transform_keys(&:to_sym).except(:percentage))
       end
 
-      sections.each do |section|
-        puts "#{section.label}: #{section.value}%"
+      diagram = new(title: title, slices: slices, version: version)
+
+      # Optional: Verify checksum if provided AFTER initialization is complete
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded PieDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+        # Or raise an error: raise "Checksum mismatch..."
       end
+
+      diagram
     end
 
-    def valid?
-      validate!
+    private
+
+    # Recalculates the percentage for each slice based on the total value.
+    # This method modifies the @slices array in place by replacing Slice instances.
+    def recalculate_percentages!
+      total = total_value
+      new_slices = @slices.map do |slice|
+        percentage = total.zero? ? 0.0 : (slice.value / total * 100.0).round(2)
+        # Create a new instance with the calculated percentage
+        slice.class.new(slice.attributes.merge(percentage: percentage))
+      end
+      # Replace the entire array to ensure changes are reflected
+      @slices = new_slices
+    end
+
+    # Validates the consistency of slices during initialization.
+    def validate_elements!
+      labels = @slices.map(&:label)
+      return if labels.uniq.size == @slices.size
+
+      raise ArgumentError, 'Duplicate slice labels found'
     end
   end
 end

data/lib/diagrams/state_diagram.rb

@@ -1,9 +1,167 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+require_relative 'elements/state'
+require_relative 'elements/transition'
+require_relative 'elements/event' # Assuming events are still desired
+
 module Diagrams
-  class StateDiagram < AbstractDiagram
-    attribute :id, Types::String
-    attribute :states, Types::Array.of(State)
-    attribute :transitions, Types::Array.of(Transition)
+  # Represents a State Diagram consisting of states and transitions between them.
+  class StateDiagram < Base
+    attr_reader :title, :states, :transitions, :events
+
+    # Initializes a new StateDiagram.
+    #
+    # @param title [String] Optional title for the diagram.
+    # @param states [Array<Element::State>] An array of state objects.
+    # @param transitions [Array<Element::Transition>] An array of transition objects.
+    # @param events [Array<Element::Event>] An array of event objects (optional).
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(title: '', states: [], transitions: [], events: [], version: 1)
+      super(version:)
+      @title = title.is_a?(String) ? title : ''
+      @states = states.is_a?(Array) ? states : []
+      @transitions = transitions.is_a?(Array) ? transitions : []
+      @events = events.is_a?(Array) ? events : [] # Keep events for now
+      validate_elements!
+      update_checksum!
+    end
+
+    # Adds a state to the diagram.
+    #
+    # @param state [Element::State] The state object to add.
+    # @raise [ArgumentError] if a state with the same ID already exists.
+    # @return [Element::State] The added state.
+    def add_state(state)
+      raise ArgumentError, 'State must be a Diagrams::Elements::State' unless state.is_a?(Diagrams::Elements::State)
+      raise ArgumentError, "State with ID '#{state.id}' already exists" if find_state(state.id)
+
+      @states << state
+      update_checksum!
+      state
+    end
+
+    # Adds a transition to the diagram.
+    #
+    # @param transition [Element::Transition] The transition object to add.
+    # @raise [ArgumentError] if the transition refers to non-existent state IDs.
+    # @return [Element::Transition] The added transition.
+    def add_transition(transition)
+      unless transition.is_a?(Diagrams::Elements::Transition)
+        raise ArgumentError,
+              'Transition must be a Diagrams::Elements::Transition'
+      end
+      unless find_state(transition.source_state_id) && find_state(transition.target_state_id)
+        raise ArgumentError,
+              "Transition refers to non-existent state IDs ('#{transition.source_state_id}' or '#{transition.target_state_id}')"
+      end
+
+      @transitions << transition
+      update_checksum!
+      transition
+    end
+
+    # Adds an event to the diagram.
+    #
+    # @param event [Element::Event] The event object to add.
+    # @raise [ArgumentError] if an event with the same ID already exists.
+    # @return [Element::Event] The added event.
+    def add_event(event)
+      raise ArgumentError, 'Event must be a Diagrams::Elements::Event' unless event.is_a?(Diagrams::Elements::Event)
+      raise ArgumentError, "Event with ID '#{event.id}' already exists" if find_event(event.id)
+
+      @events << event
+      update_checksum!
+      event
+    end
+
+    # Finds a state by its ID.
+    #
+    # @param state_id [String] The ID of the state to find.
+    # @return [Element::State, nil] The found state or nil.
+    def find_state(state_id)
+      @states.find { |s| s.id == state_id }
+    end
+
+    # Finds an event by its ID.
+    #
+    # @param event_id [String] The ID of the event to find.
+    # @return [Element::Event, nil] The found event or nil.
+    def find_event(event_id)
+      @events.find { |e| e.id == event_id }
+    end
+
+    # Returns the specific content of the state diagram as a hash.
+    # Called by `Diagrams::Base#to_h`.
+    #
+    # @return [Hash{Symbol => String | Array<Hash>}]
+    def to_h_content
+      {
+        title: @title,
+        states: @states.map(&:to_h),
+        transitions: @transitions.map(&:to_h),
+        events: @events.map(&:to_h)
+      }
+    end
+
+    # Returns a hash mapping element types to their collections for diffing.
+    # @see Diagrams::Base#identifiable_elements
+    # @return [Hash{Symbol => Array<Diagrams::Elements::State | Diagrams::Elements::Transition | Diagrams::Elements::Event>}]
+    def identifiable_elements
+      {
+        states: @states,
+        transitions: @transitions,
+        events: @events
+      }
+    end
+
+    # Class method to create a StateDiagram from a hash.
+    # Used by the deserialization factory in `Diagrams::Base`.
+    #
+    # @param data_hash [Hash] Hash containing `:title`, `:states`, `:transitions`, `:events`.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional, for verification).
+    # @return [StateDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      title = data_hash[:title] || data_hash['title'] || ''
+      states_data = data_hash[:states] || data_hash['states'] || []
+      transitions_data = data_hash[:transitions] || data_hash['transitions'] || []
+      events_data = data_hash[:events] || data_hash['events'] || []
+
+      states = states_data.map { |state_h| Diagrams::Elements::State.new(state_h.transform_keys(&:to_sym)) }
+      transitions = transitions_data.map do |trans_h|
+        Diagrams::Elements::Transition.new(trans_h.transform_keys(&:to_sym))
+      end
+      events = events_data.map { |event_h| Diagrams::Elements::Event.new(event_h.transform_keys(&:to_sym)) }
+
+      diagram = new(title:, states:, transitions:, events:, version:)
+
+      # Optional: Verify checksum if provided
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded StateDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+        # Or raise an error: raise "Checksum mismatch..."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Validates the consistency of elements during initialization.
+    def validate_elements!
+      state_ids = @states.map(&:id)
+      raise ArgumentError, 'Duplicate state IDs found' unless state_ids.uniq.size == @states.size
+
+      event_ids = @events.map(&:id)
+      raise ArgumentError, 'Duplicate event IDs found' unless event_ids.uniq.size == @events.size
+
+      @transitions.each do |t|
+        unless state_ids.include?(t.source_state_id) && state_ids.include?(t.target_state_id)
+          raise ArgumentError,
+                "Transition refers to non-existent state IDs ('#{t.source_state_id}' or '#{t.target_state_id}')"
+        end
+      end
+      # Add more validation if needed (e.g., transition labels match event IDs?)
+    end
   end
 end

data/lib/diagrams/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Diagrams
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/diagrams.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'diagrams/version'
-require 'dry-struct'
+require 'zeitwerk'
+require_relative 'diagrams/version' # Keep this for gemspec access before setup
 
 loader = Zeitwerk::Loader.for_gem
 loader.setup

data/sig/diagrams/base.rbs

@@ -0,0 +1,86 @@
+module Diagrams
+  # Abstract base class for all diagram types.
+  # Provides common functionality like versioning, checksum calculation,
+  # serialization, and equality comparison.
+  class Base
+    # Provides `==`, `eql?`, and `hash` methods based on specified attributes.
+    include Dry::Equalizer
+
+    # User-defined version identifier (e.g., Integer or String).
+    attr_reader version: Integer | String
+
+    # SHA256 checksum of the diagram's content (hex string). Nil until calculated.
+    attr_reader checksum: String?
+
+    # Initializes the base diagram attributes.
+    # Subclasses should call super.
+    # Cannot be called directly on Diagrams::Base.
+    def initialize: (?version: Integer | String?) -> void
+
+    # Abstract method: Subclasses must implement this to return a hash
+    # representing their specific content, suitable for serialization.
+    # @return [Hash[Symbol, untyped]]
+    def to_h_content: () -> Hash[Symbol, untyped]
+
+    # Abstract method: Subclasses must implement this to return a hash
+    # mapping element type symbols (e.g., :nodes, :edges) to arrays
+    # of the corresponding element objects within the diagram.
+    # Used for comparison and diffing.
+    # @return [Hash[Symbol, Array[untyped]]] # More specific types in subclasses
+    def identifiable_elements: () -> Hash[Symbol, Array[untyped]]
+
+    # Returns a hash representation of the diagram, suitable for serialization.
+    # Includes common metadata and calls `#to_h_content` for specific data.
+    # @return [Hash[Symbol, untyped]]
+    def to_h: () -> Hash[Symbol, untyped]
+
+    # Returns a JSON string representation of the diagram.
+    # Delegates to `#to_h` and uses `JSON.generate`.
+    # @param args Any arguments accepted by `JSON.generate`.
+    # @return [String]
+    def to_json: (*untyped args) -> String
+
+    # --- Class methods for Deserialization ---
+
+    # Deserializes a diagram from a hash representation.
+    # Acts as a factory, dispatching to the appropriate subclass based on the 'type' field.
+    # @param hash [Hash[Symbol | String, untyped]] The hash representation.
+    # @return [Diagrams::Base] An instance of the specific diagram subclass.
+    def self.from_hash: (Hash[Symbol | String, untyped] hash) -> Diagrams::Base
+
+    # Deserializes a diagram from a JSON string.
+    # Parses the JSON and delegates to `.from_hash`.
+    # @param json_string [String] The JSON representation of the diagram.
+    # @return [Diagrams::Base] An instance of the specific diagram subclass.
+    def self.from_json: (String json_string) -> Diagrams::Base
+
+    # Performs a basic diff against another diagram object.
+    # @param other [Diagrams::Base] The diagram to compare against.
+    # @return [Hash[Symbol, Hash[Symbol, Array[untyped]]]] A hash describing differences.
+    def diff: (Diagrams::Base other) -> Hash[Symbol, Hash[Symbol, Array[untyped]]]
+
+    # --- End Deserialization Methods ---
+
+    # Recalculates the diagram's checksum based on its current content
+    # and updates the @checksum instance variable.
+    # Subclasses should call this after initialization and any mutation.
+    # @return [String?] The new checksum value.
+    def update_checksum!: () -> String?
+
+    private
+
+    # Computes the SHA256 checksum of the diagram's content.
+    # @return [String] The hex digest of the checksum.
+    def compute_checksum: () -> String
+  end
+
+  # --- Errors ---
+  class ValidationError < StandardError
+  end
+
+  class EmptyDiagramError < ValidationError
+  end
+
+  class DuplicateLabelError < ValidationError
+  end
+end