lcp 0.1.0

data/lib/lcp_ruby/search/filter_metadata_builder.rb

@@ -0,0 +1,409 @@
+module LcpRuby
+  module Search
+    class FilterMetadataBuilder
+      EXCLUDED_FIELD_NAMES = %w[id created_at updated_at].freeze
+      EXCLUDED_FIELD_TYPES = %w[attachment rich_text json].freeze
+
+      attr_reader :presenter_definition, :model_definition, :evaluator
+
+      def initialize(presenter_definition, model_definition, evaluator)
+        @presenter_definition = presenter_definition
+        @model_definition = model_definition
+        @evaluator = evaluator
+      end
+
+      def build
+        {
+          fields: build_fields,
+          operator_labels: build_operator_labels,
+          no_value_operators: OperatorRegistry::NO_VALUE_OPERATORS.map(&:to_s),
+          multi_value_operators: OperatorRegistry::MULTI_VALUE_OPERATORS.map(&:to_s),
+          range_operators: OperatorRegistry::RANGE_OPERATORS.map(&:to_s),
+          parameterized_operators: OperatorRegistry::PARAMETERIZED_OPERATORS.map(&:to_s),
+          presets: advanced_filter_config["presets"] || [],
+          scopes: build_parameterized_scopes,
+          config: {
+            max_conditions: advanced_filter_config["max_conditions"] || 10,
+            default_combinator: advanced_filter_config["default_combinator"] || "and",
+            allow_or_groups: advanced_filter_config.fetch("allow_or_groups", true),
+            query_language: advanced_filter_config.fetch("query_language", false),
+            max_nesting_depth: advanced_filter_config["max_nesting_depth"] || 2
+          }
+        }
+      end
+
+      private
+
+      def advanced_filter_config
+        @advanced_filter_config ||= presenter_definition.advanced_filter_config
+      end
+
+      def max_association_depth
+        advanced_filter_config["max_association_depth"] || 1
+      end
+
+      def field_options
+        advanced_filter_config["field_options"] || {}
+      end
+
+      def build_fields
+        if filterable_fields_configured?
+          build_explicit_fields
+        elsif filterable_fields_except_configured?
+          build_auto_detected_fields_with_exclusions
+        else
+          build_auto_detected_fields
+        end
+      end
+
+      def filterable_fields_configured?
+        config = advanced_filter_config["filterable_fields"]
+        config.is_a?(Array) && config.any?
+      end
+
+      def filterable_fields_except_configured?
+        config = advanced_filter_config["filterable_fields_except"]
+        config.is_a?(Array) && config.any?
+      end
+
+      def build_explicit_fields
+        fields = advanced_filter_config["filterable_fields"].filter_map do |field_path|
+          if field_path.include?(".")
+            build_association_field(field_path)
+          else
+            build_direct_field(field_path)
+          end
+        end
+
+        # Custom fields (filterable + active + readable)
+        fields.concat(build_custom_field_entries)
+
+        fields
+      end
+
+      def build_auto_detected_fields
+        fields = []
+
+        # Direct fields (excluding system fields, attachments, computed)
+        model_definition.fields.each do |field_def|
+          next unless field_filterable?(field_def)
+          next unless evaluator.field_readable?(field_def.name)
+
+          fields << field_descriptor(field_def.name, field_def, nil)
+        end
+
+        # Association fields (recursive traversal)
+        traverse_associations(model_definition, [], fields, depth: 1, visited: Set.new([ model_definition.name ]), parent_model_name: nil)
+
+        # Custom fields (filterable + active + readable)
+        fields.concat(build_custom_field_entries)
+
+        fields
+      end
+
+      def build_auto_detected_fields_with_exclusions
+        exclusions = Set.new(advanced_filter_config["filterable_fields_except"].map(&:to_s))
+        fields = build_auto_detected_fields
+
+        fields.reject! { |f| exclusion_matches?(f[:name], exclusions) }
+
+        fields
+      end
+
+      # Check if a field name matches any exclusion rule
+      def exclusion_matches?(field_name, exclusions)
+        return true if exclusions.include?(field_name)
+
+        # Check if a parent association is excluded entirely
+        parts = field_name.to_s.split(".")
+        parts.size.times do |i|
+          prefix = parts[0..i].join(".")
+          return true if exclusions.include?(prefix)
+        end
+
+        false
+      end
+
+      def traverse_associations(current_model_def, path_parts, fields, depth:, visited:, parent_model_name:)
+        return if depth > max_association_depth
+
+        current_model_def.associations.each do |assoc|
+          next unless assoc.traversable?
+
+          # Skip inverse association (the one pointing back to the model we came from)
+          if parent_model_name
+            next if assoc.target_model == parent_model_name
+          end
+
+          # Cycle prevention: don't revisit models already in the current path
+          next if visited.include?(assoc.target_model)
+
+          # FK readability for belongs_to at root level
+          if assoc.belongs_to? && path_parts.empty?
+            next unless evaluator.field_readable?(assoc.foreign_key)
+          end
+
+          target_def = load_model_definition(assoc.target_model)
+          next unless target_def
+
+          assoc_path = path_parts + [ assoc.name ]
+          group_label = assoc_path.map { |p| p.to_s.humanize }.join(" > ")
+
+          # Add filterable fields from this association
+          target_def.fields.each do |field_def|
+            next unless field_filterable?(field_def)
+
+            # Skip the FK field that points back to the parent model (inverse FK exclusion)
+            if parent_model_name
+              inverse_assoc = target_def.associations.find { |a| a.belongs_to? && a.target_model == parent_model_name }
+              next if inverse_assoc && field_def.name == inverse_assoc.foreign_key
+            end
+
+            dot_path = (assoc_path + [ field_def.name ]).join(".")
+            fields << field_descriptor(dot_path, field_def, group_label)
+          end
+
+          # Recurse into sub-associations
+          new_visited = visited + [ assoc.target_model ]
+          traverse_associations(target_def, assoc_path, fields, depth: depth + 1, visited: new_visited, parent_model_name: current_model_def.name)
+        end
+      end
+
+      def build_direct_field(field_name)
+        field_def = model_definition.field(field_name)
+        return unless field_def
+        return unless evaluator.field_readable?(field_name)
+
+        field_descriptor(field_name, field_def, nil)
+      end
+
+      def build_association_field(dot_path)
+        parts = dot_path.split(".")
+        return if parts.length > max_association_depth + 1
+
+        current_model_def = model_definition
+        group_parts = []
+
+        # Traverse association chain (all parts except the last are associations)
+        parts[0..-2].each do |assoc_name|
+          assoc = current_model_def.associations.find { |a| a.name == assoc_name }
+          return unless assoc
+          return unless assoc.traversable?
+
+          # Check FK readability for belongs_to at each level
+          if assoc.belongs_to? && current_model_def == model_definition
+            return unless evaluator.field_readable?(assoc.foreign_key)
+          end
+
+          group_parts << assoc.name.humanize
+
+          target_def = load_model_definition(assoc.target_model)
+          return unless target_def
+          current_model_def = target_def
+        end
+
+        # Last part is the field name
+        target_field_name = parts.last
+        target_field_def = current_model_def.field(target_field_name)
+        return unless target_field_def
+
+        field_descriptor(dot_path, target_field_def, group_parts.join(" > "))
+      end
+
+      def field_descriptor(name, field_def, group)
+        base_type = field_def.resolved_base_type
+        operators = resolve_operators(name, base_type)
+
+        # Resolve label via i18n: for dot-path fields (e.g. "employee.full_name"),
+        # resolve against the association's target model.
+        label_model = if name.include?(".")
+          parts = name.split(".")
+          assoc_chain_model = model_definition
+          parts[0..-2].each do |assoc_name|
+            assoc = assoc_chain_model.associations.find { |a| a.name == assoc_name }
+            assoc_chain_model = load_model_definition(assoc.target_model) if assoc
+          end
+          assoc_chain_model&.name
+        else
+          model_definition.name
+        end
+
+        descriptor = {
+          name: name,
+          label: field_def.resolved_label(model_name: label_model),
+          type: base_type,
+          group: group,
+          operators: operators.map(&:to_s)
+        }
+
+        if field_def.enum?
+          descriptor[:enum_values] = format_enum_values(field_def.enum_values)
+        end
+
+        descriptor
+      end
+
+      def resolve_operators(field_name, base_type)
+        # Check for field-specific operator overrides
+        # Strip association prefix to match field_options keys
+        simple_name = field_name.split(".").last
+        override = field_options.dig(field_name, "operators") || field_options.dig(simple_name, "operators")
+
+        operators = if override
+          override.map(&:to_sym)
+        else
+          OperatorRegistry.operators_for(base_type)
+        end
+
+        # For API-backed models, intersect with data source supported operators
+        api_ops = model_definition.supported_filter_operators
+        if api_ops
+          supported = api_ops.map(&:to_sym)
+          operators = operators.select { |op| supported.include?(op) }
+        end
+
+        operators
+      end
+
+      def build_operator_labels
+        OperatorRegistry::ALL_OPERATORS.each_with_object({}) do |op, hash|
+          hash[op.to_s] = OperatorRegistry.label_for(op)
+        end
+      end
+
+      def build_custom_field_entries
+        return [] unless model_definition.custom_fields_enabled?
+        return [] unless CustomFields::Registry.available?
+
+        definitions = CustomFields::Registry.for_model(model_definition.name)
+        custom_fields_group = I18n.t("lcp_ruby.advanced_filter.field_groups.custom_fields", default: "Custom Fields")
+
+        definitions.filter_map do |defn|
+          next unless defn.active
+          next unless defn.respond_to?(:filterable) && defn.filterable
+          next unless evaluator.field_readable?(defn.field_name)
+
+          custom_field_descriptor(defn, custom_fields_group)
+        end
+      end
+
+      def custom_field_descriptor(defn, group)
+        base_type = defn.custom_type.to_s
+        operator_type = OperatorRegistry::OPERATORS_BY_TYPE.key?(base_type.to_sym) ? base_type.to_sym : :string
+        operators = OperatorRegistry.operators_for(operator_type)
+
+        descriptor = {
+          name: "cf[#{defn.field_name}]",
+          label: defn.label,
+          type: base_type,
+          group: group,
+          operators: operators.map(&:to_s),
+          custom_field: true
+        }
+
+        if base_type == "enum" && defn.enum_values.present?
+          descriptor[:enum_values] = format_enum_values(defn.enum_values)
+        end
+
+        descriptor
+      end
+
+      def format_enum_values(raw_values)
+        Array(raw_values).map do |ev|
+          if ev.is_a?(Hash)
+            value = (ev["value"] || ev[:value]).to_s
+            label = (ev["label"] || ev[:label] || value.humanize).to_s
+            [ value, label ]
+          else
+            [ ev.to_s, ev.to_s.humanize ]
+          end
+        end
+      end
+
+      def field_filterable?(field_def)
+        !EXCLUDED_FIELD_NAMES.include?(field_def.name) &&
+          !EXCLUDED_FIELD_TYPES.include?(field_def.resolved_base_type) &&
+          !field_def.computed?
+      end
+
+      def load_model_definition(model_name)
+        LcpRuby.loader.model_definition(model_name)
+      rescue LcpRuby::MetadataError => e
+        raise unless Rails.env.production?
+        LcpRuby.record_error(e, subsystem: "filter_builder", model: model_name)
+        nil
+      end
+
+      def build_parameterized_scopes
+        model_definition.parameterized_scopes.map do |scope_config|
+          name = scope_config["name"]
+          {
+            name: name,
+            label: I18n.t("lcp_ruby.scopes.#{name}", default: name.to_s.humanize),
+            parameters: build_scope_parameters(scope_config["parameters"] || [])
+          }
+        end
+      end
+
+      def build_scope_parameters(params_config)
+        params_config.map do |param|
+          param = param.transform_keys(&:to_s) if param.is_a?(Hash)
+          entry = {
+            name: param["name"],
+            label: I18n.t(
+              "lcp_ruby.scope_params.#{param['name']}",
+              default: param["name"].to_s.humanize
+            ),
+            type: param["type"],
+            required: param["required"] == true,
+            default: param["default"]
+          }
+
+          entry[:min] = param["min"] if param.key?("min")
+          entry[:max] = param["max"] if param.key?("max")
+          entry[:step] = param["step"] if param.key?("step")
+          entry[:placeholder] = param["placeholder"] if param.key?("placeholder")
+
+          if param["type"] == "enum" && param["values"]
+            entry[:values] = Array(param["values"]).map do |v|
+              [ v.to_s, v.to_s.humanize ]
+            end
+          end
+
+          if param["type"] == "model_select" && param["model"]
+            entry[:model] = param["model"]
+            entry[:display_field] = param["display_field"]
+            entry[:options] = load_model_select_options(param)
+          end
+
+          entry
+        end
+      end
+
+      def load_model_select_options(param)
+        model_name = param["model"]
+        model_class = LcpRuby.registry.model_for(model_name)
+        return [] unless model_class
+
+        model_def = load_model_definition(model_name)
+        return [] unless model_def
+
+        display_field = param["display_field"] || model_def.label_method
+        display_field = display_field.to_sym
+
+        query = model_class.all
+        filter_scope = param["filter_scope"]
+        query = query.send(filter_scope) if filter_scope && model_class.respond_to?(filter_scope)
+
+        query.limit(200).map do |record|
+          label = record.respond_to?(display_field) ? record.send(display_field).to_s : record.to_s
+          { value: record.id, label: label }
+        end
+      rescue StandardError => e
+        raise unless Rails.env.production?
+        LcpRuby.record_error(e, subsystem: "filter_builder", model: model_name, operation: "model_select_options")
+        []
+      end
+    end
+  end
+end

