ea 0.1.0 → 0.1.4

data/lib/ea/transformations/transformation_engine.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformations
+    # Transformation Engine orchestrates the entire model transformation
+    # process.
+    #
+    # This class implements the Facade pattern to provide a simple interface
+    # for complex model transformation operations. It coordinates between
+    # configuration, format detection, parser selection, and transformation.
+    #
+    # The engine follows the Dependency Inversion Principle by depending on
+    # abstractions (BaseParser interface) rather than concrete implementations.
+    #
+    # @example Basic usage
+    #   engine = TransformationEngine.new
+    #   document = engine.parse("model.xmi")
+    #
+    # @example With custom configuration
+    #   config = Configuration.load("my_config.yml")
+    #   engine = TransformationEngine.new(config)
+    #   document = engine.parse("model.qea")
+    class TransformationEngine
+      # @return [Configuration] Current configuration
+      attr_reader :configuration
+
+      # @return [FormatRegistry] Format registry
+      attr_reader :format_registry
+
+      # @return [Array<Hash>] Transformation history
+      attr_reader :transformation_history
+
+      # @return [Parser] Parser instance
+      attr_reader :current_parser
+
+      # Initialize transformation engine
+      #
+      # @param configuration [Configuration, nil] Configuration to use
+      #   (defaults to auto-loaded configuration)
+      def initialize(configuration = nil)
+        @configuration = configuration || Configuration.load
+        @format_registry = FormatRegistry.new
+        @transformation_history = []
+        @parser_cache = {}
+
+        # Load parsers from configuration
+        setup_parsers
+      end
+
+      # Parse a model file into a UML document
+      #
+      # This is the main entry point for model transformation. It auto-detects
+      # the file format and uses the appropriate parser.
+      #
+      # @param file_path [String] Path to the model file
+      # @param options [Hash] Parsing options (merged with configuration)
+      # @return [Lutaml::Uml::Document] Parsed UML document
+      # @raise [UnsupportedFormatError] if file format is not supported
+      # @raise [ParseError] if parsing fails
+      def parse(file_path, options = {}) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        validate_file_path!(file_path)
+
+        # Detect format and get parser
+        parser_class = detect_parser(file_path)
+        raise UnsupportedFormatError.new(file_path) unless parser_class
+
+        # Create parser instance with merged options
+        merged_options = merge_options(options)
+        @current_parser = get_parser_instance(parser_class, merged_options)
+
+        # Record transformation start
+        transformation_start = Time.now
+
+        begin
+          # Perform parsing
+          document = @current_parser.parse(file_path)
+
+          # Record successful transformation
+          record_transformation(
+            file_path: file_path,
+            parser: @current_parser,
+            duration: Time.now - transformation_start,
+            success: true,
+            document: document,
+          )
+
+          document
+        rescue StandardError => e
+          # Record failed transformation
+          record_transformation(
+            file_path: file_path,
+            parser: @current_parser,
+            duration: Time.now - transformation_start,
+            success: false,
+            error: e,
+          )
+
+          # Re-raise the error
+          raise
+        end
+      end
+
+      # Auto-detect file format and return appropriate parser class
+      #
+      # Uses multiple detection strategies:
+      # 1. File extension
+      # 2. Content detection (magic bytes)
+      # 3. Fallback parser from configuration
+      #
+      # @param file_path [String] Path to the model file
+      # @return [Class, nil] Parser class, or nil if format cannot be detected
+      def detect_parser(file_path) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+        # Strategy 1: File extension detection
+        if @configuration.file_extension_detection_enabled?
+          parser_class = @format_registry.parser_for_file(file_path)
+          return parser_class if parser_class
+        end
+
+        # Strategy 2: Content detection
+        if @configuration.content_sniffing_enabled?
+          parser_class = @format_registry.detect_by_content(file_path)
+          return parser_class if parser_class
+        end
+
+        # Strategy 3: Fallback parser
+        fallback_parser_name = @configuration.fallback_parser
+        if fallback_parser_name
+          return Transformations.constantize(fallback_parser_name)
+        end
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Get list of supported file extensions
+      #
+      # @return [Array<String>] List of supported extensions
+      def supported_extensions
+        @format_registry.supported_extensions
+      end
+
+      # Check if a file format is supported
+      #
+      # @param file_path [String] Path to check
+      # @return [Boolean] true if format is supported
+      def supports_file?(file_path)
+        detect_parser(file_path) != nil
+      end
+
+      # Register a custom parser for a file extension
+      #
+      # @param extension [String] File extension (e.g., ".custom")
+      # @param parser_class [Class] Parser class implementing BaseParser
+      # interface
+      # @return [void]
+      def register_parser(extension, parser_class)
+        @format_registry.register(extension, parser_class)
+      end
+
+      # Unregister a parser for a file extension
+      #
+      # @param extension [String] File extension to unregister
+      # @return [Class, nil] The unregistered parser class
+      def unregister_parser(extension)
+        @format_registry.unregister(extension)
+      end
+
+      # Set configuration and reload parsers
+      #
+      # @param config [Configuration] New configuration
+      # @return [void]
+      def configuration=(config)
+        @configuration = config
+        @parser_cache.clear
+        setup_parsers
+      end
+
+      # Get comprehensive transformation statistics
+      #
+      # @return [Hash] Statistics about transformations
+      def statistics # rubocop:disable Metrics/MethodLength
+        successful_transformations = @transformation_history.count do |t|
+          t[:success]
+        end
+        failed_transformations = @transformation_history.count do |t|
+          !t[:success]
+        end
+
+        {
+          total_transformations: @transformation_history.size,
+          successful_transformations: successful_transformations,
+          failed_transformations: failed_transformations,
+          success_rate: calculate_success_rate,
+          average_duration: calculate_average_duration,
+          supported_extensions: supported_extensions,
+          registered_parsers: @format_registry.all_parsers.keys,
+          configuration_version: @configuration.version,
+        }
+      end
+
+      # Clear transformation history
+      #
+      # @return [void]
+      def clear_history
+        @transformation_history.clear
+      end
+
+      # Get transformation history for a specific file
+      #
+      # @param file_path [String] Path to the file
+      # @return [Array<Hash>] Transformation history entries for the file
+      def history_for_file(file_path)
+        @transformation_history.select do |entry|
+          entry[:file_path] == file_path
+        end
+      end
+
+      # Get recent transformation failures
+      #
+      # @param limit [Integer] Maximum number of failures to return
+      # @return [Array<Hash>] Recent failure entries
+      def recent_failures(limit = 10)
+        @transformation_history
+          .reject { |entry| entry[:success] }
+          .last(limit)
+      end
+
+      # Validate configuration and parsers
+      #
+      # @return [Hash] Validation results
+      def validate_setup # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        results = {
+          configuration_valid: false,
+          parsers_loaded: 0,
+          parser_errors: [],
+          warnings: [],
+        }
+
+        # Validate configuration
+        begin
+          if @configuration&.enabled_parsers&.any?
+            results[:configuration_valid] = true
+          else
+            results[:warnings] << "No enabled parsers in configuration"
+          end
+        rescue StandardError => e
+          results[:parser_errors] << "Configuration error: #{e.message}"
+        end
+
+        # Validate each parser
+        @format_registry.all_parsers.each_value do |parser_class|
+          # Try to create instance to validate
+          parser = parser_class.new(configuration: @configuration)
+          if parser.is_a?(Parsers::BaseParser)
+            results[:parsers_loaded] += 1
+          else
+            results[:parser_errors] << "Parser #{parser_class} does not " \
+                                       "implement parse method"
+          end
+        rescue StandardError => e
+          results[:parser_errors] << "Failed to instantiate #{parser_class}: " \
+                                     "#{e.message}"
+        end
+
+        results
+      end
+
+      private
+
+      # Setup parsers from configuration
+      #
+      # @return [void]
+      def setup_parsers
+        # Clear existing parsers
+        @format_registry.clear
+
+        # Load parsers from configuration
+        @format_registry.load_from_configuration(@configuration)
+
+        # Load default parsers if none configured
+        if @format_registry.supported_extensions.empty?
+          @format_registry.load_default_parsers
+        end
+      end
+
+      # Get parser instance (with caching)
+      #
+      # @param parser_class [Class] Parser class
+      # @param options [Hash] Parser options
+      # @return [BaseParser] Parser instance
+      def get_parser_instance(parser_class, options)
+        cache_key = [parser_class, options.hash]
+
+        @parser_cache[cache_key] ||= parser_class.new(
+          configuration: @configuration,
+          options: options,
+        )
+      end
+
+      # Merge options with configuration defaults
+      #
+      # @param options [Hash] User-provided options
+      # @return [Hash] Merged options
+      def merge_options(options) # rubocop:disable Metrics/MethodLength
+        default_options = {}
+
+        if @configuration.transformation_options
+          default_options = {
+            validate_output: @configuration
+              .transformation_options.validate_output,
+            include_diagrams: @configuration
+              .transformation_options.include_diagrams,
+            preserve_ids: @configuration.transformation_options.preserve_ids,
+            resolve_references: @configuration
+              .transformation_options.resolve_references,
+            strict_mode: @configuration.transformation_options.strict_mode,
+          }
+        end
+
+        default_options.merge(options)
+      end
+
+      # Record transformation in history
+      #
+      # @param entry [Hash] Transformation entry
+      # @return [void]
+      def record_transformation(entry)
+        # Add timestamp and additional metadata
+        full_entry = entry.merge(
+          timestamp: Time.now,
+          engine_version: self.class.name,
+          configuration_version: @configuration.version,
+        )
+
+        @transformation_history.push(full_entry)
+        @transformation_history.shift if @transformation_history.size > 1000
+      end
+
+      # Calculate success rate
+      #
+      # @return [Float] Success rate as percentage
+      def calculate_success_rate
+        return 0.0 if @transformation_history.empty?
+
+        successful = @transformation_history.count { |t| t[:success] }
+        (successful.to_f / @transformation_history.size * 100).round(2)
+      end
+
+      # Calculate average transformation duration
+      #
+      # @return [Float] Average duration in seconds
+      def calculate_average_duration
+        return 0.0 if @transformation_history.empty?
+
+        total_duration = @transformation_history.sum { |t| t[:duration] || 0 }
+        (total_duration / @transformation_history.size).round(3)
+      end
+
+      # Validate file path
+      #
+      # @param file_path [String] File path to validate
+      # @raise [ArgumentError] if path is invalid
+      def validate_file_path!(file_path)
+        raise ArgumentError, "File path cannot be nil" if file_path.nil?
+        raise ArgumentError, "File path cannot be empty" if file_path.empty?
+
+        unless File.exist?(file_path)
+          raise ArgumentError,
+                "File does not exist: #{file_path}"
+        end
+      end
+    end
+
+    # Error class for unsupported file formats
+    class UnsupportedFormatError < Ea::Error
+      # @return [String] Path to the unsupported file
+      attr_reader :file_path
+
+      # Initialize error
+      #
+      # @param file_path [String] Path to unsupported file
+      def initialize(file_path)
+        @file_path = file_path
+        extension = File.extname(file_path)
+        super("Unsupported file format: #{extension} (file: #{file_path})")
+      end
+    end
+  end
+end

