quo 1.0.0.beta2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3e56abbd1094d91702a10b327e82b05a28d7fc44e491316c438059de2c0c229
-  data.tar.gz: 7ebdcfb6b774c274ae30e7eaff556dae898be1f2a8478c5ee1544cfde41dcd25
+  metadata.gz: 5075f8c25c83bed882ac8bdcf8d4d8134ba9855c86daa719c00bc55bc4e1c2f0
+  data.tar.gz: 0f1ddf08726dab47fe471241a577891444f2a50007587c65889e189d3cfb48b7
 SHA512:
-  metadata.gz: ff1b0856ab186d6adfab0274aac9b94a61a0ece421716726b15c762a097f46d2566bcbe53fb04c589bb6d9eb708d91b65303b5cee419c0ae0cdeab193483089f
-  data.tar.gz: 4befea0da9dcbdb6a71f4e447b871e9f0424738f50908bef479f3fd89a2401a5fc861a7ddf124c36ffbfdec5e871b03a0fd75ffcf2941e861465e0ede1ef0f6e
+  metadata.gz: 8a9ccd8cefa74d620d371c0b4a6981acce0335e9122c3552c6273804ad4bd9081868b98da0497214bf93fae921e1394a692ccd87f0369c7666a38a3cae3bc36d
+  data.tar.gz: efafd7e1e2749187cc1cb1788ab59bb80d119f1476b4d0d3172abf2e08f17beaae5f254a620571b1b23a87e0af36d1776a0f584e89a83fdc435da31de501a05b

data/.devcontainer/Dockerfile

@@ -0,0 +1,17 @@
+# Make sure RUBY_VERSION matches the Ruby version in .ruby-version or gemspec
+ARG RUBY_VERSION=3.4.2
+FROM ghcr.io/rails/devcontainer/images/ruby:$RUBY_VERSION
+
+USER root
+
+# Install pkg-config and SQLite development libraries
+RUN apt-get update -qq && \
+    apt-get install -y pkg-config libsqlite3-dev && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+USER vscode
+
+# Ensure binding is always 0.0.0.0
+# Binds the server to all IP addresses of the container, so it can be accessed from outside the container.
+ENV BINDING="0.0.0.0"

data/.devcontainer/compose.yml

@@ -0,0 +1,10 @@
+name: "quo"
+
+services:
+  quo-dev-env:
+    container_name: quo-dev-env
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    ports:
+      - "3000"

data/.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+  "name": "Quo Gem Development",
+  "dockerComposeFile": "compose.yml",
+  "service": "quo-dev-env",
+  "containerEnv": {
+    "RAILS_ENV": "development"
+  },
+  "forwardPorts": [3000],
+  "postCreateCommand": "bundle install && bundle exec appraisal install",
+  "postStartCommand": "bundle exec appraisal rake test",
+  "remoteUser": "vscode"
+}

data/Appraisals

@@ -1,15 +1,7 @@
-appraise "rails-7.0" do
-  gem "rails", "~> 7.0"
-end
-
-appraise "rails-7.1" do
-  gem "rails", "~> 7.1"
-end
-
-appraise "rails-7.2" do
-  gem "rails", "~> 7.2"
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
 end
 
-appraise "rails-8.0" do
-  gem "rails", "~> 8.0"
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
 end

data/CHANGELOG.md

@@ -1,7 +1,117 @@
 ## [Unreleased]
 
+## [2.0.0] - 2026-05-12
 