data/lib/lcp_ruby/search/filter_param_builder.rb

@@ -0,0 +1,177 @@
+module LcpRuby
+  module Search
+    class FilterParamBuilder
+      # Converts a condition tree into Ransack-compatible params hash.
+      #
+      # Supports both recursive format:
+      #   { "combinator" => "and", "children" => [leaf_or_group, ...] }
+      #
+      # and legacy format:
+      #   { "combinator" => "and", "conditions" => [...], "groups" => [...] }
+      #
+      # Output: { ransack: { ... }, custom_fields: { ... }, scopes: { ... } }
+      def self.build(condition_tree)
+        return {} if condition_tree.blank?
+
+        # Handle bare leaf condition (promoted from single-child group)
+        if condition_tree.key?("field") && !condition_tree.key?("children")
+          condition_tree = { "combinator" => "and", "children" => [ condition_tree ] }
+        end
+
+        # Detect legacy format and delegate
+        if condition_tree.key?("conditions") && !condition_tree.key?("children")
+          return build_legacy(condition_tree)
+        end
+
+        result = {}
+        custom_field_params = {}
+        scope_params = {}
+        group_counter = { value: 0 }
+
+        # Set root combinator when it's not the default "and"
+        root_combinator = condition_tree["combinator"] || "and"
+        result["m"] = root_combinator if root_combinator != "and"
+
+        children = condition_tree["children"] || []
+        children.each do |child|
+          if child.key?("field")
+            # Leaf condition at top level
+            extract_condition(child, result, custom_field_params, scope_params)
+          else
+            # Nested group — emit as Ransack group
+            result["g"] ||= {}
+            idx = group_counter[:value].to_s
+            group_counter[:value] += 1
+            group_params = build_ransack_group(child, group_counter, custom_field_params, scope_params)
+            result["g"][idx] = group_params if group_params.present?
+          end
+        end
+
+        { ransack: result, custom_fields: custom_field_params, scopes: scope_params }
+      end
+
+      # Converts association dot-path to Ransack underscore format.
+      # e.g., "company.name" -> "company_name"
+      def self.dot_path_to_ransack(path)
+        path.tr(".", "_")
+      end
+
+      private_class_method def self.extract_condition(condition, result, custom_field_params, scope_params = {})
+        field = condition["field"]
+        operator = condition["operator"]&.to_sym
+        value = condition["value"]
+
+        if operator == :scope && field&.start_with?("@")
+          # Scope condition — extract to scope_params
+          scope_name = field.delete_prefix("@")
+          scope_params[scope_name] = (condition["params"] || {}).transform_keys(&:to_s)
+        elsif field&.start_with?("cf[")
+          custom_field_params[field] = { operator: operator, value: value }
+        else
+          merge_condition(result, field, operator, value)
+        end
+      end
+
+      private_class_method def self.build_ransack_group(node, group_counter, custom_field_params, scope_params = {})
+        combinator = node["combinator"] || "and"
+        result = { "m" => combinator }
+        children = node["children"] || []
+
+        children.each do |child|
+          if child.key?("field")
+            extract_condition(child, result, custom_field_params, scope_params)
+          else
+            # Nested sub-group
+            result["g"] ||= {}
+            idx = group_counter[:value].to_s
+            group_counter[:value] += 1
+            sub_params = build_ransack_group(child, group_counter, custom_field_params, scope_params)
+            result["g"][idx] = sub_params if sub_params.present?
+          end
+        end
+
+        result
+      end
+
+      private_class_method def self.merge_condition(result, field, operator, value)
+        return if field.blank? || operator.blank?
+
+        ransack_field = dot_path_to_ransack(field)
+
+        if OperatorRegistry.relative_date?(operator)
+          expand_relative_date(result, ransack_field, operator, value)
+        elsif OperatorRegistry.range?(operator)
+          expand_between(result, ransack_field, value)
+        else
+          ransack_key = "#{ransack_field}_#{operator}"
+          # Ransack ignores predicates with nil values. No-value operators
+          # (true, false, present, blank, null, not_null) need a truthy
+          # sentinel so Ransack actually applies the predicate.
+          result[ransack_key] = value.nil? && OperatorRegistry.no_value?(operator) ? 1 : value
+        end
+      end
+
+      private_class_method def self.expand_between(result, field, value)
+        return unless value.is_a?(Array) && value.size == 2
+
+        result["#{field}_gteq"] = value[0]
+        result["#{field}_lteq"] = value[1]
+      end
+
+      private_class_method def self.expand_relative_date(result, field, operator, value)
+        today = Date.current
+
+        case operator
+        when :last_n_days
+          n = value.to_i
+          result["#{field}_gteq"] = n.days.ago.beginning_of_day.iso8601
+        when :this_week
+          result["#{field}_gteq"] = today.beginning_of_week.iso8601
+          result["#{field}_lteq"] = today.end_of_week.iso8601
+        when :this_month
+          result["#{field}_gteq"] = today.beginning_of_month.iso8601
+          result["#{field}_lteq"] = today.end_of_month.iso8601
+        when :this_quarter
+          result["#{field}_gteq"] = today.beginning_of_quarter.iso8601
+          result["#{field}_lteq"] = today.end_of_quarter.iso8601
+        when :this_year
+          result["#{field}_gteq"] = today.beginning_of_year.iso8601
+          result["#{field}_lteq"] = today.end_of_year.iso8601
+        end
+      end
+
+      # Legacy format support: { "conditions" => [...], "groups" => [...] }
+      private_class_method def self.build_legacy(condition_tree)
+        result = {}
+        custom_field_params = {}
+
+        conditions = condition_tree["conditions"] || []
+        conditions.each do |condition|
+          extract_condition(condition, result, custom_field_params)
+        end
+
+        groups = condition_tree["groups"] || []
+        if groups.any?
+          result["g"] ||= {}
+          groups.each_with_index do |group, idx|
+            group_params = build_legacy_group(group, custom_field_params)
+            result["g"][idx.to_s] = group_params if group_params.present?
+          end
+        end
+
+        { ransack: result, custom_fields: custom_field_params }
+      end
+
+      private_class_method def self.build_legacy_group(group, custom_field_params)
+        combinator = group["combinator"] || "and"
+        result = { "m" => combinator }
+
+        (group["conditions"] || []).each do |condition|
+          extract_condition(condition, result, custom_field_params)
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/lcp_ruby/search/operator_registry.rb

