with_model 2.1.7 → 2.3.0

data/lib/with_model/descendants_tracker.rb

@@ -0,0 +1,87 @@
+require "active_support/descendants_tracker"
+
+module WithModel
+  # Based on https://github.com/rails/rails/blob/491afff27e2dd3d5f301b478b9a43d3c31709af8/activesupport/lib/active_support/descendants_tracker.rb
+  module DescendantsTracker
+    if RUBY_ENGINE == "ruby"
+      # On MRI `ObjectSpace::WeakMap` keys are weak references.
+      # So we can simply use WeakMap as a `Set`.
+      class WeakSet < ObjectSpace::WeakMap # :nodoc:
+        alias_method :to_a, :keys
+
+        def <<(object)
+          self[object] = true
+        end
+      end
+    else
+      # On TruffleRuby `ObjectSpace::WeakMap` keys are strong references.
+      # So we use `object_id` as a key and the actual object as a value.
+      #
+      # JRuby for now doesn't have Class#descendant, but when it will, it will likely
+      # have the same WeakMap semantic than Truffle so we future proof this as much as possible.
+      class WeakSet # :nodoc:
+        def initialize
+          @map = ObjectSpace::WeakMap.new
+        end
+
+        def [](object)
+          @map.key?(object.object_id)
+        end
+        alias_method :include?, :[]
+
+        def []=(object, _present)
+          @map[object.object_id] = object
+        end
+
+        def to_a
+          @map.values
+        end
+
+        def <<(object)
+          self[object] = true
+        end
+      end
+    end
+    @excluded_descendants = WeakSet.new
+
+    class << self
+      def clear(classes) # :nodoc:
+        classes.each do |klass|
+          @excluded_descendants << klass
+          klass.descendants.each do |descendant|
+            @excluded_descendants << descendant
+          end
+        end
+      end
+
+      def reject!(classes) # :nodoc:
+        if @excluded_descendants
+          classes.reject! { |d| @excluded_descendants.include?(d) }
+        end
+        classes
+      end
+    end
+
+    module DestroyedClassesFiltering
+      def subclasses
+        WithModel::DescendantsTracker.reject!(super)
+      end
+
+      def descendants
+        WithModel::DescendantsTracker.reject!(super)
+      end
+    end
+  end
+end
+
+class ActiveRecord::Base
+  extend WithModel::DescendantsTracker::DestroyedClassesFiltering
+end
+
+module ActiveSupport
+  module DescendantsTracker
+    class << self
+      attr_reader :clear_disabled
+    end
+  end
+end

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.

data/lib/with_model/model.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
-require 'active_record'
-require 'active_support/core_ext/string/inflections'
-require 'English'
-require 'with_model/constant_stubber'
-require 'with_model/methods'
-require 'with_model/table'
+require "logger"
+require "active_record"
+require "active_support/core_ext/string/inflections"
+require "English"
+require "with_model/constant_stubber"
+require "with_model/descendants_tracker"
+require "with_model/methods"
+require "with_model/invalid_superclass"
+require "with_model/missing_superclass"
+require "with_model/null_table"
+require "with_model/table"
 
 module WithModel
   # In general, direct use of this class should be avoided. Instead use
@@ -14,17 +19,43 @@ module WithModel
     attr_writer :model_block, :table_block, :table_options
 
     # @param [Symbol] name The constant name to assign the model class to.
-    # @param [Class] superclass The superclass for the created class. Should
-    #   have `ActiveRecord::Base` as an ancestor.
+    # @param superclass The superclass for the created class. Either a Class
+    #   having `ActiveRecord::Base` as an ancestor, a String naming one, or a
+    #   callable returning one. A String or callable is resolved afresh for
+    #   every example, which is what allows another `with_model` model - whose
+    #   constant does not exist when this line is read - to be the superclass.
     def initialize(name, superclass: ActiveRecord::Base)
       @name = name.to_sym
       @model_block = nil
       @table_block = nil
       @table_options = {}
-      @superclass = superclass
+      @table_specified = false
+      @skip_table = false
+      @superclass_spec = superclass
     end
 
+    # Records what {WithModel::Model::DSL#table} was asked for, including the
+    # fact that it was asked for at all.
+    def specify_table(options, block)
+      @table_specified = true
+
+      if options == false
+        raise ArgumentError, "table does not take a block when its first argument is falsy" if block
+
+        @skip_table = true
+      else
+        @table_options = options
+        @table_block = block
+      end
+    end
+
+    # Whether a table was specified at all. A `table` call with no arguments
+    # counts, so this cannot be inferred from the options and block alone.
+    def table_specified? = @table_specified
+
     def create
