quo 1.0.0.beta2 → 2.0.0

data/lib/generators/quo/install/install_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Quo
+  module Generators
+    # Installs the bundled Claude Code skill into the host application's
+    # .claude/skills/quo/ directory. Optionally appends a short "Quo" section
+    # to the project's top-level CLAUDE.md.
+    class InstallGenerator < ::Rails::Generators::Base
+      # Source the skill content directly from claude-skill/ at the gem root.
+      # The generator file lives at lib/generators/quo/install/, so we go up
+      # four levels to reach the gem root.
+      source_root File.expand_path("../../../../claude-skill", __dir__)
+
+      desc "Install the Quo Claude Code skill into .claude/skills/quo/"
+
+      class_option :with_claude_md, type: :boolean, default: false,
+        desc: "Append a 'Quo' section to CLAUDE.md pointing at the skill"
+
+      CLAUDE_MD_MARKER = "## Quo"
+
+      CLAUDE_MD_FRAGMENT = <<~MD
+        #{CLAUDE_MD_MARKER}
+
+        This project uses the [Quo gem](https://github.com/stevegeek/quo) for
+        query objects. See `.claude/skills/quo/SKILL.md` for usage guidance,
+        including the class-vs-instance composition rules.
+      MD
+
+      def copy_skill
+        directory ".", ".claude/skills/quo"
+      end
+
+      def maybe_append_claude_md
+        return unless options[:with_claude_md]
+
+        path = "CLAUDE.md"
+        full_path = File.join(destination_root, path)
+        if File.exist?(full_path)
+          if File.read(full_path).include?(CLAUDE_MD_MARKER)
+            say_status :skip, "#{path} already contains '#{CLAUDE_MD_MARKER}' section", :yellow
+          else
+            append_to_file path, "\n#{CLAUDE_MD_FRAGMENT}"
+          end
+        else
+          create_file path, CLAUDE_MD_FRAGMENT
+        end
+      end
+
+      def show_post_install_message
+        say ""
+        say "Quo skill installed at .claude/skills/quo/", :green
+        say "Claude Code will pick it up automatically on the next session.", :green
+        if options[:with_claude_md]
+          say "CLAUDE.md updated with a pointer to the skill.", :green
+        end
+        say ""
+        say "Run with --force after upgrading Quo to refresh the skill content."
+      end
+    end
+  end
+end

data/lib/quo/collection_backed_query.rb

@@ -3,33 +3,39 @@
 # rbs_inline: enabled
 
 module Quo
+  # Query object backed by in-memory collections
   class CollectionBackedQuery < Query
     prop :total_count, _Nilable(Integer), reader: false
 
-    # Wrap an enumerable collection or a block that returns an enumerable collection
-    # @rbs data: untyped, props: Symbol => untyped, block: () -> untyped
+    # @rbs data: Enumerable[untyped] | Quo::CollectionBackedQuery
+    # @rbs props: Hash[Symbol, untyped]
+    # @rbs &block: ? () -> Enumerable[untyped]
     # @rbs return: Quo::CollectionBackedQuery
     def self.wrap(data = nil, props: {}, &block)
-      klass = Class.new(self) do
-        props.each do |name, property|
-          if property.is_a?(Literal::Property)
-            prop name, property.type, property.kind, reader: property.reader, writer: property.writer, default: property.default
-          else
-            prop name, property
-          end
-        end
+      raise ArgumentError, "either a query or a block must be provided" unless data || block
+
+      if data && !(data.is_a?(::Enumerable) || data.is_a?(Quo::CollectionBackedQuery))
+        raise ArgumentError,
+          "Quo::CollectionBackedQuery.wrap requires an Enumerable or a Quo::CollectionBackedQuery instance; got #{data.class}. " \
+          "Use Quo::RelationBackedQuery.wrap or Quo::RelationBackedQuery.from for ActiveRecord relations."
       end
+
+      klass = Class.new(self)
+      define_props_on_class(klass, props)
       if block
         klass.define_method(:collection, &block)
-      elsif data
-        klass.define_method(:collection) { data }
       else
-        raise ArgumentError, "either a query or a block must be provided"
+        klass.define_method(:collection) { data }
       end
-      # klass.set_temporary_name = "quo::Wrapper" # Ruby 3.3+
       klass
     end
 
+    # @rbs enumerable: Enumerable[untyped]
+    # @rbs return: Quo::WrappedCollectionBackedQuery
+    def self.from(enumerable)
+      Quo::WrappedCollectionBackedQuery.new(wrapped: enumerable)
+    end
+
     # @rbs return: Object & Enumerable[untyped]
     def collection
       raise NotImplementedError, "Collection backed query objects must define a 'collection' method"
@@ -42,7 +48,7 @@ module Quo
       collection
     end
 
-    def results
+    def results #: Quo::Results
       Quo::CollectionResults.new(self, transformer: transformer, total_count: @total_count)
     end
 

data/lib/quo/collection_results.rb

@@ -3,6 +3,7 @@
 # rbs_inline: enabled
 
 module Quo
+  # Results wrapper for collection-backed queries providing pagination and counting
   class CollectionResults < Results
     # @rbs override
     def initialize(query, transformer: nil, total_count: nil)

data/lib/quo/composed_collection_backed_query.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  class ComposedCollectionBackedQuery < Quo.collection_backed_query_base_class
+    include ComposedInstance
+
+    # @rbs!
+    #   @left: Quo::Query | Enumerable[untyped]
+    #   @right: Quo::Query | Enumerable[untyped]
+    #   @merge_joins: Symbol | Hash[untyped, untyped] | Array[untyped] | nil
+    prop :left, _Union(Quo::Query, Enumerable), writer: false
+    prop :right, _Union(Quo::Query, Enumerable), writer: false
+    prop :merge_joins, _Nilable(_Union(Symbol, Hash, Array)), default: -> {}, writer: false
+
+    # @rbs override
+    def collection
+      merge_left_and_right
+    end
+
+    # @rbs override
+    def inspect
+      "#{self.class.name}[#{operand_desc(left)}, #{operand_desc(right)}]"
+    end
+
+    private
+
+    # @rbs operand: untyped
+    # @rbs return: String
+    def operand_desc(operand)
+      case operand
+      when Quo::Query
+        operand.class.name || "(anonymous Quo::Query)"
+      when ::ActiveRecord::Relation
+        operand.klass.name
+      else
+        operand.class.name || "(anonymous)"
+      end
+    end
+  end
+end

data/lib/quo/composed_instance.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module ComposedInstance
+    # @rbs **overrides: untyped
+    # @rbs return: Quo::Query
+    def copy(**overrides)
+      return super if overrides.empty?
+
+      own_keys = own_property_names
+      own_overrides = overrides.slice(*own_keys)
+      fan_overrides = overrides.except(*own_keys)
+
+      result = own_overrides.empty? ? self : super(**own_overrides)
+      fan_overrides.each do |key, value|
+        result = result.send(:fan_override, key, value)
+      end
+      result
+    end
+
+    private
+
+    # @rbs prop_name: Symbol
+    # @rbs value: untyped
+    # @rbs return: Quo::Query
+    def fan_override(prop_name, value)
+      right_match = operand_accepts?(right, prop_name)
+      left_match = operand_accepts?(left, prop_name)
+      unless right_match || left_match
+        raise ArgumentError, "unknown property #{prop_name.inspect} on #{self.class}"
+      end
+
+      result = self
+      if right_match
+        result = result.copy(right: apply_to_operand(right, prop_name, value))
+      end
+      if left_match
+        result = result.copy(left: apply_to_operand(left, prop_name, value))
+      end
+      result
+    end
+
+    # @rbs return: Array[Symbol]
+    def own_property_names
+      self.class.literal_properties.properties_index.keys
+    end
+
+    # @rbs operand: untyped
+    # @rbs prop_name: Symbol
+    # @rbs return: bool
+    def operand_accepts?(operand, prop_name)
+      case operand
+      when Quo::ComposedInstance
+        operand.send(:operand_accepts?, operand.right, prop_name) ||
+          operand.send(:operand_accepts?, operand.left, prop_name)
+      when Quo::Query
+        operand.class.literal_properties.properties_index.key?(prop_name)
+      else
+        false
+      end
+    end
+
+    # @rbs operand: untyped
+    # @rbs prop_name: Symbol
+    # @rbs value: untyped
+    # @rbs return: untyped
+    def apply_to_operand(operand, prop_name, value)
+      case operand
+      when Quo::ComposedInstance
+        operand.send(:fan_override, prop_name, value)
+      when Quo::Query
+        operand.copy(prop_name => value)
+      end
+    end
+
+    # @rbs return: ActiveRecord::Relation | Enumerable[untyped]
+    def merge_left_and_right
+      left_rel = unwrap_operand(left)
+      right_rel = unwrap_operand(right)
+
+      if both_relations?(left_rel, right_rel)
+        merge_active_record_relations(left_rel, right_rel)
+      elsif left_relation_right_enumerable?(left_rel, right_rel)
+        left_rel.to_a + right_rel.to_a
+      elsif left_enumerable_right_relation?(left_rel, right_rel) && left_rel.respond_to?(:+)
+        left_rel.to_a + right_rel.to_a
+      elsif left_rel.respond_to?(:+)
+        left_rel + right_rel
+      else
+        raise ArgumentError, "Cannot merge #{left.class} with #{right.class}"
+      end
+    end
+
+    # @rbs operand: untyped
+    # @rbs return: ActiveRecord::Relation | Enumerable[untyped]
+    def unwrap_operand(operand)
+      case operand
+      when Quo::Query
+        operand.unwrap_unpaginated
+      when ::ActiveRecord::Relation
+        operand
+      else
+        operand
+      end
+    end
+
+    # @rbs left_rel: ActiveRecord::Relation
+    # @rbs right_rel: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def merge_active_record_relations(left_rel, right_rel)
+      left_rel = left_rel.joins(merge_joins) if merge_joins
+      left_rel.merge(right_rel)
+    end
+
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def is_relation?(rel)
+      rel.is_a?(::ActiveRecord::Relation)
+    end
+
+    # @rbs lr: untyped
+    # @rbs rr: untyped
+    # @rbs return: bool
+    def both_relations?(lr, rr)
+      is_relation?(lr) && is_relation?(rr)
+    end
+
+    # @rbs lr: untyped
+    # @rbs rr: untyped
+    # @rbs return: bool
+    def left_relation_right_enumerable?(lr, rr)
+      is_relation?(lr) && !is_relation?(rr)
+    end
+
+    # @rbs lr: untyped
+    # @rbs rr: untyped
+    # @rbs return: bool
+    def left_enumerable_right_relation?(lr, rr)
+      !is_relation?(lr) && is_relation?(rr)
+    end
+  end
+end

data/lib/quo/composed_query.rb

@@ -2,48 +2,45 @@
 
 # rbs_inline: enabled
 
+require_relative "composing"
+
 module Quo
+  # Mixin for queries composed of two child queries
   module ComposedQuery
-    # Combine two Query classes into a new composed query class
-    # Combine two query-like or composeable entities:
-    # These can be Quo::Query, Quo::ComposedQuery, Quo::CollectionBackedQuery and ActiveRecord::Relations.
-    # See the `README.md` docs for more details.
-    # @rbs chosen_superclass: singleton(Quo::RelationBackedQuery | Quo::CollectionBackedQuery)
-    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-    # @rbs joins: untyped
-    # @rbs return: singleton(Quo::ComposedQuery)
-    def composer(chosen_superclass, left_query_class, right_query_class, joins: nil)
-      validate_query_classes(left_query_class, right_query_class)
-
-      props = collect_properties(left_query_class, right_query_class)
-      klass = create_composed_class(chosen_superclass, props)
-
-      assign_query_metadata(klass, left_query_class, right_query_class, joins)
-      klass
-    end
-    module_function :composer
-
-    # We can also merge instance of prepared queries
-    # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
-    # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
-    # @rbs joins: untyped
-    # @rbs return: Quo::ComposedQuery
-    def merge_instances(left_instance, right_instance, joins: nil)
-      validate_instances(left_instance, right_instance)
+    # Class-level methods shared by every composed query class. Defined once
+    # here and extended onto each anon class via the `included` hook below
+    # rather than being re-defined on every Class.new in the composer.
+    module ClassMethods
+      attr_reader :_composing_joins, :_left_specification, :_right_specification, :_left_query, :_right_query
+
+      # @rbs return: String
+      def inspect
+        left_desc = quo_operand_desc(_left_query)
+        right_desc = quo_operand_desc(_right_query)
+        klass_name = if self < Quo::RelationBackedQuery
+          Quo.relation_backed_query_base_class.name
+        else
+          Quo.collection_backed_query_base_class.name
+        end
+        "#{klass_name}<Quo::ComposedQuery>[#{left_desc}, #{right_desc}]"
+      end
 
-      if left_instance.is_a?(Quo::Query) && right_instance.is_a?(::ActiveRecord::Relation)
-        return merge_query_and_relation(left_instance, right_instance, joins)
-      elsif right_instance.is_a?(Quo::Query) && left_instance.is_a?(::ActiveRecord::Relation)
-        return merge_relation_and_query(left_instance, right_instance, joins)
-      elsif left_instance.is_a?(Quo::Query) && right_instance.is_a?(Quo::Query)
-        return merge_query_instances(left_instance, right_instance, joins)
+      # @rbs operand: Class
+      # @rbs return: String
+      def quo_operand_desc(operand)
+        if operand < Quo::ComposedQuery
+          operand.inspect
+        else
+          operand.name || operand.superclass&.name || "(anonymous)"
+        end
       end
+    end
 
-      # Both are AR relations
-      composer(Quo.relation_backed_query_base_class, left_instance, right_instance, joins: joins).new
+    # @rbs base: Class
+    # @rbs return: void
+    def self.included(base)
+      base.extend(ClassMethods)
     end
-    module_function :merge_instances
 
     # @rbs override
     def query
@@ -56,139 +53,6 @@ module Quo
       "#{klass_name}<Quo::ComposedQuery>[#{self.class.quo_operand_desc(left.class)}, #{self.class.quo_operand_desc(right.class)}](#{super})"
     end
 
-    class << self
-      private
-
-      # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      def validate_query_classes(left_query_class, right_query_class)
-        unless left_query_class.respond_to?(:<) && right_query_class.respond_to?(:<)
-          raise ArgumentError, "Cannot compose #{left_query_class} and #{right_query_class}, are they both classes? If you want to use instances use `.merge_instances`"
-        end
-      end
-
-      # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      def collect_properties(left_query_class, right_query_class)
-        props = {}
-        props.merge!(left_query_class.literal_properties.properties_index) if left_query_class < Quo::Query
-        props.merge!(right_query_class.literal_properties.properties_index) if right_query_class < Quo::Query
-        props
-      end
-
-      def create_composed_class(chosen_superclass, props)
-        Class.new(chosen_superclass) do
-          include Quo::ComposedQuery
-
-          class << self
-            attr_reader :_composing_joins, :_left_query, :_right_query
-
-            def inspect
-              left_desc = quo_operand_desc(_left_query)
-              right_desc = quo_operand_desc(_right_query)
-              klass_name = determine_class_name
-              "#{klass_name}<Quo::ComposedQuery>[#{left_desc}, #{right_desc}]"
-            end
-
-            # @rbs operand: Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation
-            # @rbs return: String
-            def quo_operand_desc(operand)
-              if operand < Quo::ComposedQuery
-                operand.inspect
-              else
-                operand.name || operand.superclass&.name || "(anonymous)"
-              end
-            end
-
-            private
-
-            # @rbs return: String
-            def determine_class_name
-              if self < Quo::RelationBackedQuery
-                Quo.relation_backed_query_base_class.name
-              else
-                Quo.collection_backed_query_base_class.name
-              end
-            end
-          end
-
-          props.each do |name, property|
-            prop(
-              name,
-              property.type,
-              property.kind,
-              reader: property.reader,
-              writer: property.writer,
-              default: property.default
-            )
-          end
-        end
-      end
-
-      # @rbs klass: Class
-      # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
-      # @rbs joins: untyped
-      def assign_query_metadata(klass, left_query_class, right_query_class, joins)
-        klass.instance_variable_set(:@_composing_joins, joins)
-        klass.instance_variable_set(:@_left_query, left_query_class)
-        klass.instance_variable_set(:@_right_query, right_query_class)
-      end
-
-      # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
-      # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
-      def validate_instances(left_instance, right_instance)
-        unless left_instance.is_a?(Quo::Query) || left_instance.is_a?(::ActiveRecord::Relation)
-          raise ArgumentError, "Cannot merge, left has incompatible type #{left_instance.class}"
-        end
-
-        unless right_instance.is_a?(Quo::Query) || right_instance.is_a?(::ActiveRecord::Relation)
-          raise ArgumentError, "Cannot merge, right has incompatible type #{right_instance.class}"
-        end
-      end
-
-      # @rbs relation: ::ActiveRecord::Relation
-      # @rbs query: Quo::Query
-      # @rbs joins: untyped
-      def merge_query_and_relation(query, relation, joins)
-        base_class = query.is_a?(Quo::RelationBackedQuery) ?
-                    Quo.relation_backed_query_base_class :
-                    Quo.collection_backed_query_base_class
-
-        composer(base_class, query.class, relation, joins: joins).new(**query.to_h)
-      end
-
-      # @rbs relation: ::ActiveRecord::Relation
-      # @rbs query: Quo::Query
-      # @rbs joins: untyped
-      def merge_relation_and_query(relation, query, joins)
-        base_class = query.is_a?(Quo::RelationBackedQuery) ?
-                    Quo.relation_backed_query_base_class :
-                    Quo.collection_backed_query_base_class
-
-        composer(base_class, relation, query.class, joins: joins).new(**query.to_h)
-      end
-
-      # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
-      # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
-      def merge_query_instances(left_query, right_query, joins)
-        props = left_query.to_h.merge(right_query.to_h.compact)
-
-        base_class = determine_base_class_for_queries(left_query, right_query)
-        composer(base_class, left_query.class, right_query.class, joins: joins).new(**props)
-      end
-
-      # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
-      # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
-      def determine_base_class_for_queries(left_query, right_query)
-        both_relation_backed = left_query.is_a?(Quo::RelationBackedQuery) &&
-          right_query.is_a?(Quo::RelationBackedQuery)
-
-        both_relation_backed ? Quo.relation_backed_query_base_class :
-                              Quo.collection_backed_query_base_class
-      end
-    end
-
     private
 
     # @rbs return: Hash[Symbol, untyped]
@@ -206,14 +70,20 @@ module Quo
     def left
       lq = self.class._left_query
       return lq if is_relation?(lq)
-      lq.new(**child_options(lq))
+      options = child_options(lq)
+      spec = self.class._left_specification
+      options[:_specification] = spec if spec && lq < Quo::RelationBackedQuery
+      lq.new(**options)
     end
 
     # @rbs return: Quo::Query | ::ActiveRecord::Relation
     def right
       rq = self.class._right_query
       return rq if is_relation?(rq)
-      rq.new(**child_options(rq))
+      options = child_options(rq)
+      spec = self.class._right_specification
+      options[:_specification] = spec if spec && rq < Quo::RelationBackedQuery
+      rq.new(**options)
     end
 
     # @rbs return: ActiveRecord::Relation | CollectionBackedQuery
@@ -238,14 +108,9 @@ module Quo
     # @rbs right_rel: ActiveRecord::Relation
     # @rbs return: ActiveRecord::Relation
     def merge_active_record_relations(left_rel, right_rel)
-      apply_joins(left_rel).merge(right_rel)
-    end
-
-    # @rbs left_rel: ActiveRecord::Relation
-    # @rbs return: ActiveRecord::Relation
-    def apply_joins(left_rel)
       joins = self.class._composing_joins
-      joins.present? ? left_rel.joins(joins) : left_rel
+      left_rel = left_rel.joins(joins) if joins
+      left_rel.merge(right_rel)
     end
 
     # @rbs rel: untyped

data/lib/quo/composed_relation_backed_query.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  class ComposedRelationBackedQuery < Quo.relation_backed_query_base_class
+    include ComposedInstance
+
+    # @rbs!
+    #   @left: Quo::Query | ActiveRecord::Relation | Enumerable[untyped]
+    #   @right: Quo::Query | ActiveRecord::Relation | Enumerable[untyped]
+    #   @merge_joins: Symbol | Hash[untyped, untyped] | Array[untyped] | nil
+    prop :left, _Union(Quo::Query, Enumerable), writer: false
+    prop :right, _Union(Quo::Query, Enumerable), writer: false
+    prop :merge_joins, _Nilable(_Union(Symbol, Hash, Array)), default: -> {}, writer: false
+
+    # @rbs override
+    def query
+      merge_left_and_right
+    end
+
+    # @rbs override
+    def inspect
+      "#{self.class.name}[#{operand_desc(left)}, #{operand_desc(right)}]"
+    end
+
+    private
+
+    # @rbs operand: untyped
+    # @rbs return: String
+    def operand_desc(operand)
+      case operand
+      when Quo::Query
+        operand.class.name || "(anonymous Quo::Query)"
+      when ::ActiveRecord::Relation
+        operand.klass.name
+      else
+        operand.class.name || "(anonymous)"
+      end
+    end
+  end
+end

data/lib/quo/composing/base_strategy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module Composing
+    # Base class for all composition strategies
+    class BaseStrategy
+      # @rbs left: untyped
+      # @rbs right: untyped
+      # @rbs return: bool
+      def applicable?(left, right)
+        raise NoMethodError, "Subclasses must implement #applicable?"
+      end
+
+      # @rbs return: untyped
+      def compose(...)
+        raise NoMethodError, "Subclasses must implement #compose"
+      end
+    end
+  end
+end