lutaml 0.9.43 → 0.10.0

data/lib/lutaml/uml_repository/queries/search_query.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require_relative "base_query"
+require_relative "../search_result"
+
+module Lutaml
+  module UmlRepository
+    module Queries
+      # Query service for search operations.
+      #
+      # Provides methods for fuzzy text search and regex pattern matching
+      # across classes, attributes, and associations in the UML model.
+      #
+      # @example Searching for text
+      #   query = SearchQuery.new(document, indexes)
+      #   results = query.search("Building")
+      #   # => { classes: [...], attributes: [...], associations: [...],
+      #   total: 15 }
+      #
+      # @example Pattern matching
+      #   results = query.search("^Urban", type: :class)
+      class SearchQuery < BaseQuery
+        # Perform a fuzzy text search across the model.
+        #
+        # Searches for the query string in class names, attribute names, and
+        # association names. Can optionally search in documentation fields.
+        # The search is case-insensitive.
+        #
+        # @param query_string [String] The text to search for
+        # @param types [Array<Symbol>] Types to search in - :class, :attribute,
+        #   :association (default: [:class, :attribute, :association])
+        # @param fields [Array<Symbol>] Fields to search in
+        # - :name, :documentation
+        #   (default: [:name])
+        # @return [Hash] Search results with keys :classes, :attributes,
+        #   :associations, :total
+        # @example
+        #   results = query.search("building")
+        #   results = query.search("urban", fields: [:name, :documentation])
+        def search( # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          query_string, types: %i[class attribute association],
+                        fields: [:name], case_sensitive: false
+        )
+          return empty_result if query_string.nil? || query_string.empty?
+
+          results = {
+            classes: [],
+            attributes: [],
+            associations: [],
+            total: 0,
+          }
+
+          # Search classes
+          if types.include?(:class)
+            results[:classes] = search_classes(
+              query_string, fields: fields, case_sensitive: case_sensitive
+            )
+          end
+
+          # Search attributes
+          if types.include?(:attribute)
+            results[:attributes] = search_attributes(
+              query_string, fields: fields, case_sensitive: case_sensitive
+            )
+          end
+
+          # Search associations
+          if types.include?(:association)
+            results[:associations] = search_associations(
+              query_string, fields: fields, case_sensitive: case_sensitive
+            )
+          end
+
+          results[:total] = results[:classes].size +
+            results[:attributes].size +
+            results[:associations].size
+
+          results
+        end
+
+        # Perform a full-text search across all text fields.
+        # Searches for the query string in all relevant text fields of classes
+        # and packages.
+        #
+        # @param query_string [String] The text to search for
+        # @param fields [Array<Symbol>] Fields to search in - :name, :
+        def full_text_search( # rubocop:disable Metrics/MethodLength
+          query_string,
+          fields: [:name], case_sensitive: false
+        )
+          results = empty_full_text_search_result
+          if query_string.nil? || query_string.empty?
+            return results
+          end
+
+          # Search classes
+          results[:classes] = search_classes(
+            query_string, fields: fields, case_sensitive: case_sensitive
+          )
+
+          # Search packages
+          results[:packages] = search_packages(
+            query_string, case_sensitive: case_sensitive
+          )
+
+          results[:total] = results[:classes].size + results[:packages].size
+
+          results
+        end
+
+        # Search for classes matching the query
+        #
+        # @param query [String] Query string
+        # @param fields [Array<Symbol>] Fields to search in
+        # @return [Array<SearchResult>] Matching search result objects
+        def search_classes( # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          query, fields: %i[name documentation],
+          case_sensitive: false
+        )
+          pattern = regex_pattern_from_query(
+            query, case_sensitive: case_sensitive
+          )
+
+          indexes[:qualified_names].filter_map do |qname, entity|
+            match_field = nil
+            qualified_name = nil
+
+            next unless entity.is_a?(Lutaml::Uml::Class)
+
+            # Check fields for match
+            fields.each do |field|
+              if entity.respond_to?(field) &&
+                  entity.send(field)&.match?(pattern)
+
+                match_field = field
+                qualified_name = qname
+              end
+            end
+
+            if match_field
+              SearchResult.new(
+                element: entity,
+                element_type: :class,
+                qualified_name: qualified_name,
+                package_path: extract_package_path(qualified_name),
+                match_field: match_field,
+              )
+            end
+          end.uniq
+        end
+
+        def search_by_stereotype(query, case_sensitive: false) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          pattern = regex_pattern_from_query(
+            query, case_sensitive: case_sensitive
+          )
+
+          matched_entities = indexes[:stereotypes]
+            .filter_map do |_stereotype, entities|
+            entities.select do |entity|
+              entity.respond_to?(:stereotype) &&
+                entity.stereotype&.match?(pattern)
+            end.uniq
+          end.uniq.flatten
+
+          matched_entities.map do |entity|
+            SearchResult.new(
+              element: entity,
+              element_type: entity.class.name.split("::").last.downcase,
+              qualified_name: "",
+              package_path: "",
+              match_field: :stereotype,
+            )
+          end
+        end
+
+        # Search for packages matching the query
+        #
+        # @param query [String] Query string
+        # @param case_sensitive [Boolean] Whether the search is case-sensitive
+        # @return [Array<Lutaml::Uml::Package>] Matching package objects
+        def search_packages(query, case_sensitive: false) # rubocop:disable Metrics/MethodLength
+          pattern = regex_pattern_from_query(
+            query, case_sensitive: case_sensitive
+          )
+
+          indexes[:package_paths].filter_map do |path_string, package|
+            if path_string.to_s.match?(pattern)
+              SearchResult.new(
+                element: package,
+                element_type: :package,
+                qualified_name: path_string,
+                package_path: path_string,
+                match_field: :package_path,
+              )
+            end
+          end
+        end
+
+        def regex_pattern_from_query(query, case_sensitive: false)
+          # handle wildcard '*' and glob patterns
+          query = query.gsub("*", ".*") unless query.include?(".*")
+
+          if case_sensitive
+            Regexp.new(query)
+          else
+            Regexp.new(query, Regexp::IGNORECASE)
+          end
+        end
+
+        # Search for attributes matching the query
+        #
+        # @param query [String] Query string
+        # @param fields [Array<Symbol>] Fields to search in
+        # @return [Array<Lutaml::Uml::Class>] Matching search result objects
+        def search_attributes(query, fields: [:name], case_sensitive: false) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          pattern = regex_pattern_from_query(
+            query, case_sensitive: case_sensitive
+          )
+
+          indexes[:qualified_names].filter_map do |class_qname, entity| # rubocop:disable Metrics/BlockLength
+            next unless entity.respond_to?(:attributes) && entity.attributes
+
+            match_field = nil
+            match_attr = nil
+            qualified_name = nil
+
+            entity.attributes.each do |attr|
+              # Check attribute for match
+              fields.each do |field|
+                if attr.respond_to?(field) &&
+                    attr.send(field)&.match?(pattern)
+
+                  match_attr = attr
+                  match_field = field
+                  qualified_name = class_qname
+                end
+              end
+            end
+
+            if match_field
+              SearchResult.new(
+                element: match_attr,
+                element_type: :attribute,
+                qualified_name: "#{qualified_name}::#{match_attr.name}",
+                package_path: extract_package_path(qualified_name),
+                match_field: match_field,
+                match_context: {
+                  "class_name" => entity&.name,
+                  "class_qname" => qualified_name,
+                },
+              )
+            end
+          end.uniq
+        end
+
+        # Get all associations in the model
+        #
+        # @return [Array<Lutaml::Uml::Association>] All association objects
+        def get_all_associations # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          all_associations = []
+
+          # Get all associations defined at document level and
+          if document.respond_to?(:associations) && document.associations
+            all_associations << document.associations
+          end
+
+          # Get all associations defined within classes
+          indexes[:qualified_names].each_value do |entity|
+            next unless entity.respond_to?(:associations) && entity.associations
+
+            all_associations << entity.associations
+          end
+
+          all_associations.flatten.uniq
+        end
+
+        # Search for associations matching the query
+        #
+        # @param query [String] Query string
+        # @param fields [Array<Symbol>] Fields to search in
+        # @return [Array<SearchResult>] Matching search result objects
+        def search_associations(query, # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          fields: %i[
+            name owner_end member_end owner_end_attribute_name
+            member_end_attribute_name documentation
+          ],
+          case_sensitive: false)
+          all_associations = get_all_associations
+          pattern = regex_pattern_from_query(
+            query, case_sensitive: case_sensitive
+          )
+
+          all_associations.filter_map do |assoc|
+            match_field = nil
+
+            fields.each do |field|
+              if assoc.respond_to?(field) && assoc.send(field)&.match?(pattern)
+                match_field = field
+              end
+            end
+
+            if match_field
+              SearchResult.new(
+                element: assoc,
+                element_type: :association,
+                qualified_name: assoc.name || "(unnamed)",
+                package_path: "",
+                match_field: match_field,
+                match_context: {
+                  "source" => assoc.owner_end,
+                  "target" => assoc.member_end,
+                },
+              )
+            end
+          end.uniq
+        end
+
+        private
+
+        # Extract package path from qualified name
+        #
+        # @param qualified_name [String] Qualified name
+        # (e.g., "pkg1::pkg2::Class")
+        # @return [String] Package path (e.g., "pkg1::pkg2")
+        def extract_package_path(qualified_name)
+          parts = qualified_name.to_s.split("::")
+          return "" if parts.size <= 1
+
+          parts[0..-2].join("::")
+        end
+
+        # Return empty search result
+        #
+        # @return [Hash] Empty result hash
+        def empty_result
+          {
+            classes: [],
+            attributes: [],
+            associations: [],
+            total: 0,
+          }
+        end
+
+        # Return empty full text search result
+        #
+        # @return [Hash] Empty result hash
+        def empty_full_text_search_result
+          {
+            classes: [],
+            packages: [],
+            total: 0,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/query_dsl/conditions/base_condition.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module UmlRepository
+    module QueryDSL
+      module Conditions
+        # Base class for query conditions
+        #
+        # Provides the interface for filtering results in query operations.
+        # All concrete condition classes must implement the {#apply} method.
+        #
+        # @abstract Subclass and override {#apply} to implement a custom
+        #   condition
+        class BaseCondition
+          # Apply the condition to filter results
+          #
+          # @param results [Array] The collection to filter
+          # @return [Array] The filtered collection
+          # @raise [NotImplementedError] if not implemented by subclass
+          def apply(results)
+            raise NotImplementedError,
+                  "#{self.class} must implement #apply"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/query_dsl/conditions/block_condition.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base_condition"
+
+module Lutaml
+  module UmlRepository
+    module QueryDSL
+      module Conditions
+        # Block-based condition for custom filtering logic
+        #
+        # Allows arbitrary filtering logic to be specified using a Ruby block.
+        # The block receives each object and should return true/false.
+        #
+        # @example Filter by attribute count
+        #   condition = BlockCondition.new { |c| c.attributes.size > 10 }
+        #   filtered = condition.apply(classes)
+        #
+        # @example Complex filtering
+        #   condition = BlockCondition.new do |c|
+        #     c.attributes.any? && c.associations.empty?
+        #   end
+        #   filtered = condition.apply(classes)
+        class BlockCondition < BaseCondition
+          # Initialize with a filtering block
+          #
+          # @param block [Proc] The block to use for filtering
+          # @raise [ArgumentError] if no block provided
+          def initialize(&block)
+            super()
+            raise ArgumentError, "Block required" unless block
+
+            @block = block
+          end
+
+          # Apply block-based filtering to results
+          #
+          # @param results [Array] The collection to filter
+          # @return [Array] Objects for which block returns true
+          def apply(results)
+            results.select(&@block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/query_dsl/conditions/hash_condition.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "base_condition"
+
+module Lutaml
+  module UmlRepository
+    module QueryDSL
+      module Conditions
+        # Hash-based condition for filtering query results
+        #
+        # Filters results based on attribute-value pairs specified in a hash.
+        # All conditions must match for an object to be included in results.
+        #
+        # @example Filter by stereotype
+        #   condition = HashCondition.new(stereotype: 'featureType')
+        #   filtered = condition.apply(classes)
+        #
+        # @example Multiple conditions
+        #   condition = HashCondition.new(
+        #     stereotype: 'featureType',
+        #     is_abstract: false
+        #   )
+        #   filtered = condition.apply(classes)
+        class HashCondition < BaseCondition
+          # Initialize with hash conditions
+          #
+          # @param conditions [Hash] Attribute-value pairs to match
+          def initialize(conditions)
+            super()
+            @conditions = conditions
+          end
+
+          # Apply hash-based filtering to results
+          #
+          # @param results [Array] The collection to filter
+          # @return [Array] Objects matching all conditions
+          def apply(results)
+            results.select do |obj|
+              @conditions.all? do |key, value|
+                matches_condition?(obj, key, value)
+              end
+            end
+          end
+
+          private
+
+          # Check if object matches a single condition
+          #
+          # @param obj [Object] The object to check
+          # @param key [Symbol, String] The attribute name
+          # @param value [Object] The expected value
+          # @return [Boolean] true if condition matches
+          def matches_condition?(obj, key, value)
+            return false unless obj.respond_to?(key)
+
+            actual_value = obj.send(key)
+            compare_values(actual_value, value)
+          end
+
+          # Compare actual and expected values
+          #
+          # @param actual [Object] The actual value from object
+          # @param expected [Object] The expected value
+          # @return [Boolean] true if values match
+          def compare_values(actual, expected) # rubocop:disable Metrics/MethodLength
+            case expected
+            when Regexp
+              expected.match?(actual.to_s)
+            when Proc
+              expected.call(actual)
+            else
+              # Handle array attributes (e.g., stereotype)
+              if actual.is_a?(Array)
+                actual.include?(expected)
+              else
+                actual == expected
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/query_dsl/conditions/package_condition.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "base_condition"
+require_relative "../../../uml/package_path"
+
+module Lutaml
+  module UmlRepository
+    module QueryDSL
+      module Conditions
+        # Package-based condition for filtering by package membership
+        #
+        # Filters results based on package path, with support for
+        # recursive (descendant) matching.
+        #
+        # @example Filter by exact package
+        #   condition = PackageCondition.new(
+        #   "ModelRoot::i-UR", recursive: false)
+        #   filtered = condition.apply(classes)
+        #
+        # @example Filter by package and descendants
+        #   condition = PackageCondition.new("ModelRoot::i-UR", recursive: true)
+        #   filtered = condition.apply(classes)
+        class PackageCondition < BaseCondition
+          # Initialize with package path and recursion setting
+          #
+          # @param package_path [String, PackagePath]
+          # The package path to filter by
+          # @param recursive [Boolean] Whether to include descendants
+          def initialize(package_path, recursive: false)
+            super()
+            @package_path = if package_path.is_a?(PackagePath)
+                              package_path
+                            else
+                              PackagePath.new(package_path)
+                            end
+            @recursive = recursive
+          end
+
+          # Apply package-based filtering to results
+          #
+          # @param results [Array] The collection to filter
+          # @return [Array] Objects in the specified package
+          def apply(results)
+            results.select do |obj|
+              matches_package?(obj)
+            end
+          end
+
+          private
+
+          # Check if object matches package condition
+          #
+          # @param obj [Object] The object to check
+          # @return [Boolean] true if object is in target package
+          def matches_package?(obj)
+            obj_package_path = extract_package_path(obj)
+            return false unless obj_package_path
+
+            if @recursive
+              obj_package_path.starts_with?(@package_path)
+            else
+              obj_package_path == @package_path
+            end
+          end
+
+          # Extract package path from object
+          #
+          # @param obj [Object] The object to extract path from
+          # @return [PackagePath, nil] The object's package path
+          def extract_package_path(obj)
+            return nil unless obj.respond_to?(:package_path)
+
+            path = obj.package_path
+            return nil unless path
+
+            path.is_a?(PackagePath) ? path : PackagePath.new(path)
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/query_dsl/order.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module UmlRepository
+    module QueryDSL
+      # Order specification for sorting query results
+      #
+      # Sorts results based on a specified field and direction.
+      # Handles nil values by treating them as empty strings for comparison.
+      #
+      # @example Ascending order
+      #   order = Order.new(:name, :asc)
+      #   sorted = order.apply(classes)
+      #
+      # @example Descending order
+      #   order = Order.new(:name, :desc)
+      #   sorted = order.apply(classes)
+      class Order
+        VALID_DIRECTIONS = %i[asc desc].freeze
+
+        attr_reader :field, :direction
+
+        # Initialize with field and direction
+        #
+        # @param field [Symbol, String] The field to sort by
+        # @param direction [Symbol] The sort direction (:asc or :desc)
+        # @raise [ArgumentError] if direction is invalid
+        def initialize(field, direction = :asc)
+          @field = field.to_sym
+          @direction = validate_direction(direction)
+        end
+
+        # Apply ordering to results
+        #
+        # @param results [Array] The collection to sort
+        # @return [Array] The sorted collection
+        def apply(results)
+          sorted = results.sort_by do |obj|
+            extract_sort_value(obj)
+          end
+
+          @direction == :desc ? sorted.reverse : sorted
+        end
+
+        private
+
+        # Validate sort direction
+        #
+        # @param direction [Symbol] The direction to validate
+        # @return [Symbol] The validated direction
+        # @raise [ArgumentError] if direction is invalid
+        def validate_direction(direction)
+          dir = direction.to_sym
+          unless VALID_DIRECTIONS.include?(dir)
+            raise ArgumentError,
+                  "Invalid direction: #{direction}. " \
+                  "Must be one of #{VALID_DIRECTIONS.join(', ')}"
+          end
+          dir
+        end
+
+        # Extract sort value from object
+        #
+        # @param obj [Object] The object to extract value from
+        # @return [Object] The value to use for sorting
+        def extract_sort_value(obj)
+          return "" unless obj.respond_to?(@field)
+
+          value = obj.send(@field)
+          normalize_value(value)
+        end
+
+        # Normalize value for sorting
+        #
+        # @param value [Object] The value to normalize
+        # @return [Object] The normalized value
+        def normalize_value(value)
+          case value
+          when nil
+            ""
+          when String
+            value.downcase
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end