lcp 0.1.0

data/lib/lcp_ruby/array_query.rb

@@ -0,0 +1,120 @@
+module LcpRuby
+  # DB-portable query helpers for array fields.
+  # Uses native PG array operators (@>, &&, <@) on PostgreSQL
+  # and json_each() subqueries on SQLite.
+  class ArrayQuery
+    class << self
+      # Records where the array field contains ALL of the given values.
+      def contains(scope, table_name, field_name, values, item_type: "string")
+        values = Array(values)
+        return scope if values.empty?
+
+        c = connection
+        col = quoted_column(c, table_name, field_name)
+
+        condition = if LcpRuby.postgresql?
+          "#{col} @> #{pg_array_literal(values, c, item_type)}"
+        else
+          "(SELECT COUNT(DISTINCT je.value) FROM json_each(#{col}) je " \
+            "WHERE je.value IN (#{quoted_values(values, c)})) = #{values.size}"
+        end
+
+        scope.where(Arel.sql(condition))
+      end
+
+      # Records where the array field contains ANY of the given values.
+      def overlaps(scope, table_name, field_name, values, item_type: "string")
+        values = Array(values)
+        return scope.none if values.empty?
+
+        c = connection
+        col = quoted_column(c, table_name, field_name)
+
+        condition = if LcpRuby.postgresql?
+          "#{col} && #{pg_array_literal(values, c, item_type)}"
+        else
+          "EXISTS (SELECT 1 FROM json_each(#{col}) je " \
+            "WHERE je.value IN (#{quoted_values(values, c)}))"
+        end
+
+        scope.where(Arel.sql(condition))
+      end
+
+      # Records where the array field is a subset of the given values.
+      # Empty values matches only records with empty arrays.
+      def contained_by(scope, table_name, field_name, values, item_type: "string")
+        values = Array(values)
+
+        c = connection
+        col = quoted_column(c, table_name, field_name)
+
+        if values.empty?
+          return scope.where(Arel.sql(
+            LcpRuby.postgresql? ?
+              "#{col} = '{}'" :
+              "json_array_length(#{col}) = 0"
+          ))
+        end
+
+        condition = if LcpRuby.postgresql?
+          "#{col} <@ #{pg_array_literal(values, c, item_type)}"
+        else
+          "NOT EXISTS (SELECT 1 FROM json_each(#{col}) je " \
+            "WHERE je.value NOT IN (#{quoted_values(values, c)}))"
+        end
+
+        scope.where(Arel.sql(condition))
+      end
+
+      # SQL expression for the size of the array.
+      def array_length_expression(table_name, field_name)
+        c = connection
+        col = quoted_column(c, table_name, field_name)
+
+        if LcpRuby.postgresql?
+          "COALESCE(array_length(#{col}, 1), 0)"
+        else
+          "json_array_length(#{col})"
+        end
+      end
+
+      # Text search condition for array string fields (used by QuickSearch).
+      def text_search_condition(table_name, field_name, query)
+        c = connection
+        col = quoted_column(c, table_name, field_name)
+        quoted_query = c.quote("%#{query}%")
+
+        if LcpRuby.postgresql?
+          "EXISTS (SELECT 1 FROM unnest(#{col}) item " \
+            "WHERE item ILIKE #{quoted_query})"
+        else
+          "EXISTS (SELECT 1 FROM json_each(#{col}) je " \
+            "WHERE je.value LIKE #{quoted_query})"
+        end
+      end
+
+      private
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      def quoted_column(c, table_name, field_name)
+        "#{c.quote_table_name(table_name)}.#{c.quote_column_name(field_name)}"
+      end
+
+      def quoted_values(values, c)
+        values.map { |v| c.quote(v.to_s) }.join(", ")
+      end
+
+      def pg_array_literal(values, c, item_type)
+        pg_type = case item_type
+        when "integer" then "integer[]"
+        when "float"   then "float8[]"
+        else "text[]"
+        end
+        "ARRAY[#{quoted_values(values, c)}]::#{pg_type}"
+      end
+    end
+  end
+end

