dbwatcher 1.0.0 → 1.1.0

data/lib/dbwatcher/services/mermaid_syntax/cardinality_mapper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Maps relationship cardinality to Mermaid syntax
+      #
+      # Provides mapping from internal cardinality representation to
+      # specific Mermaid diagram syntax for different diagram types.
+      #
+      # @example
+      #   CardinalityMapper.to_erd("one_to_many") # => "||--o{"
+      #   CardinalityMapper.to_class("one_to_many") # => "1..*"
+      #   CardinalityMapper.to_simple("one_to_many") # => "1:N"
+      class CardinalityMapper
+        class << self
+          # Default cardinality notation
+          DEFAULT_ERD = "||--o{" # Default to one-to-many
+          DEFAULT_CLASS = "1..*" # Default to one-to-many
+          DEFAULT_SIMPLE = "1:N" # Default to one-to-many
+
+          # Lookup tables for different cardinality notations
+          ERD_NOTATIONS = {
+            "one_to_many" => "||--o{",
+            "one_to_zero_or_many" => "||--o{",
+            "many_to_one" => "}o--||",
+            "one_to_one" => "||--||",
+            "many_to_many" => "}o--o{",
+            "zero_or_one_to_many" => "|o--o{",
+            "zero_or_one_to_one" => "|o--||",
+            "one_to_zero_or_one" => "||--|o"
+          }.freeze
+
+          CLASS_NOTATIONS = {
+            "one_to_many" => "1..*",
+            "many_to_one" => "*..*",
+            "many_to_many" => "*..*",
+            "one_to_one" => "1..1",
+            "zero_or_one_to_many" => "0..1..*",
+            "one_to_zero_or_many" => "1..0..*",
+            "zero_or_one_to_one" => "0..1..1",
+            "one_to_zero_or_one" => "1..0..1"
+          }.freeze
+
+          SIMPLE_NOTATIONS = {
+            "one_to_many" => "1:N",
+            "many_to_one" => "N:1",
+            "one_to_one" => "1:1",
+            "many_to_many" => "N:N",
+            "zero_or_one_to_many" => "0,1:N",
+            "one_to_zero_or_many" => "1:0,N",
+            "zero_or_one_to_one" => "0,1:1",
+            "one_to_zero_or_one" => "1:0,1"
+          }.freeze
+
+          # Map cardinality to ERD diagram syntax
+          #
+          # @param cardinality [String, Symbol] internal cardinality representation
+          # @param _format [Symbol] cardinality format (not used for ERD)
+          # @return [String] ERD cardinality notation
+          def to_erd(cardinality, _format = :standard)
+            # ERD format doesn't change based on format parameter
+            # It always uses the standard Mermaid ERD notation
+            ERD_NOTATIONS[cardinality.to_s] || DEFAULT_ERD
+          end
+
+          # Map cardinality to class diagram syntax
+          #
+          # @param cardinality [String, Symbol] internal cardinality representation
+          # @param format [Symbol] cardinality format (:standard or :simple)
+          # @return [String] class diagram cardinality notation
+          def to_class(cardinality, format = :standard)
+            return to_simple(cardinality) if format == :simple
+
+            CLASS_NOTATIONS[cardinality.to_s] || DEFAULT_CLASS
+          end
+
+          # Map cardinality to simple text format
+          #
+          # @param cardinality [String, Symbol] internal cardinality representation
+          # @param _format [Symbol] cardinality format (not used for simple format)
+          # @return [String] simple cardinality notation
+          def to_simple(cardinality, _format = :standard)
+            SIMPLE_NOTATIONS[cardinality.to_s] || DEFAULT_SIMPLE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/mermaid_syntax/class_diagram_builder.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "class_diagram_helper"
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Builder for Class Diagrams in Mermaid syntax
+      #
+      # Generates Mermaid class diagram syntax from a standardized dataset with
+      # support for attributes, methods, and relationships with labels.
+      #
+      # @example
+      #   builder = ClassDiagramBuilder.new(show_methods: true)
+      #   content = builder.build_from_dataset(dataset)
+      #   # => "classDiagram
+      #   #     class User {
+      #   #         +string name
+      #   #         +orders()
+      #   #     }
+      #   #     User --> Order : orders"
+      class ClassDiagramBuilder < BaseBuilder
+        include ClassDiagramHelper
+
+        # Build class diagram content from dataset
+        #
+        # @param dataset [DiagramData::Dataset] dataset to render
+        # @return [String] Mermaid class diagram content
+        def build_from_dataset(dataset)
+          lines = ["classDiagram"]
+          lines << "    direction #{diagram_direction}"
+
+          # Add class definitions with attributes and methods
+          dataset.entities.each_value do |entity|
+            lines += build_class_definition(entity)
+          end
+
+          # Add relationships
+          unless dataset.relationships.empty?
+            lines << ""
+            lines << "    %% Relationships"
+            dataset.relationships.each do |relationship|
+              lines << build_class_relationship(relationship, dataset)
+            end
+          end
+
+          lines.join("\n")
+        end
+
+        # Build empty class diagram with message
+        #
+        # @param message [String] message to display
+        # @return [String] Mermaid class diagram content
+        def build_empty(message)
+          sanitized_message = sanitize_text(message)
+          [
+            "classDiagram",
+            "    direction #{diagram_direction}",
+            "    class EmptyState {",
+            "        +string message",
+            "    }",
+            "    note for EmptyState \"#{sanitized_message}\""
+          ].join("\n")
+        end
+
+        private
+
+        # Build attributes section for class definition
+        def build_attributes_section(entity)
+          return [] unless show_attributes? && entity.attributes.any?
+
+          lines = ["        %% Attributes"]
+          entity.attributes.first(max_attributes).each do |attr|
+            lines << format_attribute_line(attr)
+          end
+          add_attributes_overflow_message(lines, entity)
+          add_section_divider(lines, entity)
+          lines
+        end
+
+        # Build methods section for class definition
+        def build_methods_section(entity)
+          return [] unless show_methods? && entity.metadata[:methods]&.any?
+
+          lines = ["        %% Methods"]
+          entity.metadata[:methods].first(max_methods).each do |method|
+            lines << format_method_line(method)
+          end
+          if entity.metadata[:methods].size > max_methods
+            lines << "        %% ... #{entity.metadata[:methods].size - max_methods} more methods"
+          end
+          lines << "        %% ----------------------"
+          lines
+        end
+
+        # Build statistics section for class definition
+        def build_statistics_section(entity)
+          return [] unless entity.attributes.any? || entity.metadata[:methods]&.any?
+
+          lines = ["        %% Statistics"]
+          lines << "        +Stats: #{entity.attributes.size} attributes" if entity.attributes.any?
+          lines << "        +Stats: #{entity.metadata[:methods].size} methods" if entity.metadata[:methods]&.any?
+          lines
+        end
+
+        # Build class definition
+        def build_class_definition(entity)
+          class_name = Sanitizer.class_name(entity.name)
+          lines = ["    class #{class_name} {"]
+          lines += build_attributes_section(entity)
+          lines += build_methods_section(entity)
+          lines += build_statistics_section(entity)
+          lines << "    }"
+          lines << ""
+          lines
+        end
+
+        # Build class relationship
+        def build_class_relationship(relationship, dataset)
+          source = format_class_name(relationship.source_id, dataset)
+          target = format_class_name(relationship.target_id, dataset)
+          label = Sanitizer.label(relationship.label)
+
+          relationship_line = "    #{source}"
+          if show_cardinality? && relationship.cardinality
+            cardinality = CardinalityMapper.to_class(relationship.cardinality, cardinality_format)
+            relationship_line += " \"#{cardinality}\""
+          end
+          relationship_line += " --> #{target}"
+          relationship_line += " : #{label}" if label && !label.empty?
+          relationship_line
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/mermaid_syntax/class_diagram_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Helper module for ClassDiagramBuilder
+      #
+      # Contains formatting methods for class diagram elements
+      module ClassDiagramHelper
+        # Format an attribute for class diagram
+        def format_attribute_line(attr)
+          visibility = attr.metadata[:visibility] || "+"
+          type = attr.type.to_s.empty? ? "any" : attr.type
+          "        #{visibility}#{type} #{attr.name}"
+        end
+
+        # Add overflow message for attributes if needed
+        def add_attributes_overflow_message(lines, entity)
+          return unless entity.attributes.size > max_attributes
+
+          lines << "        %% ... #{entity.attributes.size - max_attributes} more attributes"
+        end
+
+        # Add section divider if methods will follow
+        def add_section_divider(lines, entity)
+          return unless show_methods? && entity.metadata[:methods]&.any?
+
+          lines << "        %% ----------------------"
+        end
+
+        # Format a method for class diagram
+        def format_method_line(method)
+          visibility = method[:visibility] || "+"
+          method_name = Sanitizer.method_name(method[:name])
+          "        #{visibility}#{method_name}"
+        end
+
+        # Format class name for diagram
+        def format_class_name(entity_id, dataset)
+          entity_name = dataset.get_entity(entity_id)&.name || entity_id
+          Sanitizer.class_name(entity_name)
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/mermaid_syntax/erd_builder.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Builder for Entity Relationship Diagrams in Mermaid syntax
+      #
+      # Generates Mermaid ERD syntax from a standardized dataset with
+      # support for attributes and relationships with cardinality.
+      #
+      # @example
+      #   builder = ErdBuilder.new(show_attributes: true)
+      #   content = builder.build_from_dataset(dataset)
+      #   # => "erDiagram\n    USER {\n        int id PK\n    }\n    USER ||--o{ ORDER : \"has_many\""
+      class ErdBuilder < BaseBuilder
+        # Build ERD content from dataset
+        #
+        # @param dataset [DiagramData::Dataset] dataset to render
+        # @return [String] Mermaid ERD content
+        def build_from_dataset(dataset)
+          lines = ["erDiagram"]
+
+          # Add entity definitions with attributes
+          dataset.entities.each_value do |entity|
+            lines += build_erd_entity(entity)
+          end
+
+          # Add relationships
+          unless dataset.relationships.empty?
+            lines << ""
+            dataset.relationships.each do |relationship|
+              lines << build_erd_relationship(relationship, dataset)
+            end
+          end
+
+          lines.join("\n")
+        end
+
+        # Build empty ERD with message
+        #
+        # @param message [String] message to display
+        # @return [String] Mermaid ERD content
+        def build_empty(message)
+          sanitized_message = sanitize_text(message)
+          [
+            "erDiagram",
+            "    EMPTY_STATE {",
+            "        string message \"#{sanitized_message}\"",
+            "    }"
+          ].join("\n")
+        end
+
+        private
+
+        # Format attribute definition for ERD
+        #
+        # @param attr [DiagramData::Attribute] attribute to format
+        # @return [String] formatted attribute line
+        def format_attribute_line(attr)
+          type = attr.type.to_s.empty? ? "any" : attr.type
+          key_suffix = ""
+          key_suffix += " PK" if attr.primary_key?
+          key_suffix += " FK" if attr.foreign_key? && !attr.primary_key?
+
+          "        #{type} #{attr.name}#{key_suffix}"
+        end
+
+        # Build entity definition
+        #
+        # @param entity [DiagramData::Entity] entity to render
+        # @return [Array<String>] entity definition lines
+        def build_erd_entity(entity)
+          table_name = Sanitizer.table_name(entity.name, preserve_table_case?)
+          lines = ["    #{table_name} {"]
+
+          # Add attributes if enabled and available
+          if show_attributes? && entity.attributes.any?
+            entity.attributes.first(max_attributes).each do |attr|
+              lines << format_attribute_line(attr)
+            end
+          end
+
+          lines << "    }"
+          lines << ""
+          lines
+        end
+
+        # Format entity name for ERD
+        #
+        # @param entity_id [String] entity ID
+        # @param dataset [DiagramData::Dataset] dataset for entity lookup
+        # @return [String] formatted entity name
+        def format_entity_name(entity_id, dataset)
+          entity_name = dataset.get_entity(entity_id)&.name || entity_id
+          Sanitizer.table_name(entity_name, preserve_table_case?)
+        end
+
+        # Build relationship definition
+        #
+        # @param relationship [DiagramData::Relationship] relationship to render
+        # @param dataset [DiagramData::Dataset] full dataset for context
+        # @return [String] relationship definition line
+        def build_erd_relationship(relationship, dataset)
+          source = format_entity_name(relationship.source_id, dataset)
+          target = format_entity_name(relationship.target_id, dataset)
+
+          label = Sanitizer.label(relationship.label)
+          cardinality = CardinalityMapper.to_erd(relationship.cardinality, cardinality_format)
+
+          # In Mermaid ERD syntax, relationship labels must be quoted
+          "    #{source} #{cardinality} #{target} : \"#{label}\""
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/mermaid_syntax/flowchart_builder.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Builder for Flowchart Diagrams in Mermaid syntax
+      #
+      # Generates Mermaid flowchart syntax from a standardized dataset with
+      # support for nodes with attributes and edges with labels.
+      #
+      # @example
+      #   builder = FlowchartBuilder.new(show_attributes: true)
+      #   content = builder.build_from_dataset(dataset)
+      #   # => "flowchart LR\n    User[User<br/>name, email]\n    User -->|has_many| Comment"
+      class FlowchartBuilder < BaseBuilder
+        # Build flowchart content from dataset
+        #
+        # @param dataset [DiagramData::Dataset] dataset to render
+        # @return [String] Mermaid flowchart content
+        def build_from_dataset(dataset)
+          lines = ["flowchart #{diagram_direction}"]
+
+          # Add node definitions
+          dataset.entities.each_value do |entity|
+            lines << build_flowchart_node(entity)
+          end
+
+          # Add relationships
+          unless dataset.relationships.empty?
+            lines << ""
+            dataset.relationships.each do |relationship|
+              lines << build_flowchart_relationship(relationship, dataset)
+            end
+          end
+
+          lines.join("\n")
+        end
+
+        # Build empty flowchart with message
+        #
+        # @param message [String] message to display
+        # @return [String] Mermaid flowchart content
+        def build_empty(message)
+          sanitized_message = sanitize_text(message)
+          [
+            "flowchart #{diagram_direction}",
+            "    EmptyState[\"#{sanitized_message}\"]"
+          ].join("\n")
+        end
+
+        private
+
+        # Build flowchart node
+        #
+        # @param entity [DiagramData::Entity] entity to render
+        # @return [String] node definition line
+        def build_flowchart_node(entity)
+          node_id = Sanitizer.node_id(entity.name)
+          node_content = entity.name
+
+          "    #{node_id}[\"#{node_content}\"]"
+        end
+
+        # Format entity name for node ID
+        #
+        # @param entity_id [String] entity ID
+        # @param dataset [DiagramData::Dataset] dataset for entity lookup
+        # @return [String] formatted node ID
+        def format_node_id(entity_id, dataset)
+          entity_name = dataset.get_entity(entity_id)&.name || entity_id
+          Sanitizer.node_id(entity_name)
+        end
+
+        # Format relationship label with optional cardinality
+        #
+        # @param relationship [DiagramData::Relationship] relationship
+        # @return [String] formatted label
+        def format_relationship_label(relationship)
+          label = Sanitizer.label(relationship.label)
+
+          # Add cardinality to label if enabled
+          if show_cardinality? && relationship.cardinality
+            cardinality = CardinalityMapper.to_simple(relationship.cardinality, cardinality_format)
+            label = label.empty? ? cardinality : "#{label} (#{cardinality})"
+          end
+
+          label
+        end
+
+        # Build flowchart relationship
+        #
+        # @param relationship [DiagramData::Relationship] relationship to render
+        # @param dataset [DiagramData::Dataset] full dataset for context
+        # @return [String] relationship definition line
+        def build_flowchart_relationship(relationship, dataset)
+          source = format_node_id(relationship.source_id, dataset)
+          target = format_node_id(relationship.target_id, dataset)
+          label = format_relationship_label(relationship)
+
+          if label && !label.empty?
+            "    #{source} -->|\"#{label}\"| #{target}"
+          else
+            "    #{source} --> #{target}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/services/mermaid_syntax/sanitizer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Services
+    module MermaidSyntax
+      # Utility class for sanitizing names and labels for Mermaid syntax
+      #
+      # Provides methods to sanitize various types of identifiers for use
+      # in Mermaid diagrams, ensuring valid syntax.
+      class Sanitizer
+        class << self
+          # Sanitize class name for Mermaid class diagrams
+          #
+          # @param name [String] raw class name
+          # @return [String] sanitized class name
+          def class_name(name)
+            return "UnknownClass" unless name.is_a?(String) && !name.empty?
+
+            name.to_s.gsub(/[^a-zA-Z0-9_]/, "_").capitalize
+          end
+
+          # Sanitize node name for Mermaid flowcharts
+          #
+          # @param name [String] raw node name
+          # @return [String] sanitized node name
+          def node_name(name)
+            return "unknown_node" unless name.is_a?(String) && !name.empty?
+
+            name.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          end
+
+          # Sanitize node ID for Mermaid flowcharts
+          #
+          # @param name [String] raw node name
+          # @return [String] sanitized node ID
+          def node_id(name)
+            return "unknown_node" unless name.is_a?(String) && !name.empty?
+
+            # Node IDs in flowcharts must be valid identifiers
+            name.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          end
+
+          # Sanitize table name for Mermaid ERD
+          #
+          # @param name [String] raw table name
+          # @param preserve_case [Boolean] whether to preserve original case
+          # @return [String] sanitized table name
+          def table_name(name, preserve_case = nil)
+            return "UNKNOWN_TABLE" unless name.is_a?(String) && !name.empty?
+
+            preserve = if preserve_case.nil?
+                         Dbwatcher.configuration.diagram_preserve_table_case
+                       else
+                         preserve_case
+                       end
+
+            if preserve
+              name.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+            else
+              name.to_s.upcase.gsub(/[^A-Z0-9_]/, "_")
+            end
+          end
+
+          # Sanitize method name for Mermaid class diagrams
+          #
+          # @param name [String] raw method name
+          # @return [String] sanitized method name
+          def method_name(name)
+            return "unknown_method()" unless name.is_a?(String) && !name.empty?
+
+            # Ensure method name ends with parentheses
+            method = name.to_s.gsub(/[^a-zA-Z0-9_()]/, "_")
+            method += "()" unless method.include?("(")
+            method
+          end
+
+          # Sanitize relationship label for Mermaid diagrams
+          #
+          # @param label [String] raw label
+          # @return [String] sanitized label
+          def label(label)
+            return "" unless label.is_a?(String) && !label.empty?
+
+            # For Mermaid, we need to escape quotes but not remove them completely
+            # We'll escape backslashes and double quotes, and replace newlines with spaces
+            label.to_s.gsub("\\", "\\\\").gsub('"', '\\"').gsub(/[\n\r]/, " ").strip
+          end
+
+          # Sanitize attribute type for Mermaid ERD
+          #
+          # @param type [String] raw attribute type
+          # @return [String] sanitized attribute type
+          def attribute_type(type)
+            return "string" unless type.is_a?(String) && !type.empty?
+
+            type.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          end
+        end
+      end
+    end
+  end
+end