quo 1.0.0.beta2 → 2.0.0

data/Rakefile

@@ -1,14 +1,74 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+desc "Run tests"
+task :test do
+  sh "bin/test"
 end
 
 require "standard/rake"
 
 task default: %i[test standard]
+
+# Add RubyCritic task with badge generation
+begin
+  require "rubycritic_small_badge"
+  require "rubycritic/rake_task"
+
+  RubyCriticSmallBadge.configure do |config|
+    config.minimum_score = 90
+  end
+
+  RubyCritic::RakeTask.new do |task|
+    task.paths = FileList["lib/**/*.rb"]
+
+    task.options = %(--custom-format RubyCriticSmallBadge::Report
+      --minimum-score #{RubyCriticSmallBadge.config.minimum_score}
+      --coverage-path coverage/.resultset.json
+      --no-browser)
+  end
+
+  desc "Run tests with coverage and then RubyCritic"
+  task rubycritic_with_coverage: [:coverage, :rubycritic]
+rescue LoadError
+  desc "Run RubyCritic (not available)"
+  task :rubycritic do
+    puts "RubyCritic is not available"
+  end
+end
+
+desc "Run code coverage"
+task :coverage do
+  ENV["COVERAGE"] = "1"
+  Rake::Task["test"].invoke
+end
+
+namespace :website do
+  desc "Build the documentation website"
+  task :build do
+    Dir.chdir("website") do
+      puts "Building documentation website..."
+      system "bundle install"
+      system "bundle exec jekyll build"
+      puts "Website built in website/_site/"
+    end
+  end
+
+  desc "Serve the documentation website locally"
+  task :serve do
+    Dir.chdir("website") do
+      puts "Starting local documentation server..."
+      puts "View the website at http://localhost:4000/"
+      system "bundle install"
+      system "bundle exec jekyll serve"
+    end
+  end
+
+  desc "Clean the documentation website build"
+  task :clean do
+    Dir.chdir("website") do
+      puts "Cleaning website build..."
+      system "bundle exec jekyll clean"
+    end
+  end
+end

data/UPGRADING.md