data/lib/lcp_ruby/asset_copier.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module LcpRuby
+  # Copies a bundled asset tree (the curated docs, or an example app) into a
+  # target directory, skipping generated/dev artifacts. Rails-free.
+  #
+  # The reject list here is the single source of truth: the gemspec packaging
+  # glob mirrors it (so the same artifacts are never packaged), and
+  # `LcpRuby::CLI::RunCommand` reuses {.copy} to materialize an example app.
+  module AssetCopier
+    # Directory names rejected anywhere in the tree.
+    REJECT_DIRS  = %w[tmp log storage node_modules .git .playwright-mcp].freeze
+    # Basenames rejected at any nesting level (e.g. ERD artifacts).
+    REJECT_BASENAMES = %w[erd.dot erd.pdf].freeze
+    # Matches `foo.sqlite3` plus the WAL/SHM/journal session files SQLite
+    # writes next to an open DB (`.sqlite3-wal`, `.sqlite3-shm`,
+    # `.sqlite3-journal`). Aligned with the gemspec packaging reject regex.
+    SQLITE_SUFFIX_RE = /\.sqlite3(?:-shm|-wal|-journal)?\z/.freeze
+
+    module_function
+
+    # True if a path (relative to the source root) should be skipped. The rules
+    # mirror the gemspec packaging reject regex so `lcp examples copy` /
+    # `lcp run` materialize the same set of files as the gem ships.
+    def reject?(relative_path)
+      segments = relative_path.split(File::SEPARATOR)
+      basename = segments.last
+
+      return true if segments.any? { |s| REJECT_DIRS.include?(s) }
+      return true if REJECT_BASENAMES.include?(basename)
+      # SQLite artifacts inside any `db/` directory, at any nesting depth.
+      return true if basename.match?(SQLITE_SUFFIX_RE) && segments[0..-2].include?("db")
+
+      false
+    end
+
+    # Copy every file under +src+ into +dst+, preserving structure and skipping
+    # the reject list. Creates +dst+ as needed. Dotfiles are excluded (matching
+    # the gemspec packaging glob, which also skips them). Returns the list of
+    # copied relative paths.
+    def copy(src, dst)
+      src = File.expand_path(src)
+      dst = File.expand_path(dst)
+      copied = []
+
+      Dir.glob("**/*", base: src).each do |rel|
+        abs = File.join(src, rel)
+        next unless File.file?(abs)
+        next if reject?(rel)
+
+        target = File.join(dst, rel)
+        FileUtils.mkdir_p(File.dirname(target))
+        FileUtils.cp(abs, target)
+        copied << rel
+      end
+
+      copied
+    end
+  end
+end

data/lib/lcp_ruby/association_fk_type.rb