data/lib/ea/transformations.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformations
+    autoload :Configuration, "ea/transformations/configuration"
+    autoload :FormatRegistry, "ea/transformations/format_registry"
+    autoload :TransformationEngine, "ea/transformations/transformation_engine"
+
+    module Parsers
+      autoload :BaseParser, "ea/transformations/parsers/base_parser"
+      autoload :XmiParser, "ea/transformations/parsers/xmi_parser"
+      autoload :QeaParser, "ea/transformations/parsers/qea_parser"
+    end
+
+    # Resolve a class name string to a constant
+    # @param class_name [String] Fully qualified class name (e.g. "Ea::Foo::Bar")
+    # @return [Class, nil] The resolved class constant, or nil if not found
+    def self.constantize(class_name)
+      parts = class_name.split("::")
+      constant = Object
+      parts.each { |part| constant = constant.const_get(part) }
+      constant
+    rescue NameError
+      nil
+    end
+
+    class << self
+      def engine
+        @engine ||= TransformationEngine.new
+      end
+
+      def engine=(engine)
+        @engine = engine
+      end
+
+      def parse(file_path, options = {})
+        engine.parse(file_path, options)
+      end
+
+      def detect_parser(file_path)
+        engine.detect_parser(file_path)
+      end
+
+      def supported_extensions
+        engine.supported_extensions
+      end
+
+      def supports_file?(file_path)
+        engine.supports_file?(file_path)
+      end
+
+      def statistics
+        engine.statistics
+      end
+
+      def reset_statistics
+        engine.clear_history
+      end
+
+      def validate_setup
+        engine.validate_setup
+      end
+
+      def register_parser(extension, parser_class)
+        engine.register_parser(extension, parser_class)
+      end
+
+      def load_configuration(config_path)
+        engine.configuration = Configuration.load(config_path)
+      end
+
+      def configuration
+        engine.configuration
+      end
+
+      def configuration=(config)
+        engine.configuration = config
+      end
+
+      def configure
+        yield(configuration) if block_given?
+      end
+    end
+  end
+end