@@ -0,0 +1,216 @@
+# Upgrading Quo
+
+## Upgrading from 1.x to 2.0
+
+Quo 2.0 is a structural rework of query composition. Most code continues
+to work unchanged. There are two intentional behavioural changes worth
+knowing about before you bump, plus a new value-form API you'll want to
+adopt for hot paths.
+
+### TL;DR
+
+- Composition still uses `+` / `compose` / `merge`. Same API.
+- **Class composition** (`SomeClass + OtherClass`) — unchanged. Returns a Class.
+- **Instance composition** (`some_instance + other_instance`) — now returns a
+  concrete value (`Quo::ComposedRelationBackedQuery` or
+  `Quo::ComposedCollectionBackedQuery`), not an anonymous class. Allocates
+  no new classes per call.
+- New: `Quo::RelationBackedQuery.from(relation)` and
+  `Quo::CollectionBackedQuery.from(enumerable)` — value-form constructors,
+  for use instead of `wrap(rel).new` on hot paths.
+- 1.x's "prop fan-out from a synthesised parent class" is gone. Each
+  operand keeps its own constructor-time props. Two subtle consequences
+  documented below.
+- ~2× faster instance composition, with **zero anonymous classes per call**.
+
+### Why
+
+1.x had a single composition path. Both `Q1 + Q2` (between classes) and
+`q1 + q2` (between instances) went through the same machinery, which
+allocated a fresh anonymous class on every call. For instances, the
+class was then immediately instantiated once and discarded — pure
+waste, paid per request.
+
+2.0 splits the two cases. Class composition keeps the class-allocation
+machinery (it's the right shape for *defining a new type* once at
+code-load time). Instance composition produces a value instead — a
+small struct that holds the two operands and walks them at unwrap
+time. No anonymous classes, no `prop` re-registration.
+
+### What's the same
+
+- The `+` / `compose` / `merge` API at both class and instance levels.
+- The leaf query class API: `prop`, `query`, `collection`, `transform`,
+  `wrap`, `with_specification`, etc.
+- Pagination and transformer surfaces on every Quo::Query.
+- Specifications (`order(...)`, `joins(...)`, `where(...)`, `distinct`,
+  etc.) on relation-backed queries, including when applied to a composed
+  instance.
+- `Quo::ComposedQuery` is still the marker module used by class
+  composition. Existing `kind_of?(Quo::ComposedQuery)` checks on
+  class-composed results keep working.
+- Composed and wrapped value-form instances are subclasses of the
+  configured base classes (`Quo.relation_backed_query_base_class`,
+  `Quo.collection_backed_query_base_class` — typically
+  `ApplicationRelationQuery` / `ApplicationCollectionQuery`). Anything
+  defined on those base classes is available on `.from`-constructed and
+  instance-composed values. The base classes are resolved at autoload
+  time, so configure `Quo.relation_backed_query_base_class = ...`
+  in an initializer (it runs before eager load / first reference in
+  Rails apps).
+
+### What's intentionally different
+
+#### 1. Prop fan-out at instance composition is gone
+
+In 1.x, `(Q1.new(score: 0.5) + Q2.new(score: 0.7))` produced a merged
+class whose effective `score` was 0.7 (right won) and that value was
+fanned to every child at unwrap time.
+
+In 2.x, each operand keeps its own constructor-time props. The merged
+relation is the AND of both operands' filters, evaluated independently:
+
+```ruby
+# 1.x: filter = (score < 0.7 AND score < 0.7)  -> score < 0.7
+# 2.x: filter = (score < 0.5 AND score < 0.7)  -> score < 0.5
+```
+
+If you relied on 1.x's "right wins everywhere" behaviour, you now need
+to construct the leaf with the value you actually want:
+
+```ruby
+# Equivalent to 1.x's behaviour
+Q1.new(score: 0.7) + Q2.new(score: 0.7)
+```
+
+#### 2. Pagination inherits as a coupled (page, page_size) pair
+
+In 1.x, `page` and `page_size` were fanned independently, so a composed
+query could end up with `page: 2` from the left operand and
+`page_size: 50` from the right, even though neither operand was
+constructed with that pair.
+
+In 2.x, pagination inherits *as a unit* from whichever operand is
+paginated (i.e. has a non-nil `page`). Right wins if both are.
+`page_size` alone doesn't make a query paginated, because every
+Quo::Query has a default `page_size`.
+
+If you previously relied on the cross-pollination behaviour, set
+pagination explicitly on the composed instance:
+
+```ruby
+(q1 + q2).copy(page: 1, page_size: 50).results
+```
+
+#### 3. `wrap` is type-strict at definition time
+
+`Quo::RelationBackedQuery.wrap(x)` now raises `ArgumentError` at call
+time if `x` is not an `ActiveRecord::Relation` or a
+`Quo::RelationBackedQuery` instance. Same for
+`Quo::CollectionBackedQuery.wrap(x)` — `x` must be an `Enumerable` or a
+`Quo::CollectionBackedQuery` instance. Previously these would silently
+accept the wrong type and fail later at `.unwrap` / `.results` time,
+often with a confusing error.
+
+Block forms still defer the check to first call (the block body can
+return anything until it's evaluated).
+
+If you were relying on cross-type wrapping (e.g. handing an array to
+`RelationBackedQuery.wrap`), use the matching constructor:
+
+- in-memory collection → `Quo::CollectionBackedQuery.wrap(arr)` or
+  `Quo::CollectionBackedQuery.from(arr)`
+- AR relation → `Quo::RelationBackedQuery.wrap(rel)` or
+  `Quo::RelationBackedQuery.from(rel)`
+
+#### 4. Minimum Rails 8
+
+Quo 2.x requires `activerecord >= 8.0` and `activesupport >= 8.0`. For
+Rails 7.x, stay on Quo 1.x.
+
+### What's new
+
+#### `.from` — value-form constructors
+
+For wrapping a bare relation or enumerable as a Quo::Query at a call
+site, use `.from` instead of `wrap(...).new`:
+
+```ruby
+# 1.x — still works, but allocates a new class per call.
+Quo::RelationBackedQuery.wrap(Comment.where(read: false)).new.results
+
+# 2.x — value form, no Class.new per call.
+Quo::RelationBackedQuery.from(Comment.where(read: false)).results
+
+# Same for collections.
+Quo::CollectionBackedQuery.from([1, 2, 3]).results
+```
+
+`.from` returns an instance of `Quo::WrappedRelationBackedQuery` /
+`Quo::WrappedCollectionBackedQuery`. They behave like any other
+Quo::Query — composable, paginatable, transformable.
+
+Keep using `wrap` when you want a *class* (constant assignment, block
+form with typed props):
+
+```ruby
+# Still right in 2.x — type-defining use.
+RecentComments = Quo::RelationBackedQuery.wrap(props: {since: Time}) do
+  Comment.where("created_at > ?", since)
+end
+RecentComments.new(since: 1.day.ago).results
+```
+
+The skill bundled with Quo (`bin/rails generate quo:install`) covers
+the class-vs-instance composition cut and the new `.from` API.
+
+### Performance
+
+Measured on a representative 3-leaf instance composition (5000
+iterations of `(L.new + R.new + T.new).unwrap.to_sql`):
+
+| metric              | 1.0.0       | 2.0.0       | Δ           |
+|---------------------|-------------|-------------|-------------|
+| wall                | 3805 ms     | 1740 ms     | 2.2× faster |
+| GC time             | 238 ms      | 61 ms       | 4× less     |
+| total allocations   | 8,000,091   | 4,755,036   | -41%        |
+| T_CLASS allocations | 753         | **0**       | -100%       |
+
+The "zero T_CLASS per call" is the structural win — instance
+composition no longer goes through `Class.new`.
+
+### Migrating
+
+For most apps, just bumping the gem version and running tests is
+sufficient. If tests fail, they'll fall into one of these categories:
+
+1. **Test asserted 1.x's prop-fan-out "right wins at unwrap time".**
+   Update the test to reflect the new behaviour (filter is the AND of
+   each operand's own filter) or restructure your call site to
+   construct each leaf with the values you want.
+
+2. **Test asserted the cross-pollinated pagination behaviour.** Set
+   pagination explicitly on the composed instance, not at the leaf
+   level.
+
+3. **Test calls `composed.copy(some_user_prop:)` and expects a single
+   prop value to be observed.** v2's copy applies the new value to
+   every operand that declares the prop (right-wins precedence on
+   reads when both have it). Behaviour matches if you wanted "this
+   value, everywhere". If you wanted "this value on one side only",
+   construct the new operand explicitly: `q.copy(left: q.left.copy(prop: x))`.
+
+### Performance opportunities
+
+After upgrading, scan for these patterns and consider rewriting:
+
+- `Quo::RelationBackedQuery.wrap(some_relation).new` → use
+  `Quo::RelationBackedQuery.from(some_relation)`.
+- `(Q1 + Q2).new(prop: value)` at a call site → if `Q1` and `Q2` are
+  classes, this still allocates a new class per request. Either hoist
+  the composition to a constant (`MyType = Q1 + Q2`) and instantiate
+  `MyType.new(...)` per request, or switch to instance composition
+  (`Q1.new(prop: value) + Q2.new(...)` ).
+
+Both patterns are clearly explained in the bundled skill — see
+`.claude/skills/quo/SKILL.md` after running `bin/rails generate quo:install`.

data/badges/coverage_badge_total.svg

@@ -0,0 +1,35 @@
+<svg contentScriptType="text/ecmascript" contentStyleType="text/css" preserveAspectRatio="xMidYMid meet" version="1.0" height="20" width="120"
+  xmlns="http://www.w3.org/2000/svg"
+  xmlns:xlink="http://www.w3.org/1999/xlink">
+
+
+<linearGradient id="smooth" x2="0" y2="120">
+<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+<stop offset="1" stop-opacity=".1"/>
+</linearGradient>
+<clipPath id="round">
+<rect height="20" width="120" rx="3" fill="#ffffcc"/>
+</clipPath>
+<g clip-path="url(#round)">
+<rect height="20" width="60" fill="#555"/>
+<rect x="60" height="20" width="60" fill="#cccc00"/>
+<rect height="20" width="120" fill="url(#smooth)"/>
+</g>
+<g fill="#fff" text-anchor="middle" font-family="Verdana,sans-serif" font-size="11">
+<text x="30" y="15" fill="#010101" fill-opacity="0.3">
+scov total
+</text>
+<text x="30" y="14">
+scov total
+</text>
+</g>
+<g fill="#fff" text-anchor="middle" font-family="Verdana,sans-serif" font-size="11">
+<text x="90" y="15" fill="#010101" fill-opacity="0.3">
+96%
+</text>
+<text x="90" y="14">
+96%
+</text>
+</g>
+
+</svg>

data/badges/rubycritic_badge_score.svg

@@ -0,0 +1,35 @@
+<svg contentScriptType="text/ecmascript" contentStyleType="text/css" preserveAspectRatio="xMidYMid meet" version="1.0" height="20" width="200"
+  xmlns="http://www.w3.org/2000/svg"
+  xmlns:xlink="http://www.w3.org/1999/xlink">
+
+
+<linearGradient id="smooth" x2="0" y2="200">
+<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+<stop offset="1" stop-opacity=".1"/>
+</linearGradient>
+<clipPath id="round">
+<rect height="20" width="200" rx="3" fill="#fff"/>
+</clipPath>
+<g clip-path="url(#round)">
+<rect height="20" width="100" fill="#555"/>
+<rect x="100" height="20" width="100" fill="#ff0000"/>
+<rect height="20" width="200" fill="url(#smooth)"/>
+</g>
+<g fill="#fff" text-anchor="middle" font-family="Verdana,sans-serif" font-size="11">
+<text x="50" y="15" fill="#010101" fill-opacity="0.3">
+rubycritic score
+</text>
+<text x="50" y="14">
+rubycritic score
+</text>
+</g>
+<g fill="#fff" text-anchor="middle" font-family="Verdana,sans-serif" font-size="11">
+<text x="150" y="15" fill="#010101" fill-opacity="0.3">
+87.73/100.0
+</text>
+<text x="150" y="14">
+87.73/100.0
+</text>
+</g>
+
+</svg>

data/claude-skill/README.md

@@ -0,0 +1,100 @@
+# Claude Code skill: Quo
+
+A [Claude Code](https://claude.com/claude-code) skill that teaches Claude
+how to use the [Quo gem](https://github.com/stevegeek/quo) for building
+composable, type-safe query objects in a Rails application.
+
+## What this skill provides
+
+`SKILL.md` (loaded automatically by Claude Code) covers:
+
+- The two composition modes (class vs instance) and when to use each
+- Core query object patterns for ActiveRecord and collections
+- Type-safe property declarations using Literal
+- Pagination, transformer, and `wrap` patterns
+- A short cookbook of common patterns
+
+`references/` (loaded on demand by Claude when it needs depth):
+
+| File | Read when… |
+|---|---|
+| `references/QUERY_TYPES.md` | Detail on RelationBackedQuery vs CollectionBackedQuery |
+| `references/COMPOSITION.md` | Composition modes, merge strategies, joins, conditional building |
+| `references/PAGINATION.md` | Page navigation, counts, unpaginated access |
+| `references/TRANSFORMERS.md` | Result transformation, presenter patterns |
+| `references/API_REFERENCE.md` | Method-by-method reference for queries and results |
+
+## Versioning
+
+Each markdown file in this skill carries a banner near the top declaring
+which Quo version it targets, e.g.:
+
+> **Targets Quo `~> 2.0`.**
+
+When you upgrade the gem, re-run the install generator with `--force` to
+refresh the skill content:
+
+```bash
+bin/rails generate quo:install --force
+```
+
+## Installation
+
+The intended path is the bundled Rails generator (ships with Quo `~> 2.0`):
+
+```bash
+bin/rails generate quo:install
+```
+
+This copies the skill into your app's `.claude/skills/quo/` directory.
+Claude Code picks it up automatically on the next session.
+
+You can also install manually by copying this directory to
+`.claude/skills/quo/` in your project root.
+
+### CLAUDE.md fragment
+
+The generator can optionally append a "Quo" section to your project's
+top-level `CLAUDE.md`, telling Claude that the project uses Quo and
+where the skill lives. This is opt-in:
+
+```bash
+bin/rails generate quo:install --with-claude-md
+```
+
+If you prefer to manage `CLAUDE.md` by hand, just add a line like:
+
+```markdown
+## Quo
+
+This project uses the Quo gem for query objects. See
+`.claude/skills/quo/SKILL.md` for usage guidance.
+```
+
+## How it works
+
+When Claude Code starts a session, it loads `SKILL.md` automatically.
+That makes the core concepts and quick references immediately available
+in context. When Claude needs depth on a specific topic, it reads the
+relevant file from `references/` on demand.
+
+The skill is organised around progressive disclosure: keep `SKILL.md`
+short and grep-friendly; put the long detail in references.
+
+## Contributing
+
+To improve this skill:
+
+1. Edit the relevant markdown file
+2. Keep `SKILL.md` concise — quick references and patterns
+3. Put detailed material in the `references/` files
+4. Update the version banner if the API surface you describe changed
+5. Use the `Post` / `Author` / `Comment` fixture models from the gem's
+   own test suite for examples — they're verifiable against the gem's
+   tests and avoid project-specific terminology
+
+## Related
+
+- Quo source: <https://github.com/stevegeek/quo>
+- Quo documentation site: <https://quo-gem.diaconou.com/>
+- Literal (type system): <https://github.com/joeldrapper/literal>