@@ -0,0 +1,191 @@
+require "set"
+
+module LcpRuby
+  # Shared helpers for resolving foreign-key column types from an
+  # AssociationDefinition.
+  #
+  # Two flavors are exposed:
+  #
+  # * `schema_type(assoc)` — returns a schema-level symbol suitable for
+  #   `connection.add_column` / `t.<type>` (`:bigint`, `:integer`, `:string`,
+  #   …). Used by `SchemaManager` when auto-creating FK columns.
+  #
+  # * `field_type(assoc)` — returns a string from
+  #   `Metadata::FieldDefinition::BASE_TYPES` (`"integer"`, `"string"`, …)
+  #   suitable for constructing a synthetic `FieldDefinition`. Used by
+  #   `Import::RowProcessor`, `Import::FieldTreeBuilder`, and
+  #   `Export::FieldTreeBuilder` which build field metadata for FK columns.
+  #
+  # The two vocabularies are not the same — `:bigint` is a schema concept
+  # only and is normalized to `"integer"` for FieldDefinition purposes.
+  #
+  # Lives outside SchemaManager so all of the above call sites can reach it
+  # without cross-class plumbing.
+  module AssociationFkType
+    # Schema-level vocabulary → FieldDefinition::BASE_TYPES vocabulary.
+    SCHEMA_TO_FIELD_TYPE = {
+      bigint:   "integer",
+      integer:  "integer",
+      string:   "string",
+      text:     "text",
+      float:    "float",
+      decimal:  "decimal",
+      boolean:  "boolean",
+      date:     "date",
+      datetime: "datetime",
+      uuid:     "uuid"
+    }.freeze
+
+    module_function
+
+    # Schema-level type symbol suitable for `connection.add_column` /
+    # `t.<type>`. Implements the resolution rules in the spec's
+    # "FK Column Creation" section. Raises `MetadataError` for non-LCP
+    # targets with `primary_key:` set (Decision 12) — the validator should
+    # have caught this earlier; this is a defensive tripwire so we never
+    # silently fall back to `:bigint` and corrupt the schema.
+    def schema_type(assoc)
+      if assoc.primary_key.present? && !assoc.lcp_model?
+        raise LcpRuby::MetadataError,
+              "Association '#{assoc.owner_name}##{assoc.name}': primary_key " \
+              "'#{assoc.primary_key}' targets an external class " \
+              "('#{assoc.class_name}'). This should have been caught by " \
+              "ConfigurationValidator — please file a bug. Workaround: " \
+              "declare the FK column explicitly via 'fields:'."
+      end
+
+      return :bigint unless assoc.lcp_model?
+
+      target_def = LcpRuby.loader.model_definitions[assoc.target_model]
+
+      if assoc.primary_key.present?
+        unless target_def
+          raise LcpRuby::MetadataError,
+                "Association '#{assoc.owner_name}##{assoc.name}': target_model " \
+                "'#{assoc.target_model}' not found in loader (dangling reference)"
+        end
+
+        ref_field = target_def.fields.find { |f| f.name == assoc.primary_key }
+        return ref_field.type.to_sym if ref_field
+
+        if target_def.primary_key_column == assoc.primary_key
+          return target_def.primary_key_type
+        end
+
+        raise LcpRuby::MetadataError,
+              "Association '#{assoc.owner_name}##{assoc.name}': primary_key " \
+              "'#{assoc.primary_key}' not found on target '#{assoc.target_model}'"
+      end
+
+      return :bigint unless target_def
+      target_def.primary_key_type
+    end
+
+    # FieldDefinition-level type string suitable for
+    # `Metadata::FieldDefinition.new(type: ...)`.
+    #
+    # Wraps `schema_type` and normalizes schema-only aliases (`:bigint` →
+    # `"integer"`) onto `FieldDefinition::BASE_TYPES` so the result can be
+    # fed into `FieldDefinition.new` without raising.
+    def field_type(assoc)
+      type = schema_type(assoc)
+      SCHEMA_TO_FIELD_TYPE[type.to_sym] || type.to_s
+    end
+
+    # ----- helpers used by ConfigurationValidator's managed-field collision check -----
+
+    # Normalize a FieldDefinition's *declared YAML type* to the type the
+    # underlying adapter actually stores, so the validator can compare
+    # against `existing.sql_type_metadata.type` without spurious mismatches.
+    #
+    # Reads `field.type` (raw declared YAML type) rather than
+    # `field.column_type` because `column_type` already collapses some
+    # types (`:uuid` → `:string`) before the adapter dimension is known —
+    # we want the YAML's declared shape and apply the adapter mapping here.
+    #
+    # Examples (declared YAML type → AR's `sql_type_metadata.type` string):
+    #   field type    PG          MySQL       SQLite
+    #   ──────────────────────────────────────────────
+    #   json          jsonb       json        json (AR preserves the type label)
+    #   jsonb         jsonb       json        json
+    #   uuid          uuid        string      string
+    #   enum          string      string      string
+    #   rich_text     text        text        text
+    #   file          string      string      string
+    #   array         <pg array>  text        text
+    #   <other base>  <as decl>   <as decl>   <as decl>
+    #
+    # Without this normalization, a YAML row like `type: json, lcp_managed: true`
+    # paired with a host column declared `t.json :settings` reports differently
+    # across adapters at the metadata layer (e.g., :jsonb on PG vs :json on
+    # SQLite/MySQL) and would spuriously error on every boot.
+    def adapter_normalized_type(field, connection)
+      declared = field.type.to_s
+      adapter = connection.adapter_name.to_s.downcase
+
+      case declared
+      when "json", "jsonb"
+        # PG returns :jsonb at the metadata layer for both JSON and JSONB
+        # columns; MySQL and SQLite both report :json. The pair {json, jsonb}
+        # is treated as compatible by compatible_column_types?, so the
+        # normalization here just picks the canonical adapter label.
+        adapter.include?("postgres") ? "jsonb" : "json"
+      when "uuid"
+        adapter.include?("postgres") ? "uuid" : "string"
+      when "enum"
+        "string"
+      when "rich_text"
+        "text"
+      when "file"
+        "string"
+      when "array"
+        # Mirror SchemaManager#build_column_options: PG uses native typed
+        # arrays; non-PG stores via LcpRuby.json_column_type. On SQLite that
+        # resolves to :json (AR preserves the type label even though the
+        # underlying storage is TEXT); on MySQL to :json. Keeping symmetry
+        # with the actual storage label avoids spurious validator collisions
+        # when a managed `type: array` field is declared against an existing
+        # host column whose AR type is :json.
+        adapter.include?("postgres") ? declared : LcpRuby.json_column_type.to_s
+      else
+        declared
+      end
+    end
+
+    # True iff two adapter-level type strings represent the same column
+    # storage. Used in `validate_managed_field_collisions` to allow legitimate
+    # idempotent re-checks (e.g., `:integer` vs `:bigint` for FK columns).
+    #
+    # Designed conservatively: silent type widening (string ↔ text,
+    # decimal ↔ float) is rejected because the failure mode of a quiet
+    # mismatch is data corruption far from the source.
+    EQUIVALENT_TYPE_PAIRS = [
+      %w[integer bigint].sort.freeze,
+      %w[json jsonb].sort.freeze
+    ].to_set.freeze
+
+    # Adapter-gated equivalents — only compatible on certain adapters.
+    # `text` ↔ `json` are stored identically on SQLite and MySQL (json is
+    # a label over TEXT/LONGTEXT), so a host that declared the column as
+    # `t.text` for a YAML `type: array` (json) field is honoring the same
+    # storage. PostgreSQL has a real `json`/`jsonb` type — keep strict.
+    NON_PG_EQUIVALENT_TYPE_PAIRS = [
+      %w[json text].sort.freeze
+    ].to_set.freeze
+
+    # `adapter` is optional — pass `connection.adapter_name` so non-PG
+    # storage equivalents can be honored. Without it, only the strict
+    # cross-adapter equivalents (EQUIVALENT_TYPE_PAIRS) apply.
+    def compatible_column_types?(declared, actual, adapter: nil)
+      d = declared.to_s
+      a = actual.to_s
+      return true if d == a
+      pair = [ d, a ].sort
+      return true if EQUIVALENT_TYPE_PAIRS.include?(pair)
+      if adapter && !adapter.to_s.downcase.include?("postgres")
+        return true if NON_PG_EQUIVALENT_TYPE_PAIRS.include?(pair)
+      end
+      false
+    end
+  end
+end

