lutaml 0.9.43 → 0.10.0

data/lib/lutaml/qea/factory/package_transformer.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "base_transformer"
+require_relative "tagged_value_transformer"
+require_relative "instance_transformer"
+require "lutaml/uml"
+
+module Lutaml
+  module Qea
+    module Factory
+      # Transforms EA packages to UML packages
+      class PackageTransformer < BaseTransformer
+        # Transform EA package to UML package
+        # @param ea_package [EaPackage] EA package model
+        # @return [Lutaml::Uml::Package] UML package
+        def transform(ea_package) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          return nil if ea_package.nil?
+
+          Lutaml::Uml::Package.new.tap do |pkg|
+            # Map basic properties
+            pkg.name = ea_package.name
+            pkg.xmi_id = normalize_guid_to_xmi_format(ea_package.ea_guid,
+                                                      "EAPK")
+
+            # Map definition/notes
+            pkg.definition = ea_package.notes unless
+              ea_package.notes.nil? || ea_package.notes.empty?
+
+            # Load and transform tagged values
+            # TODO: Fix tagged_values assignment - temporarily commented out
+            # pkg.tagged_values = load_tagged_values(ea_package.ea_guid)
+
+            # Load stereotype from t_xref
+            stereotype = load_stereotype(ea_package.ea_guid)
+            pkg.stereotype = stereotype if stereotype
+
+            # Note: Child packages and contents will be loaded separately
+            # to avoid circular dependencies and allow lazy loading
+            # Don't initialize collections - they have default values
+          end
+        end
+
+        # Transform and build complete package hierarchy
+        # @param ea_package [EaPackage] Root EA package
+        # @param include_children [Boolean] Whether to recursively load children
+        # @return [Lutaml::Uml::Package] Complete UML package with hierarchy
+        def transform_with_hierarchy(ea_package, include_children: true)
+          pkg = transform(ea_package)
+          return pkg unless include_children
+
+          # Load child packages
+          child_packages = load_child_packages(ea_package.package_id)
+          pkg.packages = child_packages.map do |child_pkg|
+            transform_with_hierarchy(child_pkg, include_children: true)
+          end
+
+          # Load package contents (classes, diagrams, etc.)
+          load_package_contents(pkg, ea_package.package_id)
+
+          pkg
+        end
+
+        private
+
+        # Load child packages
+        # @param parent_id [Integer] Parent package ID
+        # @return [Array<EaPackage>] Child packages
+        def load_child_packages(parent_id)
+          return [] if parent_id.nil?
+
+          query = "SELECT * FROM t_package WHERE Parent_ID = ? " \
+                  "ORDER BY TPos"
+          rows = database.connection.execute(query, parent_id)
+
+          rows.map { |row| Models::EaPackage.from_db_row(row) }
+        end
+
+        # Load package contents (objects and diagrams)
+        # @param pkg [Lutaml::Uml::Package] UML package to populate
+        # @param package_id [Integer] EA package ID
+        def load_package_contents(pkg, package_id)
+          return if package_id.nil?
+
+          # Load objects (classes, etc.) in this package
+          load_package_objects(pkg, package_id)
+
+          # Load diagrams in this package
+          load_package_diagrams(pkg, package_id)
+        end
+
+        # Load objects for a package
+        # @param pkg [Lutaml::Uml::Package] UML package
+        # @param package_id [Integer] Package ID
+        def load_package_objects(pkg, package_id) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          query = "SELECT * FROM t_object WHERE Package_ID = ?"
+          rows = database.connection.execute(query, package_id)
+
+          ea_objects = rows.map { |row| Models::EaObject.from_db_row(row) }
+
+          # Transform classes - include ALL class-type objects,
+          # even without names
+          # Also include Text objects that appear on diagrams
+          # (EA exports these as classes in XMI)
+          class_transformer = ClassTransformer.new(database)
+          ea_objects.each do |ea_obj|
+            is_class_type = ea_obj.uml_class? || ea_obj.interface?
+            is_text_on_diagram = ea_obj.object_type == "Text" &&
+              appears_on_diagram?(ea_obj.ea_object_id)
+
+            next unless is_class_type || is_text_on_diagram
+
+            uml_class = class_transformer.transform(ea_obj)
+            pkg.classes << uml_class if uml_class
+          end
+
+          # Transform instances (Object type)
+          instance_transformer = InstanceTransformer.new(database)
+          ea_objects.select(&:instance?).each do |ea_obj|
+            uml_instance = instance_transformer.transform(ea_obj)
+            pkg.instances << uml_instance if uml_instance
+          end
+
+          # Note: Enums and DataTypes could be added similarly
+        end
+
+        # Load diagrams for a package
+        # @param pkg [Lutaml::Uml::Package] UML package
+        # @param package_id [Integer] Package ID
+        def load_package_diagrams(pkg, package_id)
+          diagram_transformer = DiagramTransformer.new(database)
+
+          query = "SELECT * FROM t_diagram WHERE Package_ID = ?"
+          rows = database.connection.execute(query, package_id)
+
+          ea_diagrams = rows.map { |row| Models::EaDiagram.from_db_row(row) }
+          pkg.diagrams = diagram_transformer.transform_collection(ea_diagrams)
+        end
+
+        # Load and transform tagged values for a package
+        # @param ea_guid [String] Element GUID
+        # @return [Array<Lutaml::Uml::TaggedValue>] UML tagged values
+        def load_tagged_values(ea_guid)
+          return [] if ea_guid.nil?
+          return [] unless database.tagged_values
+
+          # Filter tagged values for this element from the in-memory collection
+          ea_tags = database.tagged_values.select do |tag|
+            tag.element_id == ea_guid
+          end
+
+          # Transform to UML tagged values
+          tag_transformer = TaggedValueTransformer.new(database)
+          tag_transformer.transform_collection(ea_tags)
+        end
+
+        # Load stereotype from t_xref table
+        # @param ea_guid [String] Element GUID
+        # @return [String, nil] Stereotype value (as string to match XMI format)
+        def load_stereotype(ea_guid) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          return nil if ea_guid.nil?
+          return nil unless database.xrefs
+
+          # Find stereotype xref from the in-memory collection
+          xref = database.xrefs.find do |x|
+            x.client == ea_guid &&
+              x.name == "Stereotypes" && x.type == "element property"
+          end
+
+          return nil unless xref
+
+          # Parse stereotype from Description field
+          # Format: @STEREO;Name=ApplicationSchema;FQName=GML::ApplicationSchema;@ENDSTEREO;
+          description = xref.description
+          return nil if description.nil? || description.empty?
+
+          # Extract the Name value from the @STEREO format
+          if description =~ /@STEREO;Name=([^;]+);/
+            return $1
+          end
+
+          nil
+        end
+
+        # Check if an object appears on any diagram
+        # @param object_id [Integer] Object ID
+        # @return [Boolean] True if object appears on a diagram
+        def appears_on_diagram?(object_id)
+          return false if object_id.nil?
+          return false unless database.diagram_objects
+
+          # Check if object appears in any diagram's objects
+          database.diagram_objects.any? do |dobj|
+            dobj.ea_object_id == object_id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/qea/factory/reference_resolver.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Qea
+    module Factory
+      # Resolves references between EA and UML elements
+      # Maps EA GUIDs to UML xmi_ids and maintains object relationships
+      class ReferenceResolver
+        # Initialize empty resolver
+        def initialize
+          @guid_to_element = {}
+          @object_id_to_name = {}
+        end
+
+        # Register EA GUID to UML element mapping
+        # @param ea_guid [String] EA GUID
+        # @param uml_element [Object] UML element with xmi_id
+        # @return [void]
+        def register(ea_guid, uml_element)
+          return if ea_guid.nil? || uml_element.nil?
+
+          @guid_to_element[normalize_guid(ea_guid)] = uml_element
+        end
+
+        # Register object ID to name mapping
+        # @param object_id [Integer] EA object ID
+        # @param name [String] Object name
+        # @return [void]
+        def register_object_name(object_id, name)
+          return if object_id.nil?
+
+          @object_id_to_name[object_id] = name
+        end
+
+        # Resolve EA GUID to UML element
+        # @param ea_guid [String] EA GUID
+        # @return [Object, nil] UML element or nil if not found
+        def resolve(ea_guid)
+          return nil if ea_guid.nil?
+
+          @guid_to_element[normalize_guid(ea_guid)]
+        end
+
+        # Get object name by object ID
+        # @param object_id [Integer] EA object ID
+        # @return [String, nil] Object name or nil if not found
+        def resolve_object_name(object_id)
+          return nil if object_id.nil?
+
+          @object_id_to_name[object_id]
+        end
+
+        # Get UML xmi_id by EA GUID
+        # @param ea_guid [String] EA GUID
+        # @return [String, nil] xmi_id or nil if not found
+        def resolve_xmi_id(ea_guid)
+          element = resolve(ea_guid)
+          element&.xmi_id
+        end
+
+        # Check if GUID is registered
+        # @param ea_guid [String] EA GUID
+        # @return [Boolean] True if registered
+        def registered?(ea_guid)
+          return false if ea_guid.nil?
+
+          @guid_to_element.key?(normalize_guid(ea_guid))
+        end
+
+        # Clear all mappings
+        # @return [void]
+        def clear
+          @guid_to_element.clear
+          @object_id_to_name.clear
+        end
+
+        # Get statistics
+        # @return [Hash] Statistics about registered elements
+        def stats
+          {
+            total_elements: @guid_to_element.size,
+            total_objects: @object_id_to_name.size,
+          }
+        end
+
+        private
+
+        # Normalize GUID format (remove braces, upcase)
+        # @param guid [String] GUID string
+        # @return [String] Normalized GUID
+        def normalize_guid(guid)
+          return guid if guid.nil?
+
+          guid.to_s.gsub(/[{}]/, "").upcase
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/qea/factory/tagged_value_transformer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base_transformer"
+require "lutaml/uml"
+
+module Lutaml
+  module Qea
+    module Factory
+      # Transforms EA TaggedValue to UML TaggedValue
+      #
+      # This transformer converts Enterprise Architect tagged value
+      # definitions (custom metadata) to standard UML TaggedValue objects.
+      #
+      # @example Transform a tagged value
+      #   ea_tag = Models::EaTaggedValue.new(
+      #     property_id: "{GUID}",
+      #     element_id: "{ELEMENT-GUID}",
+      #     base_class: "ASSOCIATION_SOURCE",
+      #     tag_value: "sequenceNumber|15$ea_notes=Unique integer..."
+      #   )
+      #   transformer = TaggedValueTransformer.new(database)
+      #   uml_tag = transformer.transform(ea_tag)
+      class TaggedValueTransformer < BaseTransformer
+        # Transform EA tagged value to UML TaggedValue
+        #
+        # @param ea_tag [Models::EaTaggedValue] EA tagged value model
+        # @return [Lutaml::Uml::TaggedValue, nil] UML tagged value or nil
+        def transform(ea_tag)
+          return nil unless ea_tag
+          return nil unless ea_tag.tag_name
+
+          Lutaml::Uml::TaggedValue.new.tap do |tag|
+            tag.name = ea_tag.tag_name
+            tag.value = ea_tag.parsed_value || ""
+            tag.notes = ea_tag.parsed_notes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/qea/factory/transformer_registry.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "class_transformer"
+require_relative "attribute_transformer"
+require_relative "operation_transformer"
+require_relative "association_transformer"
+require_relative "generalization_transformer"
+require_relative "package_transformer"
+require_relative "diagram_transformer"
+
+module Lutaml
+  module Qea
+    module Factory
+      # Registry for EA to UML transformers
+      # Implements the Registry pattern for transformer lookup
+      class TransformerRegistry
+        class << self
+          # Get or initialize the registry
+          # @return [Hash] Registry hash
+          def registry
+            @registry ||= {}
+          end
+
+          # Register a transformer for an EA type
+          # @param ea_type [Symbol, String] EA model type
+          # @param transformer_class [Class] Transformer class
+          def register(ea_type, transformer_class)
+            registry[ea_type.to_sym] = transformer_class
+          end
+
+          # Get transformer for an EA type
+          # @param ea_type [Symbol, String] EA model type
+          # @return [Class, nil] Transformer class or nil if not found
+          def transformer_for(ea_type)
+            registry[ea_type.to_sym]
+          end
+
+          # Get all registered transformers
+          # @return [Hash] All registered transformers
+          def all_transformers
+            registry.dup
+          end
+
+          # Check if a transformer is registered for a type
+          # @param ea_type [Symbol, String] EA model type
+          # @return [Boolean] True if registered
+          def registered?(ea_type)
+            registry.key?(ea_type.to_sym)
+          end
+
+          # Clear all registrations (mainly for testing)
+          def clear
+            @registry = {}
+          end
+
+          # Reset to default registrations
+          def reset_defaults
+            clear
+            register_defaults
+          end
+
+          # Register default transformers
+          def register_defaults
+            # Object types
+            register(:class, ClassTransformer)
+            register(:interface, ClassTransformer)
+            register(:package, PackageTransformer)
+
+            # Connector types
+            register(:association, AssociationTransformer)
+            register(:generalization, GeneralizationTransformer)
+
+            # Other types
+            register(:attribute, AttributeTransformer)
+            register(:operation, OperationTransformer)
+            register(:diagram, DiagramTransformer)
+          end
+        end
+
+        # Initialize registry with default transformers
+        register_defaults
+      end
+    end
+  end
+end