+      @superclass = resolve_superclass
+      @table = nil
       table.create
       @model = Class.new(@superclass) do
         extend WithModel::Methods
@@ -34,35 +65,76 @@ module WithModel
     end
 
     def destroy
+      # Test runners tear down even when setup raised, so `create` may not have
+      # reached the point of building the model. Nothing was stubbed and nothing
+      # wrote rows, so there is nothing to undo.
+      return unless @model
+
+      # Before `unstub_const`: a teardown that identifies this model's own rows
+      # can only do so while the class still has its name.
+      table.teardown(@model)
       stubber.unstub_const
       cleanup_descendants_tracking
       reset_dependencies_cache
-      table.destroy
+      WithModel::DescendantsTracker.clear([@model])
       @model = nil
     end
 
     private
 
+    def resolve_superclass
+      spec = @superclass_spec
+      spec = spec.call if spec.respond_to?(:call)
+      spec = constantize_superclass(spec) if class_name?(spec)
+
+      unless spec.is_a?(Class) && spec <= ActiveRecord::Base
+        raise InvalidSuperclass,
+          "superclass must be a Class descending from ActiveRecord::Base, but was #{spec.inspect}. " \
+          "To refer to another with_model class, or anything else that is only defined once the " \
+          "test is running, name it with a String or a Symbol, or pass a callable returning it."
+      end
+
+      spec
+    end
+
+    # A Symbol reads naturally here, since with_model names its own models with
+    # them. Anything else has to answer to `to_str`, which only real strings do:
+    # every object has a `to_s`, so accepting that would quietly look up a
+    # constant named "42".
+    def class_name?(spec)
+      spec.is_a?(Symbol) || spec.respond_to?(:to_str)
+    end
+
+    # `to_s` is safe here where `class_name?` has already vouched for the value,
+    # and it keeps the Symbol intact for the message below, which reports what was
+    # passed in rather than what it was converted to.
+    #
+    # The NameError is worth quoting rather than replacing: for a namespaced name
+    # it reports which segment was missing, which this message cannot work out.
+    # Raising inside the rescue leaves it as the `cause` for anything that wants
+    # the backtrace.
+    def constantize_superclass(name)
+      name.to_s.constantize
+    rescue NameError => e
+      raise MissingSuperclass,
+        "superclass #{name.inspect} could not be resolved: #{e.message}. Names are resolved while " \
+        "the test is running, so a with_model superclass has to be declared before the models " \
+        "that inherit it."
+    end
+
     def const_name
       @name.to_s.camelize.to_sym
     end
 
     def setup_model
-      @model.table_name = table_name
+      table.configure(@model)
       @model.class_eval(&@model_block) if @model_block
       @model.reset_column_information
     end
 
     def cleanup_descendants_tracking
-      if defined?(ActiveSupport::DescendantsTracker)
-        if ActiveSupport::VERSION::MAJOR >= 7
-          ActiveSupport::DescendantsTracker.clear([@model])
-        else
-          ActiveSupport::DescendantsTracker.class_variable_get(:@@direct_descendants).delete(ActiveRecord::Base)
-        end
-      elsif @model.superclass.respond_to?(:direct_descendants)
-        @model.superclass.direct_descendants.delete(@model)
-      end
+      ActiveSupport::DescendantsTracker.clear([@model]) \
+        unless ActiveSupport::DescendantsTracker.clear_disabled
     end
 
     def reset_dependencies_cache
@@ -76,7 +148,11 @@ module WithModel
     end
 
     def table
-      @table ||= Table.new table_name, @table_options, &@table_block
+      @table ||= if @skip_table
+        NullTable.new(@superclass, @name)
+      else
+        Table.new table_name, @table_options, connection: @superclass.connection, &@table_block
+      end
     end
 
     def table_name