@@ -0,0 +1,79 @@
+module LcpRuby
+  module Search
+    class OperatorRegistry
+      NUMERIC_OPERATORS = %i[eq not_eq gt gteq lt lteq between present blank null not_null].freeze
+      # Operators resolved at query time to absolute date ranges (not native Ransack predicates)
+      RELATIVE_DATE_OPERATORS = %i[last_n_days this_week this_month this_quarter this_year].freeze
+
+      TEMPORAL_OPERATORS = (NUMERIC_OPERATORS + RELATIVE_DATE_OPERATORS).freeze
+
+      OPERATORS_BY_TYPE = {
+        string:   %i[eq not_eq cont not_cont start not_start end not_end in not_in present blank null not_null],
+        text:     %i[cont not_cont present blank null not_null],
+        integer:  %i[eq not_eq gt gteq lt lteq between in not_in present blank null not_null],
+        float:    NUMERIC_OPERATORS,
+        decimal:  NUMERIC_OPERATORS,
+        boolean:  %i[true not_true false not_false null not_null],
+        date:     TEMPORAL_OPERATORS,
+        datetime: TEMPORAL_OPERATORS,
+        enum:     %i[eq not_eq in not_in present blank null not_null],
+        uuid:     %i[eq not_eq in not_in present blank null not_null],
+        array:    %i[array_contains array_overlaps present blank null not_null]
+      }.freeze
+
+      # Union of all operators across all types (used for validation and metadata)
+      ALL_OPERATORS = OPERATORS_BY_TYPE.values.flatten.uniq.freeze
+
+      # Operators that require no value input
+      NO_VALUE_OPERATORS = %i[present blank null not_null true not_true false not_false
+                              this_week this_month this_quarter this_year].freeze
+
+      # Operators that accept multiple values
+      MULTI_VALUE_OPERATORS = %i[in not_in].freeze
+
+      # Operators that accept two values (from + to)
+      RANGE_OPERATORS = %i[between].freeze
+
+      # Operators that require a numeric parameter (e.g., "last N days" -> N)
+      PARAMETERIZED_OPERATORS = %i[last_n_days].freeze
+
+      # Returns the list of operator symbols for a given field type.
+      def self.operators_for(field_type)
+        OPERATORS_BY_TYPE[field_type.to_sym] || []
+      end
+
+      # Returns the i18n-backed label for an operator.
+      def self.label_for(operator)
+        I18n.t(
+          "lcp_ruby.search.operators.#{operator}",
+          default: operator.to_s.humanize
+        )
+      end
+
+      # Returns true if the operator requires no value input.
+      def self.no_value?(operator)
+        NO_VALUE_OPERATORS.include?(operator.to_sym)
+      end
+
+      # Returns true if the operator accepts multiple values.
+      def self.multi_value?(operator)
+        MULTI_VALUE_OPERATORS.include?(operator.to_sym)
+      end
+
+      # Returns true if the operator accepts two values (from + to).
+      def self.range?(operator)
+        RANGE_OPERATORS.include?(operator.to_sym)
+      end
+
+      # Returns true if the operator requires a numeric parameter.
+      def self.parameterized?(operator)
+        PARAMETERIZED_OPERATORS.include?(operator.to_sym)
+      end
+
+      # Returns true if the operator is a relative date operator (resolved at query time).
+      def self.relative_date?(operator)
+        RELATIVE_DATE_OPERATORS.include?(operator.to_sym)
+      end
+    end
+  end
+end

data/lib/lcp_ruby/search/param_sanitizer.rb

@@ -0,0 +1,25 @@
+module LcpRuby
+  module Search
+    class ParamSanitizer
+      TRUTHY = %w[true 1 t yes].freeze
+      FALSY = %w[false 0 f no].freeze
+
+      # Removes key-value pairs where the value is a blank string.
+      # Preserves nil, false, 0, and non-string blanks.
+      def self.reject_blanks(params_hash)
+        return {} if params_hash.blank?
+
+        params_hash.reject { |_, v| v.is_a?(String) && v.blank? }
+      end
+
+      # Normalizes a value to boolean if it matches common truthy/falsy strings.
+      # Returns the original value unchanged if it doesn't match.
+      def self.normalize_boolean(value)
+        str = value.to_s.downcase
+        return true if TRUTHY.include?(str)
+        return false if FALSY.include?(str)
+        value
+      end
+    end
+  end
+end