data/lib/ea/transformers/qea_to_xmi/association_end.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Lightweight value object returned by `Transformer#build_association_end`.
+      #
+      # Carries both the synthesised xmi:id of the `<ownedEnd>` element
+      # (used to populate `<memberEnd idref="...">` on the enclosing
+      # `<packagedElement xmi:type="uml:Association">`) and the model
+      # instance itself.
+      #
+      # Using a Struct (not a Hash) makes the contract visible at the
+      # call site: typos like `end.xmii_id` raise NoMethodError instead
+      # of silently returning nil.
+      AssociationEnd = Struct.new(:xmi_id, :model)
+    end
+  end
+end

data/lib/ea/transformers/qea_to_xmi/cardinality.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Pure-function cardinality / multiplicity parser for EA's
+      # free-text bound fields (`t_attribute.upperbound`,
+      # `t_connector.sourcecard`, etc.).
+      #
+      # EA stores cardinality as opaque strings: `1`, `0..1`, `1..*`,
+      # `*`, occasionally `unbounded` or `*-1`. The XMI wire form needs
+      # two separate child elements (`<lowerValue value="N"/>` and
+      # `<upperValue value="M"/>`) — never a range string. This module
+      # translates the EA form to a `{ lower:, upper: }` pair.
+      #
+      # Default-when-empty: EA's "no bound specified" maps to UML's
+      # unspecified multiplicity, which Sparx renders as
+      # `<lowerValue value="0"/>` and `<upperValue value="-1"/>`.
+      # Always emitting both is required for round-trip parity with
+      # real Sparx XMI (see TODO 26).
+      module Cardinality
+        # Tokens EA uses for "unbounded". Matched case-insensitively.
+        UNLIMITED_TOKENS = %w[* *-1 unbounded].freeze
+
+        # UML defaults when EA carries no explicit bound.
+        DEFAULT_LOWER = "0"
+        DEFAULT_UPPER = "-1"
+
+        module_function
+
+        # @param raw [String, nil] e.g. "1..*", "0..1", "1", "*", nil
+        # @return [Hash{Symbol=>String}] `{ lower:, upper: }` always
+        #   populated; never nil. Empty/nil input returns the UML default.
+        def parse(raw)
+          return defaults if raw.nil? || raw.to_s.strip.empty?
+
+          stripped = raw.to_s.strip
+          return parse_range(stripped) if stripped.include?("..")
+
+          # Bare unlimited token (e.g. "*") means "many" — lower bound
+          # is unspecified, which UML renders as 0..-1. Returning
+          # `{ lower: "-1", upper: "-1" }` here would be invalid:
+          # LiteralInteger cannot hold -1.
+          return defaults if UNLIMITED_TOKENS.include?(stripped.downcase)
+
+          single = normalize_bound(stripped)
+          { lower: single, upper: single }
+        end
+
+        # Normalise an upper-bound token: `*` / `unbounded` → `-1`
+        # (UML LiteralUnlimitedNatural wire form).
+        # @param raw [String, Integer, nil]
+        # @return [String]
+        def normalize_upper(raw)
+          return DEFAULT_UPPER if raw.nil?
+
+          stripped = raw.to_s.strip
+          return DEFAULT_UPPER if stripped.empty?
+
+          UNLIMITED_TOKENS.include?(stripped.downcase) ? "-1" : stripped
+        end
+
+        # Normalise a lower-bound token: empty/nil → "0" (UML default).
+        # @param raw [String, Integer, nil]
+        # @return [String]
+        def normalize_lower(raw)
+          return DEFAULT_LOWER if raw.nil?
+
+          stripped = raw.to_s.strip
+          stripped.empty? ? DEFAULT_LOWER : stripped
+        end
+
+        # ---- Internal helpers ----
+
+        def defaults
+          { lower: DEFAULT_LOWER, upper: DEFAULT_UPPER }
+        end
+
+        def parse_range(stripped)
+          lower, upper = stripped.split("..", 2)
+          { lower: normalize_bound(lower), upper: normalize_bound(upper) }
+        end
+
+        # A single bound token (one side of `..` or a bare scalar).
+        # Empty / `*` → UML unlimited (`-1`).
+        def normalize_bound(token)
+          return "-1" if token.nil?
+          return "-1" if token.strip.empty?
+
+          stripped = token.strip
+          UNLIMITED_TOKENS.include?(stripped.downcase) ? "-1" : stripped
+        end
+      end
+    end
+  end
+end

