required_scopes 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  metadata.gz: 4d5c01aa1fe08e48a58a5d0b04403fdb1776cde9
+  data.tar.gz: a5e438c3698e6def089b4d451bb4dc2651c00ad3
+SHA512: 
+  metadata.gz: 5dc8c8bc939f6932c84408f7dfcc4a5bcc811373a110919818dc3a0f94723b629cdf35913b7137997277dd6b959ed0affdc5345fecbaae85b3198d1bf6a0bf76
+  data.tar.gz: cccbab92e292d84397b6f8e29c102d0e8e136cccac43ca7c83e893f14644faed1e0b72d577b15e9388825c9bdd2734fa2dde63d9e4592cf61761f0a07661f2c5

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+/spec_database_config.rb*

data/.travis.yml

@@ -0,0 +1,29 @@
+before_install:
+    - gem install rubygems-update -v2.1.11
+    - gem update --system 2.1.11
+    - gem --version
+rvm:
+    - "1.8.7"
+    - "1.9.3"
+    - "2.0.0"
+    - "jruby-1.7.6"
+env:
+    - REQUIRED_SCOPES_AR_TEST_VERSION=3.2.16 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=mysql
+    - REQUIRED_SCOPES_AR_TEST_VERSION=3.2.16 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=postgres
+    - REQUIRED_SCOPES_AR_TEST_VERSION=3.2.16 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=sqlite
+    - REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=mysql
+    - REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=postgres
+    - REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=sqlite
+before_script:
+    # - export JRUBY_OPTS="-J-Xmx256m -J-Xms256m $JRUBY_OPTS"
+    - mysql -e 'create database myapp_test;'
+    - psql -c 'create database myapp_test;' -U postgres
+matrix:
+    exclude:
+        # ActiveRecord 4.x doesn't support Ruby 1.8.7
+        -   rvm: 1.8.7
+            env: REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=mysql
+        -   rvm: 1.8.7
+            env: REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=postgres
+        -   rvm: 1.8.7
+            env: REQUIRED_SCOPES_AR_TEST_VERSION=4.0.2 REQUIRED_SCOPES_TRAVIS_CI_DATABASE_TYPE=sqlite

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in required_scopes.gemspec
+gemspec
+
+ar_version = ENV['REQUIRED_SCOPES_AR_TEST_VERSION']
+ar_version = ar_version.strip if ar_version
+
+version_spec = case ar_version
+when nil then nil
+when 'master' then { :git => 'git://github.com/rails/activerecord.git' }
+else "=#{ar_version}"
+end
+
+if version_spec
+  gem("activerecord", version_spec)
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2014 Andrew Geweke
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,277 @@
+# RequiredScopes
+
+RequiredScopes keeps developers from being able to accidentally forget about critical scopes on database tables. For
+example:
+
+* If you provide software-as-a-service to many clients, forgetting to include the client ID in your query may leak
+  data from one client to another — potentially a truly disastrous thing to happen.
+* If you store time-series data in a table that gets very large, querying without including a time range can cause
+  huge scalability problems as you accidentally scan the entire table.
+* If you associate permissions with various records in a table, then forgetting to constrain on the permissions in a
+  query results in them being completely ineffective.
+* If you soft-delete records (via a `deleted_at` or `deleted` flag), forgetting to either explicitly include or exclude
+  deleted records can result in "deleted" data reappearing, which can be very bad.
+
+...and the list goes on.
+
+RequiredScopes works by letting you create one or more _required scope categories_, each named via a symbol
+(_e.g._, `:client_id`, `:time_range`, `:permissions`, or `:deleted`). You can then declare scopes (or class methods)
+as _satisfying_ one or more categories. When time comes to query the database, at least one scope satisfying each
+category must have been used, or else an exception will be raised.
+
+For example:
+
+    class StatusUpdate < ActiveRecord::Base
+      must_scope_by :client_id, :recency
+
+      scope :last_week, lambda { where("created_at >= ?", 1.week.ago) }, :satisfies => :recency
+      scope :last_month, lambda { where("created_at >= ?", 1.month.ago) }, :satisfies => :recency
+
+      class << self
+        def for_client(client_id)
+          where(:client_id => client_id).scope_category_satisfied(:client_id)
+        end
+      end
+    end
+
+    StatusUpdate.last(100)                 # => RequiredScopes::Errors::RequiredScopeCategoriesNotSatisfiedError
+    StatusUpdate.for_client(982).last_week # => [ <StatusUpdate id:321890414>, <StatusUpdate id:321890583>, ... ]
+
+There's much more, too. For example, it's trivial to skip these checks if you want &mdash; the idea is to keep
+developers from simply _forgetting_ about scoping, not to make their lives more difficult. See below, under **Usage**,
+for more information.
+
+#### As an alternative to `default_scope`
+
+RequiredScopes was actually born as an alternative to `default_scope`. Rails' `default_scope` is a great idea, but, in
+actual usage, we've seen it cause a surprisingly large number of bugs. (It works exactly the way it claims it does,
+but it turns out this isn't actually a great way for it to work.)
+
+What goes wrong? It turns out that there's almost never a single scope that you truly want applied 100%, or even 99%,
+of the time. Instead, it's more like 85%; but, because it's the default, developers almost always completely forget
+about it, and bugs result.
+
+For example, take the classic case of a `deleted_at` column on a User model, and
+`default_scope lambda { where('deleted_at IS NULL')} }`. This works great for most "normal" functions of the
+application. But, then, the edge cases start creeping in:
+
+* In your admin controllers, where you _want_ to be able to see deleted users, you keep forgetting to apply `#unscoped`
+  &mdash; and lots of errors on `nil` result.
+* When a new user signs up and chooses a username, you forget to unscope when checking if an existing user has that
+  username, resulting in database unique-index failures on `users.username` when creating a new user (and HTTP 500
+  pages returned to the end user).
+* Your "reset password" page almost certainly wants to find a user account even if it's deleted, and (at minimum)
+  display a message telling the user they have a deleted account. You don't want to act like the user simply doesn't
+  exist.
+
+The truth is, there _isn't_ a single default scope that can ever be safely applied across-the-board. Developers have to
+think about it, every single time. This isn't hard; it takes an extra second or two, and prevents hours of debugging
+time (and lots of user frustration at bugs that would've resulted). But base Rails only lets you decide to either apply
+a single `default_scope` across the board (where you run into the above problems) or not (where you run into even worse
+ones, as developers completely forget about your `deleted_at` column, or whatever).
+
+Hence, RequiredScopes. It prevents you from forgetting about critical scopes, yet doesn't try to shoehorn a single
+`default_scope` everywhere.
+
+#### Supported Versions
+
+RequiredScopes supports:
+
+* Ruby 1.8.7, 1.9.3, 2.0.0, 2.1.0, and JRuby 1.7.9.
+* ActiveRecord 3.2.x and 4.0.x.
+* Any database that works with ActiveRecord.
+
+Note that because RequiredScopes ties in quite tightly with ActiveRecord, supporting previous ActiveRecord versions
+would be significant work. Patches are always welcome. :-)
+
+Current build status: ![Current Build Status](https://api.travis-ci.org/ageweke/required_scopes.png?branch=master)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'required_scopes'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install required_scopes
+
+## Usage
+
+#### `base_scope_required!`, or, the simple version
+
+An example:
+
+    class User < ActiveRecord::Base
+      base_scope_required!
+
+      # #base_scope is just like #scope, except that it says "this scope satisfies base_scope_required!"
+      base_scope :deleted, lambda { where("deleted_at IS NOT NULL") }
+      base_scope :not_deleted, lambda { where("deleted_at IS NULL") }
+
+      # #scope does not satisfy the requirement
+      scope :young, lambda { where("age <= 20") }
+
+      class << self
+        def deleted_recently
+          # The call to #base_scope_satisfied says "the scope I'm returning satisfies #base_scope_required!"
+          where("deleted_at >= ?", 1.week.ago).base_scope_satisfied
+        end
+      end
+    end
+
+This sets up the following behavior:
+
+    # Forgetting the scope gives you an error
+    User.first                   # => RequiredScopes::Errors::BaseScopeNotSatisfiedError
+    User.young.first             # => RequiredScopes::Errors::BaseScopeNotSatisfiedError
+
+    # Any of the declared scopes work just fine
+    User.deleted.first           # => SELECT * FROM users WHERE deleted_at IS NOT NULL LIMIT 1
+    User.not_deleted.first       # => SELECT * FROM users WHERE deleted_at IS NULL LIMIT 1
+    User.deleted_recently.first  # => SELECT * FROM users WHERE deleted_at >= '2013-12-30 05:23:01.367705' LIMIT 1
+
+    # You can chain them like normal, and use them anywhere
+    User.where(:name => 'some user').not_deleted.first
+         # => SELECT * FROM users WHERE deleted_at IS NULL AND name = 'some user' LIMIT 1
+
+    # Pass them around, build on them...they work just like any other scope
+    s = User.where(:name => 'some user')
+    s.not_deleted.first
+         # => SELECT * FROM users WHERE deleted_at IS NULL AND name = 'some user' LIMIT 1
+    s.deleted.first
+         # => SELECT * FROM users WHERE deleted_at IS NOT NULL AND name = 'some user' LIMIT 1
+    s.deleted_recently.where("age > 20").first
+         # => SELECT * FROM users WHERE deleted_at >= '2013-12-30 05:23:01.367705' AND name = 'some user' AND age > 20 LIMIT 1
+
+    # The special scope "ignoring_base" is generated for you; it satisfies the requirement without constraining in any way
+    User.ignoring_base.first # => SELECT * FROM users LIMIT 1
+    # #base_scope_satisfied automatically satisfies the requirement, without constraining in any way
+    User.base_scope_satisfied.first      # => SELECT * FROM users LIMIT 1
+
+#### `must_scope_by`, or, the general case
+
+`base_scope_required!` and `base_scope` are actually just syntactic sugar on top of a more general system that lets
+you declare one or more _scope categories_ (each of which is just a symbol) and various scopes and class methods that
+_satisfy_ those categories.
+
+(`base_scope_required!` is exactly equivalent to `must_scope_by :base`, and `base_scope :foo, lambda { ... }` is
+exactly equivalent to `scope :foo, lambda { ... }, :satisfies => :base`.)
+
+For example:
+
+    class User < ActiveRecord::Base
+      must_scope_by :deleted, :client
+
+      scope :not_deleted, lambda { where("deleted_at IS NULL") }, :satisfies => :deleted
+      scope :deleted, lambda { where("deleted_at IS NOT NULL") }, :satisfies => :deleted
+
+      scope :admin_active, lambda { where("deleted_at IS NULL AND client_id = 0") }, :satisfies => [ :deleted, :client ]
+
+      class << self
+        def for_client(c)
+          where(:client_id => c.id).scope_category_satisfied(:client)
+        end
+
+        def active_for_client(c)
+          where(:client_id => c.id, :deleted_at => nil).scope_categories_satisfied(:client, :deleted)
+        end
+      end
+    end
+
+This sets up two categories of scopes that _both_ must be satisfied before you can query the database, `:deleted` and
+`:client`. The scopes `not_deleted` and `deleted` satisfy the `:deleted` category; the scope `admin_active` satisfies
+both. The class method `for_client` satisfies the `:client` category; the class method `active_for_client` satisfies
+both categories.
+
+For each required category, a special `ignoring` scope is automatically defined &mdash; `ignoring_deleted`
+and `ignoring_client` in the above example. This tells RequiredScopes that you're explicitly deciding _not_ to apply
+any scopes for the given category. So, while `User.not_deleted.first` will raise an exception complaining that you
+haven't satisfied the `:client` category, `User.not_deleted.ignoring_client.first` will run just fine, and will not
+constrain on client in any way.
+
+All scopes get methods called `#scope_category_satisfied` and `#scope_categories_satisfied`. (You can actually pass
+either a single scope or multiple scopes to either one.) These mark categories as satisfied, without constraining in
+any way; this is useful for class methods, as above, that should be considered to satisfy a requirement. They also
+function in block form, just like `#scoping` or `#unscoped` from ActiveRecord do:
+
+    User.scope_category_satisfied(:client) do
+      User.not_deleted.first # => SELECT * FROM users WHERE deleted_at IS NULL LIMIT 1
+    end
+
+Note that the built-in ActiveRecord `#unscoped` method does not interact with RequiredScopes in any way. Unscoping
+neither satisfies nor removes the satisfaction of any required categories.
+
+#### RequiredScopes and Inheritance
+
+If you use inheritance among your model classes, child classes will require any scope categories that their parents
+have declared to require; if you add a separate `must_scope_by` call in the child class, then it will additionally
+require those categories, too.
+
+If you do _not_ want a child class to require all the categories of its parent, call
+`ignore_parent_scope_requirement :client, :deleted` (or whatever categories you want to skip the requirement for) in
+the child class. This removes the requirement from the child class.
+
+#### How Smart Is It?
+
+It's important to note that RequiredScopes does not, in any way, _actually look at your `WHERE` clauses_. That is, the
+only thing it's doing is matching the categories you've said are required with scopes that satisfy those categories;
+it does not know or care what those scopes actually _do_.
+
+If you say a scope satisfies a category, then RequiredScopes will be happy with it, even if it actually just does
+`ORDER BY id ASC` (or does nothing at all!). If no scope is applied that satisfies a category, you'll get an error,
+even if you've constrained every column in seven different ways.
+
+This hopefully makes the entire system much easier to understand, but it's worth noting.
+
+#### Along With `default_scope`
+
+Note that RequiredScopes does not affect the behavior of `default_scope` in any way; if you declare a `default_scope`,
+it will still be used, as normal. `default_scope`s cannot satisfy any categories, however. (But this wouldn't make any
+sense, anyway: if your default scope satisfies a category, then it's really not required any more, is it?)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### Running Specs
+
+RequiredScopes is quite thoroughly tested, using RSpec. Note that all of its tests are "system" tests, in that they
+test the entire Gem, all the way down through ActiveRecord, to the database. This is because there is really no
+significant code in RequiredScopes that's independent of its interface to ActiveRecord, and so unit tests would be of
+little use. (In other words, making this gem work correctly is all about getting the patches to ActiveRecord right,
+not about consistency of any sophisticated internal logic.)
+
+To run these specs, you'll need a database server up and running that ActiveRecord can talk to. The specs create and
+drop various tables (all prefixed with `rec_spec_`, so they're highly unlikely to conflict with anything). Because
+they do this, there's no need to prepare the database ahead of time, and it should be safe to use a database that's
+also used for other things. (On the other hand, having its own dedicated database won't hurt; and if you run these
+specs against a database containing data that's precious, you're just asking for it.)
+
+To run these specs:
+
+1. If you want to test against a particular ActiveRecord version, `export REQUIRED_SCOPES_AR_TEST_VERSION=3.2.16` (for example). If you want the latest stable ActiveRecord, simply skip this step.
+2. `cd required_scopes` (the root of the gem).
+3. Create a file called `spec_database_config.rb` at the root level of the gem. It should define your connection to the database, like so:
+
+    REQUIRED_SCOPES_SPEC_DATABASE_CONFIG = {
+      :require => 'pg',
+      :database_gem_name => 'pg',
+      :config => {
+        :adapter => 'postgresql',
+        :database => 'some_database',
+        :username => 'postgres',
+        :password => 'some_password'
+      }
+    }
+
+4. `bundle install`. (This step must come _after_ you create `spec_database_config.rb`; it uses that file to know what database gem to include.)
+5. `bundle exec rspec spec` will run all specs. (Or just `rake`.)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/required_scopes.rb

@@ -0,0 +1,17 @@
+# There's currently nothing at all in the RequiredScopes module except for its use as a namespace.
+module RequiredScopes
+end
+
+require "required_scopes/version"
+require "required_scopes/active_record/base"
+require "active_record"
+
+# Add methods to ::ActiveRecord::Base that let you declare scoping requirements, and declare scopes that satisfy
+# them...
+ActiveRecord::Base.send(:include, ::RequiredScopes::ActiveRecord::Base)
+
+# ...and add methods to ::ActiveRecord::Relation that enforce those requirements.
+require "required_scopes/active_record/relation"
+
+require "required_scopes/active_record/version_compatibility"
+::RequiredScopes::ActiveRecord::VersionCompatibility.apply_version_specific_fixes!

data/lib/required_scopes/active_record/base.rb

@@ -0,0 +1,235 @@
+require 'active_support'
+require 'active_record'
+
+module RequiredScopes
+  module ActiveRecord
+    # This is the module that gets +include+d into ::ActiveRecord::Base when +required_scopes+ is loaded. It defines
+    # the exposed methods on ::ActiveRecord::Base, and overrides a few (like #scope and #unscoped).
+    module Base
+      extend ActiveSupport::Concern
+
+      included do
+        class << self
+          delegate :scope_categories_satisfied, :scope_category_satisfied,
+            :all_scope_categories_satisfied, :to => :relation
+        end
+      end
+
+      # Calling #destroy ends up generating a relation, via this method, that is used to destroy the object. We need
+      # to make sure we don't trigger any checks on this call.
+      def relation_for_destroy
+        out = super
+        out.all_scope_categories_satisfied!
+        out
+      end
+
+      module ClassMethods
+        # Declares that all users of your model must scope it by one or more categories when running a query, performing
+        # a calculation (like #count or #exists?), or running certain bulk-update statements (like #delete_all).
+        # Categories are simply symbols, and they are considered satisfied if a scope is used that declares (_e.g._)
+        # <tt>:satisfies => :deletion</tt> is included before running a query.
+        #
+        # This is the heart of +required_scopes+. Its purpose is to remind developers that certain kinds of constraints
+        # should always be taken into account when accessing data in a particular table, so that they can't
+        # under-constrain queries and potentially ignore soft deletion of rows, or cross client boundaries, or similar
+        # things.
+        #
+        # For example:
+        #
+        #     class User < ActiveRecord::Base
+        #       must_scope_by :deletion
+        #
+        #       scope :normal, lambda { where(:deleted => false) }, :satisfies => :deletion
+        #       scope :deleted, lambda { where(:deleted => true) }, :satisfies => :deletion
+        #     end
+        #
+        # Now, if you say
+        #
+        #     the_user = User.where(:name => 'foo').first
+        #
+        # ...you'll get a RequiredScopes::Errors::RequiredScopeCategoriesNotSatisfiedError; you must instead call
+        # one of these:
+        #
+        #     the_user = User.normal.where(:name => 'foo').first
+        #     the_user = User.deleted.where(:name => 'foo').first
+        #
+        # For any given scope category, a scope starting with +ignoring_+ is automatically created; this does not
+        # actually constrain the scope in any way, but marks that category as satisfied. (The point is not to _force_
+        # developers to constrain on something, but to make sure they can't simply forget about the category.) So this
+        # will also work:
+        #
+        #     the_user = User.ignoring_deletion.where(:name => 'foo').first
+        #
+        # An explicit call to #unscoped removes all requirements, whether used in its direct form or its
+        # block form, so these will also both work:
+        #
+        #     the_user = User.unscoped.where(:name => 'foo').first
+        #     User.unscoped { the_user = User.where(:name => 'foo').first }
+        #
+        # ActiveRecord also lets you use class methods as scopes; if you want one of these to count as satisfying a
+        # scope category, use #scope_category_satisfied (or #scope_categories_satisfied):
+        #
+        #     class User < ActiveRecord::Base
+        #       must_scope_by :client
+        #
+        #       scope :active_clients, lambda { where(:client_active => true) }, :satisfies => :client
+        #
+        #       class << self
+        #         def for_client_named(client_name)
+        #           client_id = CLIENT_MAP[client_name]
+        #           where(:client_id => client_id).scope_category_satisfied(:client)
+        #         end
+        #       end
+        #     end
+        #
+        # In the above example, either <tt>User.active_clients.first</tt> or <tt>User.for_client_named('foo').first</tt>
+        # will count as having satisfied the requirement to scope by +:client+, and hence will not raise an error.
+        def must_scope_by(*args)
+          categories = args.map(&:to_sym)
+          @required_scope_categories ||= [ ]
+          @required_scope_categories += categories
+
+          categories.each do |category|
+            scope "ignoring_#{category}", lambda { send(::RequiredScopes::ActiveRecord::VersionCompatibility.relation_method_for_ignoring_scopes) }, :satisfies => category
+          end
+        end
+
+        # Returns the set of scope categories that must be satisfied for this class, as a (possibly-empty) Array.
+        def required_scope_categories
+          if self == ::ActiveRecord::Base
+            [ ]
+          else
+            out = (@required_scope_categories || [ ]) | superclass.required_scope_categories
+            out - (@ignored_parent_scope_requirements || [ ])
+          end
+        end
+
+        # If you're using inheritance in your ActiveRecord::Base classes, and a parent class declares a required scope
+        # category (using #must_scope_by), you can remove that requirement in a subclass using
+        # #ignore_parent_scope_requirement. (This should be quite rare.)
+        def ignore_parent_scope_requirement(*args)
+          categories = args.map(&:to_sym)
+          @ignored_parent_scope_requirements ||= [ ]
+          @ignored_parent_scope_requirements |= categories
+        end
+
+        # We want #unscoped to remove any actual scoping rules, just like it does in ActiveRecord by default. However,
+        # we *don't* want it to remove any category satisfaction that we're currently under. Why? So you can do this:
+        #
+        #     User.all_scope_categories_satisfied do
+        #       ...
+        #       User.unscoped.find(...)
+        #       ...
+        #     end
+        def unscoped
+          satisfied_by_default = current_scope.try(:satisfied_scope_categories) || [ ]
+
+          out = super
+          out = out.scope_category_satisfied(satisfied_by_default) if satisfied_by_default.length > 0
+          out
+        end
+
+
+        # Declares that use of this ActiveRecord::Base class must be scoped by at least one _base scope_; a base scope
+        # is any scope declared using #base_scope, instead of #scope. (Other than satisfying this requirement,
+        # #base_scope behaves identically to #scope.) This can be used to ensure that developers don't forget to scope
+        # out deleted records, or don't forget to scope by client, or so forth. (See the +README+ for +required_scopes+
+        # for why this is a better solution in many cases than just using +default_scope+.)
+        #
+        # For example:
+        #
+        #     class User < ActiveRecord::Base
+        #       base_scope_required!
+        #
+        #       base_scope :undeleted { where(:deleted => false) }
+        #       base_scope :deleted { where(:deleted => true) }
+        #     end
+        #
+        # Now, you'll get the following:
+        #
+        #     User.where(...).first               # RequiredScopes::Errors::BaseScopeNotSatisfiedError
+        #
+        #     User.undeleted.where(...).first     # => SELECT * FROM users WHERE deleted = 0 AND ... LIMIT 1
+        #     User.deleted.where(...).first       # => SELECT * FROM users WHERE deleted = 1 AND ... LIMIT 1
+        #     User.ignoring_base.where(...).first # => SELECT * FROM users WHERE ... LIMIT 1
+        #
+        # (This is simply syntactic sugar on top of #must_scope_by, using a category name of +:base+; see that method
+        # for more details.)
+        def base_scope_required!
+          must_scope_by :base
+        end
+
+        # Declares a scope that satisfies the requirement introduced by #base_scope_required!. In all other ways, it
+        # behaves identically to ActiveRecord::Base#scope.
+        def base_scope(name, body, &block)
+          scope(name, body, :satisfies => :base, &block)
+        end
+
+        # Returns a scope identical to the one it's called on, but that's marked as satisfying the requirement
+        # introduced by #base_scope_required!. This is useful in class methods that return a scope you want to count
+        # as satisfying that requirement:
+        #
+        #     class User < ActiveRecord::Base
+        #       base_scope_required!
+        #
+        #       class << self
+        #         def for_client_named(c)
+        #           where(:client_id => CLIENT_ID_TO_NAME_MAP[c]).base_scope_satisfied
+        #         end
+        #       end
+        #     end
+        def base_scope_satisfied(&block)
+          scope_category_satisfied(:base, &block)
+        end
+
+
+        # Overrides ActiveRecord::Base#scope to mark a scope as satisfying one or more categories if an extra option
+        # is passed:
+        #
+        #     scope :foo, lambda { ... }, :satisfies => :deletion
+        #
+        # You can also pass an Array of category names to :satisfies.
+        def scope(name, body, *args, &block)
+          if args && args[-1] && args[-1].kind_of?(Hash)
+            opts = args.pop
+
+            categories = Array(opts.delete(:satisfies)).compact
+
+            if categories && categories.length > 0
+              if body.kind_of?(Proc)
+                # New, happy, dynamic scopes -- i.e., scope :foo, lambda { where(...) }
+                old_body = body
+                body = lambda do
+                  out = old_body.call
+                  out.scope_categories_satisfied!(categories)
+                  out
+                end
+              else
+                # Old, sad, static scopes -- i.e., scope :foo, where(...)
+                body = body.clone
+                body.scope_categories_satisfied!(categories)
+                body
+              end
+            end
+
+            args.push(opts) if opts.size > 0
+          end
+
+          super(name, body, &block)
+        end
+      end
+    end
+  end
+end
+
+# When you call #includes to include an associated table, the Preloader ends up building a scope (via #build_scope)
+# that it uses to retrieve these rows. We need to make sure we don't trigger any checks on this scope.
+::ActiveRecord::Associations::Preloader::Association.class_eval do
+  def build_scope_with_required_scopes_ignored
+    out = build_scope_without_required_scopes_ignored
+    out.all_scope_categories_satisfied!
+    out
+  end
+
+  alias_method_chain :build_scope, :required_scopes_ignored
+end