with_model 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 809e5984c60e2fa27b71d3d3ce7664feae0a3b2c7a59f345e2a94a819affb623
-  data.tar.gz: 5e8b519ef7d338aa754755efd065af68b718e6dc1f96fe27632266752e7b4990
+  metadata.gz: 0bac7bd2d2e529887f1e9bd82117cc809f23b336a8acaa2b90e4fb9305c96fe2
+  data.tar.gz: 1867b36f42957d744858fcefe70f53c58b0c5f39b951a4749a969c39c46b42f0
 SHA512:
-  metadata.gz: cf09e4aabe724638f054a54199d62a61ae9efd0cca28485412f85fd082a99f104d4f538bd7041f1777c9380398e7d1497d5f01dcc07cb5fdacc116ad3e7dd69f
-  data.tar.gz: 6f795b756e9b33abd148d51010a0afb80e01660af35c76d1a98a634c6b2d31c38a616e94aeff99c6d8b19b019c69b994c9b5dc21e69439fbbcb004528dc3606b
+  metadata.gz: eec34fe045c932273600775ccf7b2719dad1d10d6631baf43b9b7d54eec50bc4592d24cc1da1e9af7a844e7fbc73f707a0027d9f58c891afd18fb934e1f796d9
+  data.tar.gz: 5720ad24f60c91dee5b1eac354a0ca3d3f00d6c65e5d2f45fc76a310d6330564f43ec14924f168edc064121e9cc70b4ca7483c08a33587ea90f20031fff3fba2

data/.github/dependabot.yml

@@ -1,8 +1,24 @@
 version: 2
 updates:
-- package-ecosystem: bundler
-  directory: "/"
-  schedule:
-    interval: daily
-    time: "10:00"
-  open-pull-requests-limit: 10
+  # Gemfile.lock is not checked in and the Gemfile deliberately leaves versions
+  # to Bundler, so there is nothing here for Dependabot to bump routinely. It is
+  # listed to receive security advisories for the constraints that do exist.
+  - package-ecosystem: bundler
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: saturday
+    open-pull-requests-limit: 10
+
+  # The workflow pins actions by major version, which does not float across
+  # majors: actions/checkout sat four majors behind until someone noticed by
+  # hand. One grouped pull request keeps them current without a PR per action.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: saturday
+    groups:
+      actions:
+        patterns:
+          - "*"

data/.github/workflows/ci.yml

@@ -6,50 +6,85 @@ on:
       - master
       - github-actions
   pull_request:
