dbwatcher 1.0.0 → 1.1.0

data/lib/dbwatcher/services/diagram_data/relationship.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "relationship_params"
+
+module Dbwatcher
+  module Services
+    module DiagramData
+      # Standard relationship between entities
+      #
+      # This class provides a standardized representation for all diagram relationships
+      # (edges, connections, associations, foreign keys, etc.) with consistent validation.
+      #
+      # @example
+      #   relationship = Relationship.new(
+      #     source_id: "users",
+      #     target_id: "orders",
+      #     type: "has_many",
+      #     label: "orders",
+      #     cardinality: "one_to_many",
+      #     metadata: { association_type: "has_many" }
+      #   )
+      #   relationship.valid? # => true
+      #   relationship.to_h   # => { source_id: "users", target_id: "orders", ... }
+      class Relationship
+        attr_accessor :source_id, :target_id, :type, :label, :cardinality, :metadata
+
+        # Valid cardinality types
+        VALID_CARDINALITIES = [
+          "one_to_one",
+          "one_to_many",
+          "many_to_one",
+          "many_to_many",
+          nil
+        ].freeze
+
+        # Cardinality mapping for relationship types
+        CARDINALITY_MAPPING = {
+          "has_many" => "one_to_many",
+          "belongs_to" => "many_to_one",
+          "has_one" => "one_to_one",
+          "has_and_belongs_to_many" => "many_to_many"
+        }.freeze
+
+        # ERD cardinality notations
+        ERD_NOTATIONS = {
+          "one_to_many" => "||--o{",
+          "many_to_one" => "}o--||",
+          "one_to_one" => "||--||",
+          "many_to_many" => "}|--|{"
+        }.freeze
+
+        # Default ERD notation
+        DEFAULT_ERD_NOTATION = "||--o{" # Default to one-to-many
+
+        # Initialize relationship
+        #
+        # @param params [RelationshipParams, Hash] relationship parameters
+        # @return [Relationship] new relationship instance
+        def initialize(params)
+          params = RelationshipParams.new(params) if params.is_a?(Hash)
+
+          @source_id = params.source_id.to_s
+          @target_id = params.target_id.to_s
+          @type = params.type.to_s
+          @label = params.label&.to_s
+          @cardinality = params.cardinality&.to_s
+          @metadata = params.metadata.is_a?(Hash) ? params.metadata : {}
+        end
+
+        # Check if relationship is valid
+        #
+        # @return [Boolean] true if relationship has required fields
+        def valid?
+          validation_errors.empty?
+        end
+
+        # Get validation errors
+        #
+        # @return [Array<String>] array of validation error messages
+        def validation_errors
+          errors = []
+          errors << "Source ID cannot be blank" if source_id.nil? || source_id.to_s.strip.empty?
+          errors << "Target ID cannot be blank" if target_id.nil? || target_id.to_s.strip.empty?
+          errors << "Type cannot be blank" if type.nil? || type.to_s.strip.empty?
+
+          # Allow self-referential relationships when explicitly marked as such
+          errors << "Source and target cannot be the same" if !metadata[:self_referential] && (source_id == target_id)
+
+          errors << "Invalid cardinality: #{cardinality}" if cardinality && !VALID_CARDINALITIES.include?(cardinality)
+          errors << "Metadata must be a Hash" unless metadata.is_a?(Hash)
+          errors
+        end
+
+        # Infer cardinality from relationship type if not explicitly set
+        #
+        # @return [String, nil] inferred cardinality or nil if can't be determined
+        def infer_cardinality
+          return cardinality if cardinality
+
+          CARDINALITY_MAPPING[type]
+        end
+
+        # Get cardinality for ERD notation
+        #
+        # @return [String] ERD cardinality notation
+        def erd_cardinality_notation
+          # Default to one-to-many if not recognized
+          ERD_NOTATIONS[infer_cardinality] || DEFAULT_ERD_NOTATION
+        end
+
+        # Serialize relationship to hash
+        #
+        # @return [Hash] serialized relationship data
+        def to_h
+          {
+            source_id: source_id,
+            target_id: target_id,
+            type: type,
+            label: label,
+            cardinality: cardinality,
+            metadata: metadata
+          }
+        end
+
+        # Serialize relationship to JSON
+        #
+        # @return [String] JSON representation
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+
+        # Create relationship from hash
+        #
+        # @param hash [Hash] relationship data
+        # @return [Relationship] new relationship instance
+        def self.from_h(hash)
+          hash = hash.transform_keys(&:to_sym) if hash.keys.first.is_a?(String)
+          new(hash)
+        end
+
+        # Create relationship from JSON
+        #
+        # @param json [String] JSON string
+        # @return [Relationship] new relationship instance
+        def self.from_json(json)
+          from_h(JSON.parse(json))
+        end
+
+        # Check equality with another relationship
+        #
+        # @param other [Relationship] other relationship to compare
+        # @return [Boolean] true if relationships are equal
+        def ==(other)
+          return false unless other.is_a?(Relationship)
+
+          source_id == other.source_id &&
+            target_id == other.target_id &&
+            type == other.type &&
+            label == other.label &&
+            cardinality == other.cardinality &&
+            metadata == other.metadata
+        end
+
+        # Generate hash code for relationship
+        #
+        # @return [Integer] hash code
+        def hash
+          [source_id, target_id, type, label, cardinality, metadata].hash
+        end
+
+        # String representation of relationship
+        #
+        # @return [String] string representation
+        def to_s
+          "#{self.class.name}(source: #{source_id}, target: #{target_id}, type: #{type})"
+        end
+
+        # Detailed string representation
+        #
+        # @return [String] detailed string representation
+        def inspect
+          "#{self.class.name}(source: #{source_id.inspect}, target: #{target_id.inspect}, " \
+            "type: #{type.inspect}, label: #{label.inspect}, cardinality: #{cardinality.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/diagram_data/relationship_params.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module DiagramData
+      # Parameter object for relationship creation
+      #
+      # This class encapsulates parameters used for creating relationships
+      # to avoid long parameter lists.
+      class RelationshipParams
+        attr_accessor :source_id, :target_id, :type, :label, :cardinality, :metadata
+
+        # Initialize relationship parameters
+        #
+        # @param params [Hash] hash containing all parameters
+        # @option params [String] :source_id ID of the source entity
+        # @option params [String] :target_id ID of the target entity
+        # @option params [String] :type relationship type
+        # @option params [String] :label optional display label
+        # @option params [String] :cardinality optional cardinality type
+        # @option params [Hash] :metadata additional information
+        def initialize(params = {})
+          @source_id = params[:source_id]
+          @target_id = params[:target_id]
+          @type = params[:type]
+          @label = params[:label]
+          @cardinality = params[:cardinality]
+          @metadata = params[:metadata] || {}
+        end
+
+        # Create from individual parameters
+        #
+        # @param params [Hash] parameters hash
+        # @return [RelationshipParams] new instance
+        def self.create(params)
+          new(params)
+        end
+
+        # Convert to hash
+        #
+        # @return [Hash] hash representation of parameters
+        def to_h
+          {
+            source_id: source_id,
+            target_id: target_id,
+            type: type,
+            label: label,
+            cardinality: cardinality,
+            metadata: metadata
+          }
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/diagram_data.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "diagram_data/entity"
+require_relative "diagram_data/relationship"
+require_relative "diagram_data/dataset"
+
+module Dbwatcher
+  module Services
+    # DiagramData module provides standardized data models for diagram generation
+    #
+    # This module contains the core data structures used to represent diagram
+    # entities and relationships in a consistent, validated format that can be
+    # consumed by any diagram strategy.
+    #
+    # @example
+    #   # Create entities
+    #   user_entity = Dbwatcher::Services::DiagramData::Entity.new(
+    #     id: "users", name: "User", type: "table"
+    #   )
+    #   order_entity = Dbwatcher::Services::DiagramData::Entity.new(
+    #     id: "orders", name: "Order", type: "table"
+    #   )
+    #
+    #   # Create relationship
+    #   relationship = Dbwatcher::Services::DiagramData::Relationship.new(
+    #     source_id: "users", target_id: "orders", type: "has_many"
+    #   )
+    #
+    #   # Create dataset
+    #   dataset = Dbwatcher::Services::DiagramData::Dataset.new
+    #   dataset.add_entity(user_entity)
+    #   dataset.add_entity(order_entity)
+    #   dataset.add_relationship(relationship)
+    #
+    #   # Validate and use
+    #   if dataset.valid?
+    #     puts dataset.stats
+    #   end
+    module DiagramData
+      # Convenience method to create a new Entity
+      #
+      # @param args [Hash] entity arguments
+      # @return [Entity] new entity instance
+      def self.entity(**args)
+        Entity.new(**args)
+      end
+
+      # Convenience method to create a new Relationship
+      #
+      # @param args [Hash] relationship arguments
+      # @return [Relationship] new relationship instance
+      def self.relationship(**args)
+        Relationship.new(**args)
+      end
+
+      # Convenience method to create a new Dataset
+      #
+      # @param args [Hash] dataset arguments
+      # @return [Dataset] new dataset instance
+      def self.dataset(**args)
+        Dataset.new(**args)
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/diagram_error_handler.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    # Centralized error handling for diagram generation
+    #
+    # Provides consistent error categorization, logging, and response formatting
+    # for all diagram generation failures with recovery strategies.
+    #
+    # @example
+    #   handler = DiagramErrorHandler.new
+    #   response = handler.handle_generation_error(error, context)
+    #   # => { success: false, error_code: 'DIAGRAM_001', message: '...', recoverable: false }
+    class DiagramErrorHandler
+      # Custom error class for diagram generation failures
+      class DiagramGenerationError < StandardError
+        attr_reader :error_code, :context, :original_error
+
+        def initialize(message, error_code: nil, context: {}, original_error: nil)
+          super(message)
+          @error_code = error_code
+          @context = context
+          @original_error = original_error
+        end
+      end
+
+      # Error code mapping for consistent error identification
+      ERROR_CODES = {
+        session_not_found: "DIAGRAM_001",
+        invalid_diagram_type: "DIAGRAM_002",
+        syntax_validation_failed: "DIAGRAM_003",
+        generation_timeout: "DIAGRAM_004",
+        insufficient_data: "DIAGRAM_005",
+        analyzer_error: "DIAGRAM_006",
+        cache_error: "DIAGRAM_007",
+        system_error: "DIAGRAM_099"
+      }.freeze
+
+      # Initialize error handler with configuration
+      #
+      # @param config [Hash] error handler configuration
+      # @option config [Logger] :logger logger instance
+      # @option config [Boolean] :include_backtrace include backtrace in logs
+      # @option config [Integer] :backtrace_lines number of backtrace lines to log
+      def initialize(config = {})
+        @config = default_config.merge(config)
+        @logger = @config[:logger] || default_logger
+      end
+
+      # Handle diagram generation error with categorization and logging
+      #
+      # @param error [Exception] the original error
+      # @param context [Hash] additional context information
+      # @return [Hash] formatted error response
+      def handle_generation_error(error, context = {})
+        error_info = categorize_error(error, context)
+        log_error(error_info)
+
+        # Return user-friendly error response
+        create_error_response(error_info)
+      end
+
+      # Check if an error type is recoverable
+      #
+      # @param error_code [String] error code
+      # @return [Boolean] true if error is recoverable
+      def recoverable_error?(error_code)
+        recoverable_codes = [
+          ERROR_CODES[:syntax_validation_failed],
+          ERROR_CODES[:generation_timeout],
+          ERROR_CODES[:insufficient_data],
+          ERROR_CODES[:cache_error]
+        ]
+        recoverable_codes.include?(error_code)
+      end
+
+      private
+
+      # Default configuration
+      #
+      # @return [Hash] default configuration
+      def default_config
+        {
+          include_backtrace: true,
+          backtrace_lines: 5
+        }
+      end
+
+      # Default logger when no logger is provided
+      #
+      # @return [Logger] default logger instance
+      def default_logger
+        # Use Rails logger if available, otherwise create a simple logger
+        if defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger
+        else
+          require "logger"
+          Logger.new($stdout)
+        end
+      end
+
+      # Categorize error based on type and context
+      #
+      # @param error [Exception] the original error
+      # @param context [Hash] error context
+      # @return [Hash] categorized error information
+      def categorize_error(error, context)
+        # Check for session not found errors first
+        if error.message.include?("Session") && error.message.include?("not found")
+          return {
+            type: :session_not_found,
+            code: ERROR_CODES[:session_not_found],
+            message: "Session not found: #{context[:session_id]}",
+            recoverable: false,
+            original_error: error,
+            user_message: "The requested session could not be found. Please verify the session ID."
+          }
+        end
+
+        case error
+        when ArgumentError
+          if error.message.include?("Unknown diagram type") || error.message.include?("Invalid diagram type")
+            {
+              type: :invalid_diagram_type,
+              code: ERROR_CODES[:invalid_diagram_type],
+              message: "Invalid diagram type: #{context[:diagram_type]}",
+              recoverable: false,
+              original_error: error,
+              user_message: "The requested diagram type is not supported."
+            }
+          else
+            categorize_generic_error(error, context)
+          end
+        when StandardError
+          if error.message.include?("syntax") || error.message.include?("Mermaid")
+            {
+              type: :syntax_validation_failed,
+              code: ERROR_CODES[:syntax_validation_failed],
+              message: "Diagram syntax validation failed: #{error.message}",
+              recoverable: true,
+              original_error: error,
+              user_message: "There was an issue generating the diagram syntax. Please try again."
+            }
+          elsif error.message.include?("timeout") || error.is_a?(Timeout::Error)
+            {
+              type: :generation_timeout,
+              code: ERROR_CODES[:generation_timeout],
+              message: "Diagram generation timed out",
+              recoverable: true,
+              original_error: error,
+              user_message: "Diagram generation took too long. Please try again with a smaller dataset."
+            }
+          elsif error.message.include?("No") && error.message.include?("found")
+            {
+              type: :insufficient_data,
+              code: ERROR_CODES[:insufficient_data],
+              message: "Insufficient data for diagram generation: #{error.message}",
+              recoverable: true,
+              original_error: error,
+              user_message: "Not enough data available to generate the diagram."
+            }
+          elsif error.message.include?("cache") || error.message.include?("Cache")
+            {
+              type: :cache_error,
+              code: ERROR_CODES[:cache_error],
+              message: "Cache operation failed: #{error.message}",
+              recoverable: true,
+              original_error: error,
+              user_message: "A temporary caching issue occurred. The diagram was still generated."
+            }
+          else
+            categorize_generic_error(error, context)
+          end
+        else
+          categorize_generic_error(error, context)
+        end
+      end
+
+      # Categorize generic/unknown errors
+      #
+      # @param error [Exception] the original error
+      # @param context [Hash] error context
+      # @return [Hash] categorized error information
+      def categorize_generic_error(error, _context)
+        {
+          type: :system_error,
+          code: ERROR_CODES[:system_error],
+          message: "Unexpected error during diagram generation: #{error.class.name}",
+          recoverable: false,
+          original_error: error,
+          user_message: "An unexpected error occurred. Please try again or contact support."
+        }
+      end
+
+      # Log error with appropriate level and detail
+      #
+      # @param error_info [Hash] categorized error information
+      def log_error(error_info)
+        log_data = {
+          error_code: error_info[:code],
+          error_type: error_info[:type],
+          message: error_info[:message],
+          recoverable: error_info[:recoverable],
+          original_error_class: error_info[:original_error]&.class&.name
+        }
+
+        # Add backtrace if configured and available
+        if @config[:include_backtrace] && error_info[:original_error]&.backtrace
+          log_data[:backtrace] = error_info[:original_error].backtrace.first(@config[:backtrace_lines])
+        end
+
+        # Log at appropriate level based on recoverability
+        if error_info[:recoverable]
+          @logger.warn "Recoverable diagram generation error: #{error_info[:message]} (#{error_info[:code]})"
+        else
+          @logger.error "Non-recoverable diagram generation error: #{error_info[:message]} (#{error_info[:code]})"
+        end
+      end
+
+      # Create formatted error response
+      #
+      # @param error_info [Hash] categorized error information
+      # @return [Hash] formatted error response
+      def create_error_response(error_info)
+        {
+          success: false,
+          error: error_info[:user_message] || error_info[:message],
+          error_code: error_info[:code],
+          error_type: error_info[:type],
+          message: error_info[:user_message] || error_info[:message],
+          recoverable: error_info[:recoverable],
+          timestamp: Time.now.iso8601,
+          content: nil,
+          type: nil
+        }
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/diagram_generator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "diagram_error_handler"
+require_relative "diagram_type_registry"
+
+module Dbwatcher
+  module Services
+    # Orchestrator for diagram generation using strategy pattern
+    #
+    # This service coordinates diagram generation by delegating to appropriate
+    # analyzer and strategy classes with clean error handling.
+    #
+    # @example
+    #   generator = DiagramGenerator.new(session_id, 'database_tables')
+    #   result = generator.call
+    #   # => { content: "erDiagram\n    USERS ||--o{ ORDERS : user_id", type: 'erDiagram' }
+    class DiagramGenerator < BaseService
+      attr_reader :session_id, :diagram_type, :registry, :error_handler, :logger
+
+      # Initialize with session id and diagram type
+      #
+      # @param session_id [String] session identifier
+      # @param diagram_type [String] type of diagram to generate
+      # @param dependencies [Hash] optional dependency injection
+      # @option dependencies [DiagramTypeRegistry] :registry type registry
+      # @option dependencies [DiagramErrorHandler] :error_handler error handler
+      # @option dependencies [Logger] :logger logger instance
+      def initialize(session_id, diagram_type = "database_tables", dependencies = {})
+        @session_id = session_id
+        @diagram_type = diagram_type
+        @registry = dependencies[:registry] || DiagramTypeRegistry.new
+        @error_handler = dependencies[:error_handler] || DiagramErrorHandler.new
+        @logger = dependencies[:logger] || default_logger
+        super()
+      end
+
+      # Generate diagram for session
+      #
+      # @return [Hash] diagram data with content and type
+      def call
+        @logger.info("Generating diagram for session #{@session_id} with type #{@diagram_type}")
+        start_time = Time.now
+
+        begin
+          result = generate_diagram
+          log_completion(start_time, result)
+          result
+        rescue StandardError => e
+          @error_handler.handle_generation_error(e, error_context)
+        end
+      end
+
+      # Get available diagram types with metadata
+      #
+      # @return [Hash] diagram types with metadata
+      def available_types
+        @registry.available_types_with_metadata
+      end
+
+      # Get available diagram types (class method for backward compatibility)
+      #
+      # @return [Hash] diagram types with metadata
+      def self.available_types
+        DiagramTypeRegistry.new.available_types_with_metadata
+      end
+
+      private
+
+      # Default logger when no logger is provided
+      #
+      # @return [Logger] default logger instance
+      def default_logger
+        # Use Rails logger if available, otherwise create a simple logger
+        if defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger
+        else
+          require "logger"
+          Logger.new($stdout)
+        end
+      end
+
+      # Generate diagram using standardized analyzer-to-strategy flow
+      #
+      # @return [Hash] diagram generation result
+      def generate_diagram
+        # Validate diagram type
+        unless @registry.type_exists?(@diagram_type)
+          raise DiagramTypeRegistry::UnknownTypeError, "Invalid diagram type: #{@diagram_type}"
+        end
+
+        # Load session
+        session = load_session
+        return error_result("Session not found") unless session
+
+        # Create analyzer and generate dataset
+        analyzer = @registry.create_analyzer(@diagram_type, session)
+        dataset = analyzer.call
+
+        @logger.debug("Generated dataset with #{dataset.entities.size} entities and " \
+                      "#{dataset.relationships.size} relationships")
+
+        # Create strategy and generate diagram from dataset
+        strategy = @registry.create_strategy(@diagram_type)
+        strategy.generate_from_dataset(dataset)
+      end
+
+      # Load session for analysis
+      #
+      # @return [Object] session object
+      def load_session
+        Dbwatcher::Storage.sessions.find(@session_id)
+      rescue StandardError => e
+        @logger.warn("Could not load session #{@session_id}: #{e.message}")
+        nil
+      end
+
+      # Build error context for error handler
+      #
+      # @return [Hash] error context
+      def error_context
+        {
+          session_id: @session_id,
+          diagram_type: @diagram_type,
+          timestamp: Time.now
+        }
+      end
+
+      # Create error result
+      #
+      # @param message [String] error message
+      # @return [Hash] error result
+      def error_result(message)
+        {
+          success: false,
+          error: message,
+          content: nil,
+          type: nil,
+          generated_at: Time.now.iso8601
+        }
+      end
+
+      # Log generation completion
+      #
+      # @param start_time [Time] operation start time
+      # @param result [Hash] generation result
+      def log_completion(start_time, result)
+        duration = Time.now - start_time
+        success = result[:success] || false
+        @logger.info("Diagram generation completed for session #{@session_id} type #{@diagram_type} " \
+                     "in #{(duration * 1000).round(2)}ms - Success: #{success}")
+      end
+    end
+  end
+end