data/lib/with_model/null_table.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "with_model/invalid_superclass"
+
+module WithModel
+  # Stands in for a {WithModel::Table} when a model should inherit its
+  # superclass's table instead of getting one of its own, as Rails Single Table
+  # Inheritance requires. Selected by `table(false)`.
+  #
+  # In general, direct use of this class should be avoided. Instead use
+  # either the {WithModel high-level API} or {WithModel::Model::DSL low-level API}.
+  class NullTable
+    # @param [Class] superclass The resolved superclass whose table will be
+    #   inherited.
+    # @param [Symbol, String] name The model's name, so that a refusal can say
+    #   which model it is talking about.
+    def initialize(superclass, name)
+      @superclass = superclass
+      @name = name
+    end
+
+    # Creates nothing, but refuses a superclass that cannot support single
+    # table inheritance.
+    #
+    # Refusals describe the model's situation rather than the call that produced
+    # it. Any expression that evaluates to false selects a NullTable, so there
+    # is no call spelling to quote - and in with_model 3.0, omitting `table`
+    # will arrive here too.
+    #
+    # A superclass whose table does not exist *yet* is deliberately allowed: the
+    # table may be created later in the example, and a test may legitimately
+    # want a model whose table is missing. Active Record raises a clear
+    # `StatementInvalid` naming the table if it never appears, so refusing here
+    # would only forbid working setups.
+    #
+    # What is left is {WithModel::InvalidSuperclass}: both refusals are permanent
+    # facts about the superclass passed in, not about when it was looked at, so no
+    # amount of waiting makes them work.
+    def create
+      refuse "#{@superclass} has none to inherit" unless table_name?
+
+      # Nothing more can be checked until there is a table to look at.
+      return unless table_exists?
+      return if inheritance_column?
+
+      refuse "#{@superclass}'s table #{@superclass.table_name.inspect} has no " \
+             "#{inheritance_column.inspect} column, so Active Record cannot tell its rows " \
+             "apart from a subclass's"
+    end
+
+    # Deliberately does nothing: leaving `table_name` unassigned is what lets
+    # Active Record's own inheritance supply the superclass's table.
+    def configure(klass)
+    end
+
+    # Removes the rows this model wrote, which would otherwise outlive the
+    # constant that names them and make the superclass unloadable
+    # (`ActiveRecord::SubclassNotFound`).
+    #
+    # `unscoped` is required because a `default_scope` on the superclass would
+    # otherwise hide rows from the delete; the inheritance-column condition is
+    # then reapplied explicitly, since `unscoped` also discards the type
+    # condition that keeps this from touching the superclass's own rows.
+    #
+    # A table that does not exist holds no rows to remove, and failing here
+    # would fail an example whose body had already passed.
+    def teardown(klass)
+      return unless klass.table_exists?
+
+      klass.unscoped.where(klass.inheritance_column => klass.sti_name).delete_all
+    end
+
+    # Drops nothing; there is no table of our own to drop.
+    def destroy
+    end
+
+    private
+
+    def inheritance_column = @superclass.inheritance_column
+
+    # `ActiveRecord::Base` and abstract classes alike have no `table_name`, so
+    # this is what "nothing to inherit" actually looks like - `abstract_class?`
+    # is false for `ActiveRecord::Base` and so does not describe both.
+    def table_name? = @superclass.table_name.present?
+
+    def table_exists? = @superclass.table_exists?
+
+    def inheritance_column?
+      inheritance_column.present? && @superclass.columns_hash.key?(inheritance_column)
+    end
+
+    def refuse(problem)
+      raise InvalidSuperclass,
+        "with_model #{@name.inspect} has no table of its own, but #{problem}"
+    end
+  end
+end

data/lib/with_model/table.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'active_record'
+require "active_record"
 
 module WithModel
   # In general, direct use of this class should be avoided. Instead use
@@ -8,12 +8,14 @@ module WithModel
   class Table
     # @param [Symbol] name The name of the table to create.
     # @param options Passed to ActiveRecord `create_table`.
+    # @param connection The connection to use for creating the table.
     # @param block Passed to ActiveRecord `create_table`.
     # @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table
-    def initialize(name, options = {}, &block)
+    def initialize(name, options = {}, connection: ActiveRecord::Base.connection, &block)
       @name = name.freeze
       @options = options.freeze
       @block = block
+      @connection = connection
     end
 
     # Creates the table with the initialized options. Drops the table if
@@ -23,12 +25,26 @@ module WithModel
       connection.create_table(@name, **@options, &@block)
     end
 