-## [1.0.0.rc1] - Unreleased
+### Breaking
+
+- Minimum Rails 8.0; minimum Literal 1.9.
+- Instance composition (`q1 + q2`) returns a value (`Quo::ComposedRelationBackedQuery` / `Quo::ComposedCollectionBackedQuery`), not an anonymous class. No more per-call class allocation.
+- Each operand keeps its own constructor-time props; merge is the AND of each side's filter (1.x's prop fan-out is gone).
+- Pagination inherits as a coupled `(page, page_size)` pair from whichever operand is paginated (right wins).
+- `wrap` is type-strict at definition time. `Quo::RelationBackedQuery.wrap` requires an `ActiveRecord::Relation` or `Quo::RelationBackedQuery`; `Quo::CollectionBackedQuery.wrap` requires `Enumerable` or `Quo::CollectionBackedQuery`. Block forms still defer.
+
+### Added
+
+- `Quo::RelationBackedQuery.from(relation)` and `Quo::CollectionBackedQuery.from(enumerable)` value-form constructors. Zero class allocation per call.
+- `copy(prop: value)` on a composed instance fans the override across every operand declaring the prop, recursing into composed operands.
+- Composed and wrapped value-form classes inherit from `Quo.relation_backed_query_base_class` / `Quo.collection_backed_query_base_class`.
+
+### Fixed
+
+- #5 — `Quo::RelationBackedQuerySpecification#joins` / `#left_outer_joins` accept multiple tables.
+- #6 — `_specification` survives `Query#copy` and merge paths.
+- #7 — `Quo::Results` Enumerable delegation returns transformed items for filter-style methods (`select`, `reject`, `find`, `sort_by`, `partition`, …) where the block already saw transformed items.
+- #8 — `wrap` rejects the wrong type at definition time with a message pointing at the matching constructor.
+
+### Removed
+
+- Unused per-call `Quo::Composing::InstanceStrategyRegistry` + the four instance-strategy classes.
+
+## [1.0.1] - 2026-05-12
+
+### Fixed
+
+- Pin the `literal` dependency to `~> 1.6.0` in the gemspec. Quo's
+  internals reference `Literal::Null` (renamed to `Literal::Undefined`
+  in Literal 1.7) and `Literal::Types::ConstraintType.new` (signature
+  changed in Literal 1.7). Users whose lockfile resolved Literal to
+  1.7+ saw `NameError: uninitialized constant Literal::Null` or
+  `ArgumentError` at runtime / in CI. The 1.x line is now firmly on
+  Literal 1.6.x; a broader range targeting newer Literal versions is
+  planned for 2.0.
+- Defensive handling of the sentinel rename in `Quo::Query` so the
+  `LITERAL_UNSET` constant resolves to whichever name exists at load
+  time. This is belt-and-braces on top of the pin.
+
+## [1.0.0] - 2026-05-06
+
+First stable release. Folds in the perf work and tooling shipped in beta3.
+
+### Added
+
+- **Claude Code skill bundled with the gem.** A skill at `claude-skill/`
+  teaches Claude Code how to build composable, type-safe query objects
+  with Quo. The skill's `SKILL.md` covers the most important Quo concept
+  to get right — class-vs-instance composition, when to use each, and the
+  performance trade-offs involved. Reference files in
+  `claude-skill/references/` go deep on query types, composition, pagination,
+  transformers, and the API surface.
+- **Rails install generator.** `bin/rails generate quo:install` copies the
+  bundled skill into the host app's `.claude/skills/quo/` directory.
+  Re-running with `--force` refreshes the skill after a Quo upgrade.
+  Optional `--with-claude-md` opt-in appends a short pointer to the
+  project's top-level `CLAUDE.md`. The fragment is idempotent — safe to
+  re-run.
+
+## [1.0.0.beta3] - 2026-05-06
+
+### Performance
+
+Composition is materially cheaper. Constructing and resolving a composed query
+no longer reallocates per-call infrastructure that the Ruby/Literal class
+hierarchy already provides for free. On a representative composition graph
+(four-level tree, 16 page-renders), measured improvements over `1.0.0.beta2`:
+
+- ~46% lower wall-clock time
+- ~51% less time spent in GC
+- ~38% fewer total allocations
+
+No public API changes. The wins come from five internal fixes:
+
+- `Quo::Composing` now reuses singleton class- and instance-strategy
+  registries instead of allocating fresh ones on every `composer` /
+  `merge_instances` call.
+- The class-level helpers on composed query classes (`_composing_joins`,
+  `_left_query`, `inspect`, `quo_operand_desc`, etc.) live on a new
+  `Quo::ComposedQuery::ClassMethods` module that is `extend`ed via the
+  `included` hook, rather than being re-defined inside the per-class
+  `Class.new { class << self; ... end }` block.
+- `Quo::Composing::ClassStrategy#collect_properties` now skips properties
+  that the composed class's chosen superclass already declares — Literal
+  inherits these automatically, and re-registering them on every anonymous
+  class did a full `Literal::Property` allocation, schema dup, and
+  `module_eval` for no behavioural gain. This is the dominant win.
+- `Quo::RelationBackedQuery#respond_to_missing?` now reuses the memoized
+  `RelationBackedQuerySpecification.blank` singleton instead of allocating
+  a fresh specification on every probe (ActiveRecord's delegation chain
+  hits `respond_to?` heavily).
+- `Quo::ComposedQuery#left` / `#right` now pass `_specification:` to the
+  child constructor directly. Previously they always allocated the child
+  via `.new`, then allocated a second copy via `.with_specification(...)`
+  (which calls `copy(...)`), even when the specification was `nil`.
+
+## [1.0.0.beta2] - 2025-04-01
+
+### Breaking Changes
+
+- `Quo::ComposedQuery.composer` is now `Quo::Composing.composer`
+- `Quo::ComposedQuery.merge_instances` is now `Quo::Composing.merge_instances`
+
+### Fixed
+
+- Fixed issue with handling of query specifications in the query composer
+
+## [1.0.0.beta1] - 2025-04-01
 
 ### Breaking Changes
 