+  schedule:
+    - cron: "0 18 * * 6" # Saturdays at 12pm CST
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   test:
+    name: Ruby ${{ matrix.ruby-version }} / ${{ matrix.active-record.label }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     env:
       CI: true
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.1', '3.2', '3.3', '3.4']
-        active-record-version-env:
-          - ACTIVE_RECORD_VERSION="~> 7.0.0"
-          - ACTIVE_RECORD_VERSION="~> 7.1.0"
-          - ACTIVE_RECORD_VERSION="~> 7.2.0"
-          - ACTIVE_RECORD_VERSION="~> 8.0.0"
+        ruby-version: ["3.3", "3.4", "4.0"]
+        active-record:
+          - label: AR 7.2
+            env: ACTIVE_RECORD_VERSION=~> 7.2.0
+          - label: AR 8.0
+            env: ACTIVE_RECORD_VERSION=~> 8.0.0
+          - label: AR 8.1
+            env: ACTIVE_RECORD_VERSION=~> 8.1.0
         allow-failure: [false]
-        exclude:
-          - ruby-version: '3.1'
-            active-record-version-env: ACTIVE_RECORD_VERSION="~> 8.0.0"
         include:
-          - ruby-version: '3.4'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="main"
+          - ruby-version: "4.0"
+            active-record:
+              label: AR main
+              env: ACTIVE_RECORD_BRANCH=main
             allow-failure: true
-          - ruby-version: '3.4'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="8-0-stable"
+          - ruby-version: "4.0"
+            active-record:
+              label: AR 8-1-stable
+              env: ACTIVE_RECORD_BRANCH=8-1-stable
             allow-failure: true
-          - ruby-version: '3.4'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-2-stable"
+          - ruby-version: "4.0"
+            active-record:
+              label: AR 8-0-stable
+              env: ACTIVE_RECORD_BRANCH=8-0-stable
             allow-failure: true
-          - ruby-version: '3.4'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-1-stable"
+          - ruby-version: "4.0"
+            active-record:
+              label: AR 7-2-stable
+              env: ACTIVE_RECORD_BRANCH=7-2-stable
             allow-failure: true
-          - ruby-version: '3.4'
-            active-record-version-env: ACTIVE_RECORD_BRANCH="7-0-stable"
+          # A canary for the next Ruby, which cannot fail the build.
+          - ruby-version: ruby-head
+            active-record:
+              label: AR 8.1
+              env: ACTIVE_RECORD_VERSION=~> 8.1.0
             allow-failure: true
     continue-on-error: ${{ matrix.allow-failure }}
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true
-    - name: Update bundle
-      run: ${{ matrix.active-record-version-env }} bundle update
-    - name: Run tests
-      run: ${{ matrix.active-record-version-env }} bin/rake
+      - uses: actions/checkout@v7
+      # Set the version here rather than prefixing each command, so the matrix
+      # value reaches the environment without being interpolated into a script.
+      - name: Select Active Record version
+        env:
+          ACTIVE_RECORD_ENV: ${{ matrix.active-record.env }}
+        run: echo "$ACTIVE_RECORD_ENV" >> "$GITHUB_ENV"
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+          cache-version: ${{ matrix.active-record.env }}
+      # Gemfile.lock is not checked in, so this resolves the newest gems that
+      # satisfy the Gemfile on each run rather than a recorded set. `--all` is
+      # what Bundler 4, shipped with Ruby 4.0, wants for that.
+      - name: Update bundle
+        run: bundle update --all
+      # Not bin/rake: bin/ holds generated binstubs and is not checked in, and
+      # whether bundling writes them there varies by Bundler version - Bundler 4
+      # does not, which left Ruby 4.0 with no binstub to run.
+      - name: Run tests
+        run: bundle exec rake

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+### 2.3.0
+
+- Add `table(false)` to create no table, so that a model whose superclass is a
+  concrete Active Record class uses single table inheritance.
+- Accept a String, a Symbol, or a callable for `superclass:`, resolved for each
+  example, so that another `with_model` model can be the superclass.
+- Raise `WithModel::InvalidSuperclass` for a `superclass:` that cannot be used,
+  and `WithModel::MissingSuperclass` for a name that resolves to nothing. Both
+  are `ArgumentError`s, and the latter is an `InvalidSuperclass`, so either can
+  be rescued as narrowly as needed.
+- Deprecate omitting `table`, which currently creates a table with only an id
+  column. In 3.0 it will create no table.
+- Create minitest models in the order they are declared, so that a model can
+  refer to another model declared above it.
+- Add support for Active Record 8.1.
+- Require Active Record 7.2 or later.
+- Add support for Ruby 4.0.
+- Require Ruby 3.3 or later.
+
 ### 2.2.0
 
 - Fix dependency tracking issue when `cache_classes: true` is set in Rails 7+.

data/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to with_model
+
+If you experience a bug, we welcome you to report it. Please include a minimal
+example showing the code you ran, what happened, and what you expected to happen
+instead — a failing `with_model` block is ideal, since it can be dropped straight
+into the suite. If you can fix the bug and open a pull request, it will get
+resolved sooner, but don't hesitate to report an issue you don't know how to fix.
+
+If you have a substantial feature in mind, consider opening an issue to discuss
+it first. We may have thought about it already, and can sometimes save you a
+detour.
+
+When in doubt, go ahead and open a pull request. If something needs rethinking,
+we will do our best to say so clearly. Don't be discouraged if we ask you to
+change your code — we appreciate the work, and we also have opinions about style
+and object design.
+
+## Supported versions
+
+The [gemspec](./with_model.gemspec) declares the minimum supported Ruby and
+Active Record, and the [CI workflow](./.github/workflows/ci.yml) lists every
+combination actually tested. It can be hard to try them all locally, so please
+avoid anything that only works on the newest of either.
+
+## Running the tests
+
+The suite runs against both supported test harnesses, so `with_model` has to work
+under each:
+
+- `spec/` covers behavior under RSpec.
+- `test/` covers the minitest life cycle — the setup and teardown hooks, and
+  their ordering — rather than repeating the specs.
+
+Run everything, including the linter, with:
+
+```sh
+bundle exec rake
+```
+
+`bin/` holds generated binstubs and is not checked in. Whether bundling writes
+them for you depends on your Bundler version, so create them once if you would
+rather type `bin/rake`:
+
+```sh
+bundle binstubs --all
+```
+
+Our automated tests begin by updating every gem to its newest version. That is
+deliberate: we would rather find out about an incompatibility from our own build
+than from a bug report. `Gemfile.lock` is not checked in, so you can do the same
+at any time with `bundle update --all`.
+
+To try a particular Active Record, set `ACTIVE_RECORD_VERSION` to a version
+requirement and update the bundle:
+
+```sh
+ACTIVE_RECORD_VERSION="~> 8.1.0" bundle update --all
+ACTIVE_RECORD_VERSION="~> 8.1.0" bundle exec rake
+```
+
+To test against Active Record from git instead — an unreleased branch, or `main`
+— set `ACTIVE_RECORD_BRANCH`:
+
+```sh
+ACTIVE_RECORD_BRANCH=main bundle update --all
+ACTIVE_RECORD_BRANCH=main bundle exec rake
+```
+
+Style is enforced by [Standard](https://github.com/standardrb/standard), which
+`rake` runs. To correct what it can:
+
+```sh
+bundle exec standardrb --fix
+```
+
+## Changes and releases
+
+Please add a line to `CHANGELOG.md` under `### Unreleased` describing your change
+from the point of view of someone using the gem. Leave `lib/with_model/version.rb`
+alone: version bumps and releases are cut separately by a maintainer, so a bump
+in a pull request only creates a conflict.
+
+Last, but not least, have fun.

data/Gemfile

@@ -9,7 +9,6 @@ ar_version = ENV.fetch("ACTIVE_RECORD_VERSION", nil)
 
 if ar_branch
   gem "activerecord", git: "https://github.com/rails/rails.git", branch: ar_branch
-  gem "arel", git: "https://github.com/rails/arel.git" if ar_branch == "master"
 elsif ar_version
   gem "activerecord", ar_version
 end
@@ -22,10 +21,6 @@ gem "minitest"
 gem "mutex_m"
 gem "rake"
 gem "rspec"
+gem "ruby-lsp"
+gem "sqlite3"
 gem "standard"
-
-if ar_branch == "7-0-stable" || ar_version == "~> 7.0.0"
-  gem "sqlite3", "< 2"
-else
-  gem "sqlite3"
-end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010–2022 Casebook, PBC <http://www.casebook.net>
+Copyright (c) 2010–2026 Casebook, PBC <http://www.casebook.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,7 @@
 # [with_model](https://github.com/Casecommons/with_model)
 
 [![Gem Version](https://img.shields.io/gem/v/with_model.svg?style=flat)](https://rubygems.org/gems/with_model)
-[![Build Status](https://github.com/Casecommons/with_model/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Casecommons/with_model/actions/workflows/ci.yml)
+[![Build Status](https://github.com/Casecommons/with_model/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Casecommons/with_model/actions/workflows/ci.yml?query=branch%3Amaster)
 [![API Documentation](https://img.shields.io/badge/yard-api%20docs-lightgrey.svg)](https://www.rubydoc.info/gems/with_model)
 
 `with_model` dynamically builds an Active Record model (with table) before each test in a group and destroys it afterwards.
@@ -19,7 +19,7 @@ Install as usual: `gem install with_model` or add `gem 'with_model'` to your Gem
 Extend `WithModel` into RSpec:
 
 ```ruby
-require 'with_model'
+require "with_model"
 
 RSpec.configure do |config|
   config.extend WithModel
@@ -31,7 +31,7 @@ end
 Extend `WithModel` into minitest/spec and set the test runner explicitly:
 
 ```ruby
-require 'with_model'
+require "with_model"
 
 WithModel.runner = :minitest
 
@@ -45,11 +45,16 @@ end
 After setting up as above, call `with_model` and inside its block pass it a `table` block and a `model` block.
 
 ```ruby
-require 'spec_helper'
+require "spec_helper"
 
-describe "A blog post" do
-  module MyModule; end
+module MyModule; end
+
+# A pre-existing model
+class Car < ActiveRecord::Base
+  self.abstract_class = true
+end
 
+describe "A blog post" do
   with_model :BlogPost do
     # The table block (and an options hash) is passed to Active Record migration’s `create_table`.
     table do |t|
@@ -60,15 +65,16 @@ describe "A blog post" do
     # The model block is the Active Record model’s class body.
     model do
       include MyModule
+
       has_many :comments
       validates_presence_of :title
 
       def self.some_class_method
-        'chunky'
+        "chunky"
       end
 
       def some_instance_method
-        'bacon'
+        "bacon"
       end
     end
   end
@@ -91,15 +97,15 @@ describe "A blog post" do
   end
 
   it "has the module" do
-    expect(BlogPost.include?(MyModule)).to eq true
+    expect(BlogPost.include?(MyModule)).to be true
   end
 
   it "has the class method" do
-    expect(BlogPost.some_class_method).to eq 'chunky'
+    expect(BlogPost.some_class_method).to eq "chunky"
   end
 
   it "has the instance method" do
-    expect(BlogPost.new.some_instance_method).to eq 'bacon'
+    expect(BlogPost.new.some_instance_method).to eq "bacon"
   end
 
   it "can do all the things a regular model can" do
@@ -107,22 +113,21 @@ describe "A blog post" do
     expect(record).not_to be_valid
     record.title = "foo"
     expect(record).to be_valid
-    expect(record.save).to eq true
+    expect(record.save).to be true
     expect(record.reload).to eq record
-    record.comments.create!(:text => "Lorem ipsum")
+    record.comments.create!(text: "Lorem ipsum")
     expect(record.comments.count).to eq 1
   end
 
-  # with_model classes can have inheritance.
-  class Car < ActiveRecord::Base
-    self.abstract_class = true
-  end
-
+  # with_model classes can have inheritance. Car is abstract, so it has no table
+  # and Ford gets one of its own. To inherit a concrete superclass's table
+  # instead, see "Single table inheritance" below.
   with_model :Ford, superclass: Car do
+    table
   end
 
   it "has a specified superclass" do
-    expect(Ford < Car).to eq true
+    expect(Ford.new).to be_a(Car)
   end
 end
 
@@ -150,8 +155,8 @@ end
 
 describe "with table options" do
   with_model :WithOptions do
-    table :id => false do |t|
-      t.string 'foo'
+    table id: false do |t|
+      t.string "foo"
       t.timestamps null: false
     end
   end
@@ -162,6 +167,89 @@ describe "with table options" do
 end
 ```
 
+## Single table inheritance
+
+Pass `table(false)` to create no table at all. Active Record's own inheritance
+then supplies the superclass's table, which is what single table inheritance
+needs.
+
+The superclass can be another `with_model` model. Its constant does not exist yet
+when the `superclass:` argument is read, so name it with a String or a Symbol, or
+pass a callable returning it, and it will be resolved once per example.
+
+```ruby
+describe "with_model supports Single Table Inheritance" do
+  with_model :Sandwich do
+    table do |t|
+      t.string "type"
+      t.string "bread"
+    end
+  end
+
+  with_model :ChunkyBacon, superclass: :Sandwich do
+    table(false)
+  end
+
+  it "shares the superclass's table" do
+    expect(ChunkyBacon.table_name).to eq Sandwich.table_name
+  end
+
+  it "stores its own type" do
+    sandwich = ChunkyBacon.create!(bread: "rye")
+
+    expect(sandwich.reload.type).to eq "ChunkyBacon"
+    expect(Sandwich.first).to be_a ChunkyBacon
+  end
+end
+```
+
+A `superclass:` that cannot be used raises `WithModel::InvalidSuperclass`: one
+that is not an Active Record class, one with no table of its own
+(`ActiveRecord::Base`, or an abstract class such as a Rails app's
+`ApplicationRecord`), or one whose table has no inheritance column to tell a
+subclass's rows apart. A name that resolves to nothing raises
+`WithModel::MissingSuperclass`, a kind of `InvalidSuperclass`, quoting the
+constant Ruby could not find — for a namespaced name, that is the segment which
+is actually missing. Both are `ArgumentError`s.
+
+A superclass whose table does not exist *yet* is allowed, since the table may be
+created later in the example, and Active Record reports its absence clearly
+enough on its own. Rows the model wrote are deleted when it goes away, since they
+name a class that is about to stop existing and would make the superclass
+unloadable.
+
+## Foreign keys
+
+`foreign_key: true` asks Active Record to infer the table a foreign key points
+at, and it infers `authors` from `author_id`. Generated table names are unique
+rather than conventional, so name the table instead:
+
+```ruby
+describe "with_model supports foreign keys" do
+  with_model :Author do
+    table
+  end
+
+  with_model :Book do
+    table do |t|
+      t.references :author, foreign_key: {to_table: Author.table_name}
+    end
+
+    model do
+      belongs_to :author
+    end
+  end
+
+  it "has a foreign key" do
+    expect { Book.create!(author_id: 0) }
+      .to raise_error ActiveRecord::InvalidForeignKey
+  end
+end
+```
+
+This reads `Author.table_name`, so declare `Author` first: models are created in
+the order they are declared, and destroyed in the reverse order.
+
 ## Requirements
 
 See the [gemspec metadata](https://rubygems.org/gems/with_model) for dependency requirements. RSpec and minitest are indirect dependencies, and `with_model` should support any maintained version of both.
@@ -177,11 +265,17 @@ See the [gemspec metadata](https://rubygems.org/gems/with_model) for dependency
 
 In general, `with_model` is not guaranteed to be thread-safe, but is, in certain usages, safe to use concurrently across multiple processes with a single database schema.
 
+## Contributing
+
+Bug reports and pull requests are welcome. See the
+[CONTRIBUTING guide](/CONTRIBUTING.md) for how to run the tests against a
+particular Ruby or Active Record.
+
 ## Versioning
 
 `with_model` uses [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html).
 
 ## License
 
-Copyright © 2010–2022 [Casebook PBC](https://www.casebook.net).
+Copyright © 2010–2026 [Casebook PBC](https://www.casebook.net).
 Licensed under the MIT license, see [LICENSE](/LICENSE) file.

data/lib/with_model/invalid_superclass.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module WithModel
+  # Raised when the `superclass:` a model was given cannot be used: it is not an
+  # Active Record class at all, or it is one that cannot supply a table to a model
+  # which has none of its own - because it has no table itself
+  # (`ActiveRecord::Base`, or an abstract class), or because its table has no
+  # inheritance column and so cannot tell a subclass's rows apart.
+  #
+  # An `ArgumentError`, because each is a fact about the argument rather than about
+  # when it was looked at, and the superclass is needed the moment the model is
+  # built - unlike a table, which an example is free to create later.
+  class InvalidSuperclass < ArgumentError
+  end
+end

data/lib/with_model/missing_superclass.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "with_model/invalid_superclass"
+
+module WithModel
+  # Raised when the name given for a `superclass:` resolves to nothing at all.
+  #
+  # A kind of {WithModel::InvalidSuperclass}, so every superclass that cannot be
+  # used is catchable in one place, while a name that is simply not there - a
+  # typo, or a with_model superclass declared after the models inheriting it -
+  # can be told apart from a class that exists but cannot supply a table.
+  class MissingSuperclass < InvalidSuperclass
+  end
+end

data/lib/with_model/model/dsl.rb

@@ -11,10 +11,13 @@ module WithModel
       # Provide a schema definition for the table, passed to ActiveRecord's `create_table`.
       # The table name will be auto-generated.
       #
+      # Pass `false` instead of options to create no table at all, so that the
+      # model inherits its superclass's table as Rails Single Table Inheritance
+      # requires. `table(false)` takes no block.
+      #
       # @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table
       def table(options = {}, &block)
-        @model.table_options = options
-        @model.table_block = block
+        @model.specify_table(options, block)
       end
 
       # Provide a class body for the ActiveRecord model.