lutaml 0.9.43 → 0.10.0

data/lib/lutaml/qea/verification/comparison_result.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Qea
+    module Verification
+      # Holds comparison results between XMI and QEA documents
+      class ComparisonResult
+        attr_reader :matches, :differences, :xmi_only, :qea_only,
+                    :property_differences
+
+        def initialize # rubocop:disable Metrics/MethodLength
+          @matches = {
+            packages: 0,
+            classes: 0,
+            enums: 0,
+            data_types: 0,
+            associations: 0,
+            attributes: 0,
+            operations: 0,
+          }
+          @differences = []
+          @xmi_only = {
+            packages: [],
+            classes: [],
+            enums: [],
+            data_types: [],
+            associations: [],
+          }
+          @qea_only = {
+            packages: [],
+            classes: [],
+            enums: [],
+            data_types: [],
+            associations: [],
+          }
+          @property_differences = []
+        end
+
+        # Record matched elements
+        #
+        # @param type [Symbol] Element type (:packages, :classes, etc.)
+        # @param count [Integer] Number of matches
+        def add_matches(type, count)
+          @matches[type] = count
+        end
+
+        # Record XMI-only elements
+        #
+        # @param type [Symbol] Element type
+        # @param elements [Array<String>] Element names/paths
+        def add_xmi_only(type, elements)
+          @xmi_only[type] = elements
+        end
+
+        # Record QEA-only elements
+        #
+        # @param type [Symbol] Element type
+        # @param elements [Array<String>] Element names/paths
+        def add_qea_only(type, elements)
+          @qea_only[type] = elements
+        end
+
+        # Record a difference
+        #
+        # @param description [String] Difference description
+        def add_difference(description)
+          @differences << description
+        end
+
+        # Record property-level difference
+        #
+        # @param element_type [Symbol] Element type
+        # @param element_name [String] Element name
+        # @param differences [Array<String>] List of property differences
+        def add_property_difference(element_type, element_name, differences)
+          @property_differences << {
+            type: element_type,
+            name: element_name,
+            differences: differences,
+          }
+        end
+
+        # Check if documents are equivalent
+        # QEA is considered equivalent if it has >= information compared to XMI
+        #
+        # @return [Boolean] True if equivalent
+        def equivalent?
+          # No critical XMI-only elements (some are acceptable)
+          critical_xmi_only = xmi_only[:classes].any? ||
+            xmi_only[:packages].any?
+
+          # No property differences that indicate information loss
+          critical_property_diffs = property_differences.any? do |diff|
+            diff[:differences].any? { |d| d.include?("QEA has fewer") }
+          end
+
+          !critical_xmi_only && !critical_property_diffs
+        end
+
+        # Generate human-readable summary
+        #
+        # @return [String] Summary text
+        def summary # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          lines = []
+          lines << "=== Verification Summary ==="
+          lines << ""
+
+          # Matches
+          lines << "Matched Elements:"
+          matches.each do |type, count|
+            next if count.zero?
+
+            lines << "  ✓ #{type.to_s.capitalize}: #{count}"
+          end
+          lines << ""
+
+          # XMI-only elements
+          if xmi_only.values.any?(&:any?)
+            lines << "XMI-Only Elements (missing in QEA):"
+            xmi_only.each do |type, elements|
+              next if elements.empty?
+
+              lines << "  ✗ #{type.to_s.capitalize}: #{elements.size}"
+              elements.first(5).each do |elem|
+                lines << "    - #{elem}"
+              end
+              if elements.size > 5
+                lines << "    ... and #{elements.size - 5} more"
+              end
+            end
+            lines << ""
+          end
+
+          # QEA-only elements (acceptable, shows QEA richness)
+          if qea_only.values.any?(&:any?)
+            lines << "QEA-Only Elements (additional in QEA - acceptable):"
+            qea_only.each do |type, elements|
+              next if elements.empty?
+
+              lines << "  + #{type.to_s.capitalize}: #{elements.size}"
+            end
+            lines << ""
+          end
+
+          # Property differences
+          if property_differences.any?
+            lines << "Property Differences:"
+            property_differences.first(10).each do |diff|
+              lines << "  #{diff[:type]}: #{diff[:name]}"
+              diff[:differences].each do |d|
+                lines << "    - #{d}"
+              end
+            end
+            if property_differences.size > 10
+              lines << "  ... and #{property_differences.size - 10} more"
+            end
+            lines << ""
+          end
+
+          # Result
+          lines << "Result: " \
+                   "#{equivalent? ? '✓ EQUIVALENT' : '✗ NOT EQUIVALENT'}"
+          lines << ""
+
+          lines << if equivalent?
+                     "QEA contains all XMI information (possibly more)."
+                   else
+                     "Information loss detected - " \
+                       "QEA missing critical elements."
+                   end
+
+          lines.join("\n")
+        end
+
+        # Generate detailed report
+        #
+        # @return [Hash] Detailed report data
+        def to_report
+          {
+            equivalent: equivalent?,
+            matches: matches,
+            xmi_only: xmi_only,
+            qea_only: qea_only,
+            property_differences: property_differences,
+            summary: summary,
+          }
+        end
+
+        # Generate statistics
+        #
+        # @return [Hash] Statistics about the comparison
+        def statistics
+          {
+            total_matches: matches.values.sum,
+            total_xmi_only: xmi_only.values.sum(&:size),
+            total_qea_only: qea_only.values.sum(&:size),
+            total_property_diffs: property_differences.size,
+            equivalent: equivalent?,
+          }
+        end
+
+        # Check if there are any issues
+        #
+        # @return [Boolean] True if there are issues
+        def has_issues?
+          !equivalent?
+        end
+
+        # Get critical issues (information loss)
+        #
+        # @return [Array<String>] List of critical issues
+        def critical_issues # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          issues = []
+
+          # Missing packages
+          if xmi_only[:packages].any?
+            issues << "Missing #{xmi_only[:packages].size} packages in QEA"
+          end
+
+          # Missing classes
+          if xmi_only[:classes].any?
+            issues << "Missing #{xmi_only[:classes].size} classes in QEA"
+          end
+
+          # Property differences with information loss
+          property_differences.each do |diff|
+            diff[:differences].each do |d|
+              next unless d.include?("QEA has fewer")
+
+              issues << "#{diff[:name]}: #{d}"
+            end
+          end
+
+          issues
+        end
+
+        # Get acceptable differences (QEA has more)
+        #
+        # @return [Array<String>] List of acceptable differences
+        def acceptable_differences # rubocop:disable Metrics/MethodLength
+          acceptable = []
+
+          # QEA-only elements
+          qea_only.each do |type, elements|
+            next if elements.empty?
+
+            acceptable << "QEA has #{elements.size} additional #{type}"
+          end
+
+          # Property differences where QEA has more
+          property_differences.each do |diff|
+            diff[:differences].each do |d|
+              next unless d.include?("QEA has more")
+
+              acceptable << "#{diff[:name]}: #{d}"
+            end
+          end
+
+          acceptable
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/qea/verification/document_normalizer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Qea
+    module Verification
+      # Normalizes UML documents for comparison by removing XMI IDs,
+      # sorting collections, and normalizing strings
+      class DocumentNormalizer
+        # Normalize a document for comparison
+        #
+        # @param document [Lutaml::Uml::Document] The document to normalize
+        # @return [Lutaml::Uml::Document] A normalized copy
+        def normalize(document)
+          normalized = deep_copy(document)
+          remove_xmi_ids(normalized)
+          sort_collections(normalized)
+          normalize_strings_in_document(normalized)
+          normalized
+        end
+
+        # Remove all XMI IDs from document
+        #
+        # @param document [Lutaml::Uml::Document] The document to process
+        # @return [void]
+        def remove_xmi_ids(document) # rubocop:disable Metrics/AbcSize
+          # Remove XMI IDs from packages recursively
+          process_packages(document.packages) if document.packages
+
+          # Remove XMI IDs from classes
+          process_classes(document.classes) if document.classes
+
+          # Remove XMI IDs from associations
+          process_associations(document.associations) if document.associations
+
+          # Remove XMI IDs from enums
+          process_enums(document.enums) if document.enums
+
+          # Remove XMI IDs from data types
+          process_data_types(document.data_types) if document.data_types
+        end
+
+        # Sort collections in document for consistent comparison
+        #
+        # @param document [Lutaml::Uml::Document] The document to process
+        # @return [void]
+        def sort_collections(document) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          # Sort top-level collections by name
+          document.packages&.sort_by! { |p| p.name || "" }
+          document.classes&.sort_by! { |c| c.name || "" }
+          document.enums&.sort_by! { |e| e.name || "" }
+          document.data_types&.sort_by! { |dt| dt.name || "" }
+          document.associations&.sort_by! do |a|
+            "#{a.owner_end}#{a.member_end}"
+          end
+
+          # Sort nested collections recursively
+          sort_package_collections(document.packages) if document.packages
+          sort_class_collections(document.classes) if document.classes
+        end
+
+        # Normalize strings (trim whitespace, normalize case for comparison)
+        #
+        # @param text [String, nil] The text to normalize
+        # @return [String, nil] Normalized text
+        def normalize_string(text)
+          return nil if text.nil?
+          return text unless text.is_a?(String)
+
+          text.strip
+        end
+
+        private
+
+        # Deep copy document to avoid modifying original
+        def deep_copy(document)
+          # Use YAML serialization for deep copy
+          yaml = document.to_yaml
+          Lutaml::Uml::Document.from_yaml(yaml)
+        end
+
+        # Process packages recursively to remove XMI IDs
+        def process_packages(packages) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+          packages.each do |package|
+            package.xmi_id = nil if package.respond_to?(:xmi_id=)
+            process_classes(package.classes) if package.classes
+            process_enums(package.enums) if package.enums
+            process_data_types(package.data_types) if package.data_types
+            process_packages(package.packages) if package.packages
+          end
+        end
+
+        # Process classes to remove XMI IDs
+        def process_classes(classes) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          classes.each do |klass|
+            klass.xmi_id = nil if klass.respond_to?(:xmi_id=)
+
+            # Remove XMI IDs from attributes
+            klass.attributes&.each do |attr|
+              attr.xmi_id = nil if attr.respond_to?(:xmi_id=)
+            end
+
+            # Remove XMI IDs from operations
+            klass.operations&.each do |op|
+              op.xmi_id = nil if op.respond_to?(:xmi_id=)
+              op.parameters&.each do |param|
+                param.xmi_id = nil if param.respond_to?(:xmi_id=)
+              end
+            end
+
+            # Process nested classes
+            if klass.respond_to?(:classes) && klass.classes
+              process_classes(klass.classes)
+            end
+          end
+        end
+
+        # Process associations to remove XMI IDs
+        def process_associations(associations)
+          associations.each do |assoc|
+            assoc.xmi_id = nil if assoc.respond_to?(:xmi_id=)
+            if assoc.respond_to?(:owner_end_xmi_id=)
+              assoc.owner_end_xmi_id = nil
+            end
+            if assoc.respond_to?(:member_end_xmi_id=)
+              assoc.member_end_xmi_id = nil
+            end
+          end
+        end
+
+        # Process enums to remove XMI IDs
+        def process_enums(enums)
+          enums.each do |enum|
+            enum.xmi_id = nil if enum.respond_to?(:xmi_id=)
+          end
+        end
+
+        # Process data types to remove XMI IDs
+        def process_data_types(data_types)
+          data_types.each do |dt|
+            dt.xmi_id = nil if dt.respond_to?(:xmi_id=)
+          end
+        end
+
+        # Sort collections within packages
+        def sort_package_collections(packages) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          packages.each do |package|
+            package.classes&.sort_by! { |c| c.name || "" }
+            package.enums&.sort_by! { |e| e.name || "" }
+            package.data_types&.sort_by! { |dt| dt.name || "" }
+            package.packages&.sort_by! { |p| p.name || "" }
+
+            sort_class_collections(package.classes) if package.classes
+            sort_package_collections(package.packages) if package.packages
+          end
+        end
+
+        # Sort collections within classes
+        def sort_class_collections(classes) # rubocop:disable Metrics/CyclomaticComplexity
+          classes.each do |klass|
+            klass.attributes&.sort_by! { |a| a.name || "" }
+            klass.operations&.sort_by! { |o| o.name || "" }
+            klass.associations&.sort_by! do |a|
+              "#{a.owner_end}#{a.member_end}"
+            end
+          end
+        end
+
+        # Normalize strings throughout document
+        def normalize_strings_in_document(document)
+          # This is a placeholder for string normalization
+          # Can be extended to normalize strings throughout the document
+          # For now, normalization happens during comparison
+        end
+      end
+    end
+  end
+end