+    # Points the model at this table.
+    def configure(klass)
+      klass.table_name = @name
+    end
+
+    # Removes everything this table holds by dropping it. The model is not
+    # needed, but is accepted so that {WithModel::NullTable} - which does need
+    # it - can stand in here.
+    def teardown(_klass)
+      destroy
+    end
+
     def destroy
       connection.drop_table(@name)
     end
 
     private
 
+    attr_reader :connection
+
     def exists?
       if connection.respond_to?(:data_source_exists?)
         connection.data_source_exists?(@name)
@@ -36,9 +52,5 @@ module WithModel
         connection.table_exists?(@name)
       end
     end
-
-    def connection
-      ActiveRecord::Base.connection
-    end
   end
 end

data/lib/with_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WithModel
-  VERSION = '2.1.7'
+  VERSION = "2.3.0"
 end

data/lib/with_model.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
-require 'with_model/model'
-require 'with_model/model/dsl'
-require 'with_model/table'
-require 'with_model/version'
+require "active_support/deprecation"
+require "with_model/invalid_superclass"
+require "with_model/missing_superclass"
+require "with_model/model"
+require "with_model/model/dsl"
+require "with_model/null_table"
+require "with_model/table"
+require "with_model/version"
 
 module WithModel
   class MiniTestLifeCycle < Module
     def initialize(object)
+      # Each with_model includes a fresh module, so the last one declared sits
+      # earliest in the ancestor chain. Calling super() first means setup runs
+      # in declaration order while teardown unwinds in reverse, which is what
+      # lets one with_model refer to another declared above it.
       define_method :before_setup do
-        object.create
         super() if defined?(super)
+        object.create
       end
 
       define_method :after_teardown do
@@ -32,6 +40,14 @@ module WithModel
     @runner ||= :rspec
   end
 
+  # The deprecator used for with_model's own deprecation warnings. Callers can
+  # silence it (`WithModel.deprecator.silenced = true`) or escalate it
+  # (`behavior = :raise`) while migrating, and Rails applications can register
+  # it in `Rails.application.deprecators`.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("3.0", "with_model")
+  end
+
   # @param [Symbol] name The constant name to assign the model class to.
   # @param scope Passed to `before`/`after` in the test context. RSpec only.
   # @param options Passed to {WithModel::Model#initialize}.
@@ -41,6 +57,8 @@ module WithModel
     model = Model.new name, **options
     dsl = Model::DSL.new model
     dsl.instance_exec(&block) if block
+    # caller_locations(1) is this method's caller: the `with_model` line itself.
+    WithModel.warn_omitted_table(name, caller_locations(1)) unless model.table_specified?
 
     setup_object(model, scope: scope, runner: runner)
   end
@@ -56,12 +74,32 @@ module WithModel
     setup_object(table, scope: scope, runner: runner)
   end
 
+  # Warns once per call site, at definition time, rather than once per example.
+  # The horizon is stated in the message because `Deprecation#warn` does not
+  # interpolate the deprecator's `deprecation_horizon`.
+  #
+  # The callstack has to be handed in. `ActiveSupport::Deprecation` skips Rails'
+  # own frames and the standard library when working out where a warning came
+  # from, but with_model's frames look like anyone else's to it, so left to itself
+  # it reports this file for every omission in a suite.
+  #
+  # @param callstack Frames to blame, beginning with the caller to report.
+  def self.warn_omitted_table(name, callstack)
+    deprecator.warn(
+      "with_model #{name.inspect} was called without a `table`, which creates a table with only " \
+      "an id column. In with_model 3.0 no table will be created. Call `table` (with no " \
+      "arguments or an empty block) to keep a table, or `table(false)` to inherit the " \
+      "superclass's table (single table inheritance).",
+      callstack
+    )
+  end
+
   private
 
   # @param [Object] object The new model object instance to create
   # @param scope Passed to `before`/`after` in the test context. Rspec only.
   # @param [Symbol] runner The test running, either :rspec or :minitest, defaults to :rspec
-  def setup_object(object, scope: nil, runner: nil) # rubocop:disable Metrics/MethodLength
+  def setup_object(object, scope: nil, runner: nil)
     case runner || WithModel.runner
     when :rspec
       before(*scope) do
@@ -76,7 +114,7 @@ module WithModel
         include MiniTestLifeCycle.call(object)
       end
     else
-      raise ArgumentError, 'Unsupported test runner set, expected :rspec or :minitest'
+      raise ArgumentError, "Unsupported test runner set, expected :rspec or :minitest"
     end
   end
 end