ea 0.1.0 → 0.1.4

data/lib/ea/qea/factory/document_builder.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Ea
+  module Qea
+    module Factory
+      # Builds and validates UML Document structure
+      # Ensures all required document sections are populated correctly
+      class DocumentBuilder
+        attr_reader :document
+
+        # Initialize builder with new document
+        # @param name [String] Document name
+        def initialize(name: "EA Model")
+          @document = Lutaml::Uml::Document.new
+          @document.name = name
+          # Don't initialize collections - they have default values
+        end
+
+        # Add packages to document
+        # @param packages [Array<Lutaml::Uml::Package>] Packages to add
+        # @return [self] For method chaining
+        def add_packages(packages)
+          return self if packages.nil? || packages.empty?
+
+          @document.packages.concat(packages)
+          self
+        end
+
+        # Add classes to document
+        # @param classes [Array<Lutaml::Uml::UmlClass>] Classes to add
+        # @return [self] For method chaining
+        def add_classes(classes)
+          return self if classes.nil? || classes.empty?
+
+          @document.classes.concat(classes)
+          self
+        end
+
+        # Add enums to document
+        # @param enums [Array<Lutaml::Uml::Enum>] Enums to add
+        # @return [self] For method chaining
+        def add_enums(enums)
+          return self if enums.nil? || enums.empty?
+
+          @document.enums.concat(enums)
+          self
+        end
+
+        # Add data types to document
+        # @param data_types [Array<Lutaml::Uml::DataType>] Data types to add
+        # @return [self] For method chaining
+        def add_data_types(data_types)
+          return self if data_types.nil? || data_types.empty?
+
+          @document.data_types.concat(data_types)
+          self
+        end
+
+        # Add instances to document
+        # @param instances [Array<Lutaml::Uml::Instance>] Instances to add
+        # @return [self] For method chaining
+        def add_instances(instances)
+          return self if instances.nil? || instances.empty?
+
+          @document.instances.concat(instances)
+          self
+        end
+
+        # Add associations to document
+        # @param associations [Array<Lutaml::Uml::Association>] Associations
+        # @return [self] For method chaining
+        def add_associations(associations)
+          return self if associations.nil? || associations.empty?
+
+          @document.associations.concat(associations)
+          self
+        end
+
+        # Add diagrams to document
+        # @param diagrams [Array<Lutaml::Uml::Diagram>] Diagrams
+        # @return [self] For method chaining
+        def add_diagrams(diagrams)
+          return self if diagrams.nil? || diagrams.empty?
+
+          @document.diagrams.concat(diagrams)
+          self
+        end
+
+        # Set document metadata
+        # @param title [String] Document title
+        # @param caption [String] Document caption
+        # @return [self] For method chaining
+        def set_metadata(title: nil, caption: nil)
+          @document.title = title if title
+          @document.caption = caption if caption
+          self
+        end
+
+        # Build and return the document
+        # @param validate [Boolean] Whether to validate before returning
+        # @return [Lutaml::Uml::Document] The built document
+        # @raise [ValidationError] If validation fails
+        def build(validate: true)
+          validate! if validate
+          @document
+        end
+
+        # Validate document integrity
+        # @return [Boolean] True if valid
+        # @raise [ValidationError] If validation fails
+        def validate! # rubocop:disable Metrics/MethodLength
+          errors = []
+          warnings = []
+
+          # Check for duplicate xmi_ids
+          check_duplicate_xmi_ids(errors)
+
+          # Check association references (warnings only for missing refs)
+          check_association_references(warnings)
+
+          # Print warnings if any
+          unless warnings.empty?
+            warn "Document validation warnings:"
+            warnings.each { |w| warn "  - #{w}" }
+          end
+
+          raise ValidationError, errors.join("; ") unless errors.empty?
+
+          true
+        end
+
+        # Get document statistics
+        # @return [Hash] Statistics about document contents
+        def stats
+          {
+            packages: @document.packages.size,
+            classes: @document.classes.size,
+            enums: @document.enums.size,
+            data_types: @document.data_types.size,
+            instances: @document.instances.size,
+            associations: @document.associations.size,
+          }
+        end
+
+        private
+
+        # Check for duplicate xmi_ids across all elements
+        # @param errors [Array<String>] Error accumulator
+        def check_duplicate_xmi_ids(errors)
+          xmi_ids = collect_all_xmi_ids
+          duplicates = xmi_ids.group_by { |id| id }
+            .select { |_, v| v.size > 1 }
+            .keys
+
+          unless duplicates.empty?
+            errors << "Duplicate xmi_ids found: #{duplicates.join(', ')}"
+          end
+        end
+
+        # Collect all xmi_ids from document
+        # @return [Array<String>] All xmi_ids
+        def collect_all_xmi_ids # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
+          ids = []
+
+          # Collect from top-level elements
+          ids.concat(@document.packages.filter_map(&:xmi_id))
+          ids.concat(@document.classes.filter_map(&:xmi_id))
+          ids.concat(@document.enums.filter_map(&:xmi_id))
+          ids.concat(@document.data_types.filter_map(&:xmi_id))
+          ids.concat(@document.instances.filter_map(&:xmi_id))
+
+          # Recursively collect from packages (where most classes actually are)
+          @document.packages.each do |package|
+            ids.concat(collect_package_xmi_ids(package))
+          end
+
+          ids
+        end
+
+        # Recursively collect all xmi_ids from a package and its descendants
+        # @param package [Lutaml::Uml::Package] Package to collect from
+        # @return [Array<String>] All xmi_ids in package hierarchy
+        def collect_package_xmi_ids(package) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          ids = []
+
+          # Collect from package's elements
+          ids.concat(package.classes.filter_map(&:xmi_id)) if package.classes
+          ids.concat(package.enums.filter_map(&:xmi_id)) if package.enums
+          if package.data_types
+            ids.concat(package.data_types.filter_map(&:xmi_id))
+          end
+          if package.instances
+            ids.concat(package.instances.filter_map(&:xmi_id))
+          end
+
+          # Recursively collect from child packages
+          package.packages&.each do |child_package|
+            ids.concat(collect_package_xmi_ids(child_package))
+          end
+
+          ids
+        end
+
+        # Check that all association references are valid
+        # @param warnings [Array<String>] Warning accumulator
+        def check_association_references(warnings) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          return if @document.associations.empty?
+
+          all_xmi_ids = collect_all_xmi_ids.to_set
+          invalid_associations = []
+
+          @document.associations.each do |assoc|
+            has_invalid_member = !check_association_end_valid?(
+              assoc, :member_end_xmi_id, all_xmi_ids
+            )
+            has_invalid_owner = !check_association_end_valid?(
+              assoc, :owner_end_xmi_id, all_xmi_ids
+            )
+
+            if has_invalid_member || has_invalid_owner
+              invalid_associations << assoc
+              if has_invalid_member
+                add_invalid_end_warning(assoc, :member_end_xmi_id, all_xmi_ids,
+                                        warnings)
+              end
+              if has_invalid_owner
+                add_invalid_end_warning(assoc, :owner_end_xmi_id, all_xmi_ids,
+                                        warnings)
+              end
+            end
+          end
+
+          # Remove invalid associations from document
+          unless invalid_associations.empty?
+            @document.associations.reject! do |a|
+              invalid_associations.include?(a)
+            end
+            warnings << "Removed #{invalid_associations.size} association(s) " \
+                        "with invalid references"
+          end
+        end
+
+        # Check if association end reference is valid
+        # @param assoc [Lutaml::Uml::Association] Association
+        # @param attr [Symbol] Attribute to check (should be xmi_id attribute)
+        # @param valid_ids [Set<String>] Set of valid xmi_ids
+        # @return [Boolean] True if valid or nil
+        def check_association_end_valid?(assoc, attr, valid_ids)
+          value = assoc.public_send(attr)
+          return true if value.nil?
+
+          valid_ids.include?(value)
+        end
+
+        # Add warning for invalid association end
+        # @param assoc [Lutaml::Uml::Association] Association
+        # @param attr [Symbol] Attribute to check (should be xmi_id attribute)
+        # @param valid_ids [Set<String>] Set of valid xmi_ids
+        # @param warnings [Array<String>] Warning accumulator
+        def add_invalid_end_warning(assoc, attr, valid_ids, warnings) # rubocop:disable Metrics/MethodLength
+          value = assoc.public_send(attr)
+          return if value.nil?
+
+          unless valid_ids.include?(value)
+            # Get the corresponding name attribute for better error messages
+            name_attr = attr.to_s.gsub("_xmi_id", "").to_sym
+            name_value = begin
+              assoc.public_send(name_attr)
+            rescue StandardError
+              nil
+            end
+
+            warnings << "Association #{assoc.xmi_id} references " \
+                        "invalid #{name_attr}: #{name_value}"
+          end
+        end
+
+        # Custom validation error
+        class ValidationError < Ea::Error; end
+      end
+    end
+  end
+end