data/lib/ea/transformers/qea_to_xmi/context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Shared state passed across the walk.
+      #
+      # Wraps the {Ea::Qea::Database} and provides:
+      # - ID-derivation helpers (`xmi_id_for`, `end_xmi_id_for`) backed by
+      #   {GuidFormat}
+      # - delegated database lookups (objects, packages, attributes, etc.)
+      #
+      # The {Ea::Qea::Database} already maintains its own lookup indexes
+      # (object-by-id, connectors-by-object, attributes-by-object, etc.).
+      # This class delegates to those rather than re-indexing — single source
+      # of truth lives on the database.
+      class Context
+        attr_reader :database, :id_allocator
+
+        def initialize(database:)
+          @database = database
+          @id_allocator = IdAllocator.new
+        end
+
+        # ---- ID helpers ---------------------------------------------------
+
+        # @param record [#ea_guid]
+        # @param prefix [String] "EAID" (default) or "EAPK" for top-level packages
+        # @return [String, nil]
+        def xmi_id_for(record, prefix: "EAID")
+          return nil unless record&.ea_guid
+
+          GuidFormat.ea_guid_to_xmi_id(record.ea_guid, prefix: prefix)
+        end
+
+        # @param connector_xmi_id [String]
+        # @param side [Symbol] :source or :destination
+        # @return [String]
+        def end_xmi_id_for(connector_xmi_id, side:)
+          GuidFormat.connector_end_xmi_id(connector_xmi_id, side: side)
+        end
+
+        # ---- Database lookups --------------------------------------------
+
+        # @param ea_guid [String]
+        # @return [Ea::Qea::Models::EaObject, nil]
+        def object_by_guid(ea_guid)
+          database.find_object_by_guid(ea_guid)
+        end
+
+        # @param object_id [Integer]
+        # @return [Ea::Qea::Models::EaObject, nil]
+        def object_by_id(object_id)
+          database.find_object(object_id)
+        end
+
+        # @param package_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaPackage>]
+        def child_packages(package_id)
+          database.child_packages_for(package_id)
+        end
+
+        # @param package_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaObject>]
+        def objects_in_package(package_id)
+          database.objects_in_package(package_id)
+        end
+
+        # @param object_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaAttribute>]
+        def attributes_for(object_id)
+          database.attributes_for_object(object_id)
+        end
+
+        # @param object_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaOperation>]
+        def operations_for(object_id)
+          database.operations_for_object(object_id)
+        end
+
+        # @param operation_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaOperationParam>]
+        def params_for_operation(operation_id)
+          database.operation_params_for(operation_id)
+        end
+
+        # Connectors where the object is on either side.
+        # @param object_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaConnector>]
+        def connectors_for(object_id)
+          database.connectors_for_object(object_id)
+        end
+
+        # Connectors where this object is the start (source) — used to decide
+        # which package owns a relationship connector.
+        # @param object_id [Integer]
+        # @return [Array<Ea::Qea::Models::EaConnector>]
+        def connectors_starting_at(object_id)
+          database.connectors_for_object(object_id).select do |conn|
+            conn.start_object_id == object_id
+          end
+        end
+      end
+    end
+  end
+end