data/lib/lutaml/qea/file_detector.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module Lutaml
+  module Qea
+    # Utility for detecting and validating QEA files
+    class FileDetector
+      # SQLite magic bytes
+      SQLITE_MAGIC = "SQLite format 3\x00"
+
+      # Required EA tables for valid QEA file
+      REQUIRED_EA_TABLES = %w[
+        t_object
+        t_attribute
+        t_connector
+        t_package
+      ].freeze
+
+      class << self
+        # Check if file is a QEA file
+        #
+        # @param path [String] File path
+        # @return [Boolean] True if file appears to be QEA
+        def qea_file?(path)
+          return false unless File.exist?(path)
+          return false unless File.file?(path)
+          return false unless path.end_with?(".qea")
+
+          # Quick check: is it SQLite?
+          sqlite_file?(path)
+        end
+
+        # Validate QEA file structure
+        #
+        # @param path [String] File path
+        # @return [Hash] Validation result with :valid, :errors, :warnings
+        #
+        # @example
+        #   result = FileDetector.validate_qea("model.qea")
+        #   if result[:valid]
+        #     puts "Valid QEA file"
+        #   else
+        #     puts "Errors: #{result[:errors]}"
+        #   end
+        def validate_qea(path) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          errors = []
+          warnings = []
+
+          # Check file exists
+          unless File.exist?(path)
+            return {
+              valid: false,
+              errors: ["File not found: #{path}"],
+              warnings: [],
+            }
+          end
+
+          # Check file extension
+          unless path.end_with?(".qea")
+            warnings << "File does not have .qea extension"
+          end
+
+          # Check SQLite format
+          unless sqlite_file?(path)
+            errors << "File is not a valid SQLite database"
+            return { valid: false, errors: errors, warnings: warnings }
+          end
+
+          # Check for EA tables
+          begin
+            db = SQLite3::Database.new(path, readonly: true)
+            tables = get_table_names(db)
+
+            REQUIRED_EA_TABLES.each do |required_table|
+              unless tables.include?(required_table)
+                errors << "Missing required EA table: #{required_table}"
+              end
+            end
+
+            # Check for data
+            if tables.include?("t_object")
+              count = db.execute("SELECT COUNT(*) FROM t_object").first.first
+              if count.zero?
+                warnings << "No objects found in t_object table"
+              end
+            end
+          rescue SQLite3::Exception => e
+            errors << "Failed to open database: #{e.message}"
+          ensure
+            db&.close
+          end
+
+          {
+            valid: errors.empty?,
+            errors: errors,
+            warnings: warnings,
+          }
+        end
+
+        # Get file information
+        #
+        # @param path [String] File path
+        # @return [Hash] File information
+        #
+        # @example
+        #   info = FileDetector.file_info("model.qea")
+        #   puts "Size: #{info[:size_mb]} MB"
+        #   puts "Tables: #{info[:table_count]}"
+        def file_info(path) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          return { error: "File not found" } unless File.exist?(path)
+
+          info = {
+            path: path,
+            size_bytes: File.size(path),
+            size_mb: (File.size(path) / 1024.0 / 1024.0).round(2),
+            modified: File.mtime(path),
+            is_qea: qea_file?(path),
+          }
+
+          if sqlite_file?(path)
+            begin
+              db = SQLite3::Database.new(path, readonly: true)
+              tables = get_table_names(db)
+              info[:is_sqlite] = true
+              info[:table_count] = tables.size
+              info[:has_ea_tables] = REQUIRED_EA_TABLES.all? do |t|
+                tables.include?(t)
+              end
+
+              # Get record counts for key tables
+              if tables.include?("t_object")
+                info[:object_count] =
+                  db.execute("SELECT COUNT(*) FROM t_object").first.first
+              end
+              if tables.include?("t_package")
+                info[:package_count] =
+                  db.execute("SELECT COUNT(*) FROM t_package").first.first
+              end
+            rescue SQLite3::Exception => e
+              info[:error] = e.message
+            ensure
+              db&.close
+            end
+          else
+            info[:is_sqlite] = false
+          end
+
+          info
+        end
+
+        private
+
+        # Check if file is SQLite database
+        #
+        # @param path [String] File path
+        # @return [Boolean] True if SQLite database
+        def sqlite_file?(path)
+          File.open(path, "rb") do |f|
+            magic = f.read(16)
+            magic == SQLITE_MAGIC
+          end
+        rescue StandardError
+          false
+        end
+
+        # Get table names from database
+        #
+        # @param db [SQLite3::Database] Database connection
+        # @return [Array<String>] Table names
+        def get_table_names(db)
+          db.execute("SELECT name FROM sqlite_master WHERE type='table'")
+            .flatten
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/qea/infrastructure/database_connection.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module Lutaml
+  module Qea
+    module Infrastructure
+      # DatabaseConnection manages the SQLite database connection lifecycle
+      # for QEA files (Enterprise Architect SQLite databases).
+      #
+      # @example Connect to a QEA file
+      #   conn = DatabaseConnection.new("model.qea")
+      #   conn.connect
+      #   # ... use connection
+      #   conn.close
+      #
+      # @example Using with_connection block
+      #   conn = DatabaseConnection.new("model.qea")
+      #   conn.with_connection do |db|
+      #     # ... use db
+      #   end
+      class DatabaseConnection
+        attr_reader :file_path, :connection
+
+        # Initialize a new database connection
+        #
+        # @param file_path [String] Path to the .qea file
+        # @raise [ArgumentError] if file_path is nil or empty
+        def initialize(file_path)
+          if file_path.nil? || file_path.empty?
+            raise ArgumentError,
+                  "file_path cannot be nil or empty"
+          end
+
+          @file_path = file_path
+          @connection = nil
+        end
+
+        # Connect to the database
+        #
+        # @return [SQLite3::Database] The database connection
+        # @raise [Errno::ENOENT] if the file does not exist
+        # @raise [SQLite3::Exception] if connection fails
+        def connect
+          unless File.exist?(@file_path)
+            raise Errno::ENOENT, "QEA file not found: #{@file_path}"
+          end
+
+          @connection = SQLite3::Database.new(@file_path, readonly: true)
+          @connection.results_as_hash = true
+          @connection
+        end
+
+        # Close the database connection
+        #
+        # @return [void]
+        def close
+          return unless @connection
+
+          @connection.close
+          @connection = nil
+        end
+
+        # Check if the connection is open
+        #
+        # @return [Boolean] true if connection is open
+        def connected?
+          !@connection.nil? && !@connection.closed?
+        end
+
+        # Execute a block with an active connection
+        #
+        # This method ensures the connection is properly opened and closed.
+        # If a connection already exists, it reuses it. Otherwise, it creates
+        # a new connection and closes it after the block executes.
+        #
+        # @yield [SQLite3::Database] The database connection
+        # @return [Object] The result of the block
+        # @raise [Errno::ENOENT] if the file does not exist
+        # @raise [SQLite3::Exception] if connection fails
+        #
+        # @example
+        #   conn = DatabaseConnection.new("model.qea")
+        #   result = conn.with_connection do |db|
+        #     db.execute("SELECT COUNT(*) FROM t_object")
+        #   end
+        def with_connection
+          should_close = !connected?
+
+          begin
+            connect unless connected?
+            yield @connection
+          ensure
+            close if should_close
+          end
+        end
+      end
+    end
+  end
+end