data/lib/ea/qea/factory/ea_to_uml_factory.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Ea
+  module Qea
+    module Factory
+      # Main factory for orchestrating EA to UML transformation
+      # Implements Facade pattern for complete model transformation
+      class EaToUmlFactory
+        attr_reader :database, :options, :resolver
+
+        # Initialize factory with EA database
+        # @param database [Ea::Qea::Database] Loaded EA database
+        # @param options [Hash] Transformation options
+        # @option options [Boolean] :include_diagrams Include diagrams
+        # (default: true)
+        # @option options [Boolean] :validate Validate output (default: true)
+        # @option options [String] :document_name Document name
+        def initialize(database, options = {})
+          @database = database
+          @options = default_options.merge(options)
+          @resolver = ReferenceResolver.new
+          @transformers = {}
+        end
+
+        # Create complete UML document from EA database
+        # @return [Lutaml::Uml::Document] Complete UML document
+        def create_document # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          builder = DocumentBuilder.new(
+            name: options[:document_name] || "EA Model",
+          )
+
+          # Transform packages with hierarchy (includes all classes)
+          packages = transform_packages
+
+          # Transform associations (references classes by xmi_id)
+          associations = transform_associations
+
+          # Collect class-level associations from packages
+          # class-level associations contain associations with both directions
+          # and it may include associations in connector level
+          # i.e. owner_end -> member_end and member_end -> owner_end
+          class_associations = collect_class_association(packages)
+
+          # Orphaned classes: EA class objects whose package_id does not
+          # resolve to a known package. Attach them to the document root so
+          # their associations can resolve.
+          orphan_classes = transform_orphan_classes
+
+          # Build document with both connector-level and
+          # class-level associations
+          builder.add_packages(packages)
+            .add_classes(orphan_classes)
+            .add_associations(associations)
+            .add_associations(class_associations)
+
+          # Add diagrams if requested
+          if options[:include_diagrams]
+            builder.add_diagrams(transform_diagrams)
+          end
+
+          builder.build(validate: options[:validate])
+        end
+
+        # Transform all packages with hierarchy
+        # @return [Array<Lutaml::Uml::Package>] Root packages
+        def transform_packages # rubocop:disable Metrics/MethodLength
+          root_packages = database.packages.select do |pkg|
+            pkg.parent_id.nil? || pkg.parent_id.zero?
+          end
+
+          package_transformer = get_transformer(:package)
+          root_packages.filter_map do |ea_package|
+            uml_package = package_transformer.transform_with_hierarchy(
+              ea_package,
+              include_children: true,
+            )
+
+            register_package_hierarchy(uml_package)
+
+            uml_package
+          end
+        end
+
+        # Transform EA class objects that have no resolvable parent package.
+        #
+        # EA occasionally stores class rows whose `package_id` does not
+        # correspond to any row in `t_package` (typically the result of a
+        # deleted package whose children were not reparented). These classes
+        # would otherwise be silently dropped, breaking any associations that
+        # reference them. Attach them to the document root instead.
+        #
+        # @return [Array<Lutaml::Uml::UmlClass>] Orphaned UML classes
+        def transform_orphan_classes
+          class_transformer = get_transformer(:class)
+
+          orphans = ea_class_objects.reject do |ea_object|
+            package_known?(ea_object.package_id)
+          end
+
+          uml_classes = class_transformer.transform_collection(orphans)
+          uml_classes.each { |uml_class| register_element(uml_class) }
+          uml_classes
+        end
+
+        # All EA class-like objects (classes and interfaces)
+        # @return [Array<Ea::Qea::Models::EaObject>]
+        def ea_class_objects
+          database.objects.find_by_type("Class") +
+            database.objects.find_by_type("Interface")
+        end
+
+        # Whether a package_id resolves to a known package in t_package
+        # @param package_id [Integer, nil]
+        # @return [Boolean]
+        def package_known?(package_id)
+          return false if package_id.nil?
+
+          !database.find_package(package_id).nil?
+        end
+
+        # Transform all associations
+        # @return [Array<Lutaml::Uml::Association>] All UML associations
+        def transform_associations # rubocop:disable Metrics/MethodLength
+          association_transformer = get_transformer(:association)
+
+          ea_associations = database.connectors.select(&:association?)
+
+          uml_associations = association_transformer.transform_collection(
+            ea_associations,
+          )
+
+          uml_associations.each do |uml_assoc|
+            register_element(uml_assoc)
+          end
+
+          uml_associations
+        end
+
+        # Transform all diagrams
+        # @return [Array<Lutaml::Uml::Diagram>] All UML diagrams
+        def transform_diagrams
+          diagram_transformer = get_transformer(:diagram)
+          diagram_transformer.transform_collection(database.diagrams)
+        end
+
+        # Register custom transformers, overriding registry defaults
+        # @param transformers [Hash] Custom transformer instances keyed by type
+        # @return [self] For method chaining
+        def with_transformers(transformers)
+          @transformers.merge!(transformers)
+          self
+        end
+
+        private
+
+        def default_options
+          {
+            include_diagrams: true,
+            validate: true,
+            document_name: "EA Model",
+          }
+        end
+
+        # Get or create transformer by type using the TransformerRegistry
+        # @param type [Symbol] Transformer type
+        # @return [BaseTransformer] Transformer instance
+        def get_transformer(type)
+          return @transformers[type] if @transformers.key?(type)
+
+          transformer_class = TransformerRegistry.transformer_for(type)
+          unless transformer_class
+            raise ArgumentError, "Unknown transformer type: #{type}"
+          end
+
+          @transformers[type] = transformer_class.new(database)
+        end
+
+        def register_package_hierarchy(package)
+          return if package.nil?
+
+          register_element(package)
+          register_package_members(package)
+
+          package.packages&.each do |child_package|
+            register_package_hierarchy(child_package)
+          end
+        end
+
+        MEMBER_COLLECTIONS = %i[classes enums data_types instances].freeze
+
+        def register_package_members(package)
+          MEMBER_COLLECTIONS.each do |collection|
+            package.public_send(collection)&.each do |elem|
+              register_element(elem)
+            end
+          end
+        end
+
+        def register_element(element)
+          return if element.nil? || element.xmi_id.nil?
+
+          @resolver.register(element.xmi_id, element)
+        end
+
+        def collect_class_association(packages)
+          associations = []
+
+          packages.each do |package|
+            collect_package_associations(package, associations)
+          end
+
+          associations
+        end
+
+        def collect_package_associations(package, associations) # rubocop:disable Metrics/CyclomaticComplexity
+          package.classes&.each do |klass|
+            if klass.associations && !klass.associations.empty?
+              associations.concat(klass.associations)
+            end
+          end
+
+          package.packages&.each do |child_package|
+            collect_package_associations(child_package, associations)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ea/qea/factory/enum_transformer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ea
+  module Qea
+    module Factory
+      # Transforms EA objects (Enumeration type) to UML enums
+      class EnumTransformer < BaseTransformer
+        # Transform EA object to UML enum
+        # @param ea_object [EaObject] EA object model
+        # @return [Lutaml::Uml::Enum] UML enum
+        def transform(ea_object)
+          return nil if ea_object.nil?
+          return nil unless enum?(ea_object)
+
+          Lutaml::Uml::Enum.new.tap do |enum|
+            assign_enum_basic(enum, ea_object)
+            assign_enum_features(enum, ea_object)
+          end
+        end
+
+        def assign_enum_basic(enum, ea_object)
+          enum.name = ea_object.name
+          enum.xmi_id = normalize_guid_to_xmi_format(ea_object.ea_guid,
+                                                     "EAID")
+          enum.visibility = map_visibility(ea_object.visibility)
+          enum.stereotype = [ea_object.stereotype] if valid_stereotype?(ea_object)
+          enum.definition = ea_object.note if note_present?(ea_object)
+        end
+
+        def note_present?(ea_object)
+          ea_object.note && !ea_object.note.empty?
+        end
+
+        def assign_enum_features(enum, ea_object)
+          enum.values = load_enum_values(ea_object.ea_object_id)
+          enum.tagged_values = load_tagged_values(ea_object.ea_guid)
+        end
+
+        private
+
+        def enum?(ea_object)
+          ea_object.enumeration? ||
+            (ea_object.stereotype && ea_object.stereotype.downcase == "enumeration")
+        end
+
+        def valid_stereotype?(ea_object)
+          ea_object.stereotype && !ea_object.stereotype.empty?
+        end
+
+        # Load enum values (literals) from attributes
+        # @param object_id [Integer] Object ID
+        # @return [Array<Lutaml::Uml::Value>] Enum values
+        def load_enum_values(object_id)
+          return [] if object_id.nil?
+
+          ea_attrs = database.attributes_for_object(object_id)
+            .sort_by { |a| a.pos || 0 }
+
+          ea_attrs.filter_map { |ea_attr| build_enum_value(ea_attr) }
+        end
+
+        def build_enum_value(ea_attr)
+          Lutaml::Uml::Value.new.tap do |value|
+            value.name = ea_attr.name
+            value.id = normalize_guid_to_xmi_format(ea_attr.ea_guid, "EAID")
+            value.definition = ea_attr.notes unless
+              ea_attr.notes.nil? || ea_attr.notes.empty?
+          end
+        end
+
+      end
+    end
+  end
+end