data/lib/lcp_ruby/association_join_column.rb

@@ -0,0 +1,28 @@
+module LcpRuby
+  # Helper for resolving the join column on an association — i.e., the
+  # column whose value the form / search / cascading-select / page-parameter
+  # submits as the FK value.
+  #
+  # For belongs_to with `primary_key:` set, the join column is that custom
+  # column on the target. Otherwise it is the target's actual primary key
+  # column (usually "id").
+  #
+  # Used by Layer B consumers (form_helper, resources_controller,
+  # association_options_builder, view partials, page parameter resolver,
+  # virtual_columns/builder, import row processor, …) which bypass AR's
+  # reflection and need the column name directly.
+  module AssociationJoinColumn
+    module_function
+
+    # @param assoc [LcpRuby::Metadata::AssociationDefinition]
+    # @param target_class [Class, nil] resolved AR class — pass it in when
+    #   already known to avoid an extra registry lookup.
+    # @return [String] the column name to read off a target record
+    def for(assoc, target_class = nil)
+      return assoc.primary_key if assoc.primary_key.present?
+
+      target_class ||= LcpRuby.registry.model_for(assoc.target_model)
+      target_class.primary_key
+    end
+  end
+end

data/lib/lcp_ruby/association_options_builder.rb

@@ -0,0 +1,231 @@
+module LcpRuby
+  # Shared helpers for building association select options.
+  # Used by both FormHelper (server-side rendering) and
+  # ResourcesController (AJAX JSON endpoint).
+  module AssociationOptionsBuilder
+    # Maximum number of options returned in non-search mode to prevent
+    # unbounded result sets for large tables.
+    MAX_SELECT_OPTIONS = 1000
+
+    OptionsQuery = Struct.new(:query, :label_method, :disabled_ids, :target_class, :join_column, keyword_init: true)
+
+    private
+
+    # Build a fully prepared query for association select options.
+    # Applies scope, filter, depends_on, sort, and SELECT column optimization.
+    # Returns an OptionsQuery struct ready for formatting.
+    #
+    # @param user [Object, nil] when present, the resulting relation is
+    #   wrapped through the target model's Pundit policy_scope so the
+    #   builder cannot leak records the user is not authorized to see.
+    #   Callers in request context MUST pass `user: current_user`;
+    #   the kwarg is optional only so non-request callers
+    #   (rake tasks, fixtures) can opt out explicitly.
+    def build_options_query(assoc, input_options, role: nil, depends_on_values: {}, user: nil)
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      query = apply_option_scope(target_class, input_options, role: role, user: user, target_model_name: assoc.target_model)
+      query = query.where(input_options["filter"]) if input_options["filter"]
+
+      depends_on = input_options["depends_on"]
+      if depends_on && depends_on_values.present?
+        fk = depends_on["foreign_key"]
+        parent_value = depends_on_values[depends_on["field"]]
+        query = query.where(fk => parent_value) if fk && parent_value.present?
+      end
+
+      query = query.order(input_options["sort"]) if input_options["sort"]
+
+      label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+      join_column = LcpRuby::AssociationJoinColumn.for(assoc, target_class)
+      disabled_ids = resolve_disabled_values(assoc, input_options)
+
+      select_cols = optimize_select_columns(
+        target_class, label_method, input_options["group_by"], sort: input_options["sort"],
+        join_column: join_column
+      )
+      query = query.select(*select_cols) if select_cols
+
+      max = (input_options["max_options"] || MAX_SELECT_OPTIONS).to_i
+      query = query.limit(max)
+
+      OptionsQuery.new(
+        query: query,
+        label_method: label_method,
+        disabled_ids: disabled_ids,
+        target_class: target_class,
+        join_column: join_column
+      )
+    end
+
+    # Unified scope application for both server-side and AJAX select options.
+    #
+    # When `user:` and `target_model_name:` are both supplied, the
+    # resulting relation is wrapped through the target model's Pundit
+    # `policy_scope`, so callers cannot leak records the user is not
+    # authorized to see. The base scope (configurator's `scope:` or
+    # `scope_by_role:` choice) is applied first; Pundit further narrows
+    # it. When `user:` is nil the relation is returned unscoped — only
+    # callers outside request context (rake, fixtures) should rely on
+    # that path; all controllers / helpers MUST pass the user.
+    def apply_option_scope(target_class, input_options, role: nil, user: nil, target_model_name: nil)
+      base =
+        if input_options["scope_by_role"] && role.present?
+          role_scope = input_options.dig("scope_by_role", role)
+          if role_scope && role_scope != "all" && target_class.respond_to?(role_scope)
+            target_class.send(role_scope)
+          else
+            target_class.all
+          end
+        elsif input_options["scope"] && target_class.respond_to?(input_options["scope"])
+          target_class.send(input_options["scope"])
+        else
+          target_class.all
+        end
+
+      return base unless user && target_model_name
+
+      LcpRuby::Authorization::ScopeResolver.resolve(user, base, target_model_name)
+    end
+
+    # Format OptionsQuery result as Rails select-compatible arrays.
+    # Flat: [[label, value], [label, value, {disabled}], ...]
+    # Grouped: { "group" => [[label, value], ...], ... }
+    def format_options_for_select(oq, input_options)
+      join_col = (oq.join_column || :id).to_sym
+      if input_options["group_by"]
+        group_attr = input_options["group_by"]
+        oq.query.group_by { |r| r.respond_to?(group_attr) ? r.send(group_attr) : "Other" }
+          .sort_by { |group_name, _| group_name.to_s }
+          .to_h
+          .transform_values do |records|
+            records.map do |r|
+              value = r.public_send(join_col)
+              option = [ resolve_label(r, oq.label_method), value ]
+              option << { disabled: "disabled" } if oq.disabled_ids.include?(value)
+              option
+            end
+          end
+      else
+        oq.query.map do |r|
+          value = r.public_send(join_col)
+          option = [ resolve_label(r, oq.label_method), value ]
+          option << { disabled: "disabled" } if oq.disabled_ids.include?(value)
+          option
+        end
+      end
+    end
+
+    # Format OptionsQuery result as JSON-compatible hashes.
+    # Flat: [{value:, label:}, ...]
+    # Grouped: [{group:, options: [{value:, label:}]}, ...]
+    def format_options_for_json(oq, input_options)
+      join_col = (oq.join_column || :id).to_sym
+      if input_options["group_by"]
+        group_attr = input_options["group_by"]
+        grouped = oq.query.group_by { |r| r.respond_to?(group_attr) ? r.send(group_attr) : "Other" }
+        grouped.sort_by { |k, _| k.to_s }.map do |group_name, records|
+          {
+            group: group_name.to_s,
+            options: records.map { |r|
+              value = r.public_send(join_col)
+              opt = { value: value, label: resolve_label(r, oq.label_method) }
+              opt[:disabled] = true if oq.disabled_ids.include?(value)
+              opt
+            }
+          }
+        end
+      else
+        oq.query.map { |r|
+          value = r.public_send(join_col)
+          opt = { value: value, label: resolve_label(r, oq.label_method) }
+          opt[:disabled] = true if oq.disabled_ids.include?(value)
+          opt
+        }
+      end
+    end
+
+    def resolve_label(record, label_method)
+      record.respond_to?(label_method) ? record.send(label_method) : record.to_s
+    end
+
+    def resolve_default_label_method(assoc)
+      target_model_def = LcpRuby.loader.model_definition(assoc.target_model)
+      method = target_model_def&.label_method
+      method && method != "to_s" ? method : "to_label"
+    rescue LcpRuby::MetadataError
+      "to_label"
+    end
+
+    # Returns a Set of disabled IDs from static disabled_values or a named scope.
+    def resolve_disabled_values(assoc, input_options)
+      disabled = Set.new
+
+      if input_options["disabled_values"].is_a?(Array)
+        # Do NOT coerce to integer — the join column may be a string
+        # business key (e.g. "EUR", "0042") which must round-trip
+        # unchanged. Comparison sites use the raw value.
+        input_options["disabled_values"].each { |v| disabled << v }
+      end
+
+      if input_options["disabled_scope"]
+        target_class = LcpRuby.registry.model_for(assoc.target_model)
+        scope_name = input_options["disabled_scope"]
+        if target_class.respond_to?(scope_name)
+          join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+          target_class.send(scope_name).pluck(join_col).each { |v| disabled << v }
+        end
+      end
+
+      disabled
+    end
+
+    # Returns [label, value] if the record exists in the legacy scope but not in
+    # the normal option set, nil otherwise.
+    def resolve_legacy_record(assoc, input_options, current_value)
+      return nil unless current_value.present?
+
+      legacy_scope_name = input_options["legacy_scope"]
+      return nil unless legacy_scope_name
+
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      return nil unless target_class.respond_to?(legacy_scope_name)
+
+      label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+      join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+      record = target_class.send(legacy_scope_name).find_by(join_col => current_value)
+      return nil unless record
+
+      [ resolve_label(record, label_method), record.public_send(join_col) ]
+    end
+
+    # Returns array of columns to SELECT, or nil when optimization is not safe.
+    # Optimization is skipped when any referenced column (label, group_by, sort)
+    # is not a real DB column (e.g. computed method like :to_label).
+    def optimize_select_columns(target_class, label_method, group_by, sort: nil, join_column: :id)
+      return nil unless target_class.respond_to?(:column_names)
+
+      label_col = label_method.to_s
+      return nil unless target_class.column_names.include?(label_col)
+
+      join_col = join_column.to_s
+      return nil unless target_class.column_names.include?(join_col)
+
+      cols = [ join_col.to_sym, label_col.to_sym ]
+
+      if group_by
+        return nil unless target_class.column_names.include?(group_by.to_s)
+        cols << group_by.to_sym
+      end
+
+      if sort.is_a?(Hash)
+        sort.each_key do |col|
+          col_s = col.to_s
+          return nil unless target_class.column_names.include?(col_s)
+          cols << col_s.to_sym
+        end
+      end
+
+      cols.uniq
+    end
+  end
+end