@@ -25,6 +135,7 @@ Nearly everything has had changes. Porting will require some effort.
 ### Added
 
 - Helpers `stub_query` and `mock_query` for Minitest
+- Support for Rails 8
 
 ## [0.5.0] - 2022-12-23
 

data/CLAUDE.md

@@ -0,0 +1,19 @@
+# Quo Development Guide
+
+## Build & Test Commands
+- Run all tests: `bundle exec rake test`
+- Run a single test: `bundle exec ruby -Ilib:test test/path/to/test_file.rb -n test_method_name`
+- Run tests across Rails versions: `bundle exec appraisal rake test`
+- Type checking: `bundle exec steep check`
+- Lint code: `bundle exec standardrb`
+- Fix lint issues: `bundle exec standardrb --fix`
+
+## Code Style Guidelines
+- **Frozen String Literals**: Include `# frozen_string_literal: true` at the top of every file
+- **Types**: Use RBS for type annotations with `# rbs_inline: enabled` and `@rbs` annotations
+- **Naming**: Use snake_case for methods/variables, CamelCase for classes, and SCREAMING_CASE for constants
+- **Error Handling**: Raise specific errors with clear messages
+- **Indentation**: 2 spaces (default Standard Ruby style)
+- **Testing**: Use Minitest for tests
+- **Framework**: Built on Literal gem - use Literal::Struct and Literal::Types
+- **Documentation**: Document public methods with comments

data/Gemfile

@@ -5,7 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in quo.gemspec
 gemspec
 
-gem "rails", "~> 7.2"
+gem "rails", "~> 8"
 
 group :development, :test do
   gem "sqlite3"
@@ -14,9 +14,15 @@ group :development, :test do
 
   gem "minitest", "~> 5.0"
 
+  gem "simplecov", require: false
+
   gem "standard", require: false
 
   gem "steep", require: false
 
   gem "rbs-inline", "~> 0.11.0", require: false
+
+  gem "simplecov-small-badge", require: false
+  gem "rubycritic-small-badge", require: false
+  gem "repo-small-badge"
 end

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022-2024 Stephen Ierodiaconou
+Copyright (c) 2022-2025 Stephen Ierodiaconou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal