This reverts commit 3420a145, reversing
changes made to afb66a5a.

The `@offsets` cache is used by FinderMethods to cache records found by
find_nth. This cache is cleared in AR::Relation#reset, but not in
CollectionProxy#reset or CollectionProxy#reload.

Because of this, since #29098, calling #first/#find_nth/etc after
calling #reload or #reset on an association could return a stale record.
This is an issue both when the full association target is loaded and
when the item is loaded in #find_nth.

This commit solves the problem by clearing the `@offsets` cache in
CollectionProxy#reset and CollectionProxy#reload.

Some third party modules expects that association returns same proxy
object each time (e.g. for stubbing collection methods:
https://github.com/rspec/rspec-rails/issues/1817).
So I decided that cache the proxy object and reset scope in the proxy
object each time.

Related context: https://github.com/rails/rails/commit/c86a32d7451c5d901620ac58630460915292f88b#commitcomment-2784312

This fixes the following issues.

* `association_scope` doesn't include `default_scope`. Should use `scope` instead.
* We can't use `method_missing` for customizing existing method.
* We can't use `relation_delegate_class` for sharing extensions. Should extend per association.

`ClassSpecificRelation` has `method_missing` and the `method_missing` is
called first. if an associated class has the missing method in a
relation, never reach to the `method_missing` in the `CollectionProxy`.
I extracted `DelegateExtending` and included it to the delegate class
that including `ClassSpecificRelation` to fix the issue.

Fixes https://github.com/rails/rails/pull/28246#issuecomment-296033784.

Since #28473 `uniq` is delegated to `records`, so `CollectionProxy#uniq`
is unnecessary.

Extension methods should not delegate to `scope` to respect dirty
target on `CollectionProxy`.

Fixes #28419.

The `select` in `QueryMethods` is also an enumerable method.
Enumerable methods with block should delegate to `records` on
`CollectionProxy`, not `scope`.

Fixes #28348.

I incorrectly changed behavior of `dup`. Reading the original issue I
thought that `dup` should retain the original contents of the record
and it's associations but it is in fact supposed to be a copy as if a
record had been reinitialized.

This reverts commit ca8c21df.

In Rails 3.2 dupping a `CollectionProxy` would dup it's `load_target` as
well. That functionality has been broken since the release of Rails 4.0.
I hit this in an application upgrade and wondered why duplicating a
CollectionProxy and assigning it to a variable stopped working.

When calling `dup` on a `CollectionProxy` only the owner (ex.
topic) was getting duplicated and the `load_target` would remain in tact
with it's original object ID. Dupping the `load_target` is useful for performing
a logging operation after records have been destroyed in a method.

For example:

```
def transfer_operation
  saved_replies = topic.replies

  topic.replies.clear

  saved_replies.each do |reply|
    user.update_replies_count!
  end
end
```

This change adds a `initialize_dup` method that performs a `deep_dup` on
the `@associatiation` so that the `load_target` is dupped as well.

Fixes #17117

Some methods were added to public API in
5b14129d and they should be not part of
the public API.

`merge! association.scope(nullify: false)` is expensive but most methods
do not need the merge.

Currently if `CollectionProxy` has more than one new record,
`CollectionProxy#uniq` result is incorrect.

And `CollectionProxy#uniq` was aliased to `distinct` in a1bb6c8b.
But the `uniq` method and the `SELECT DISTINCT` method are different
methods. The doc in `CollectionProxy` is for the `SELECT DISTINCT`
method, not for the `uniq` method.

Therefore, reverting the alias in `CollectionProxy` to fix the
inconsistency and to have the both methods.

- CollectionAssociation#select was removed in
  https://github.com/rails/rails/pull/25989 in favor of
  QueryMethods#select but it caused a regression when passing arguments
  to select and a block.
- This used to work earlier in Rails 4.2 and Rails 5. See gist
  https://gist.github.com/prathamesh-sonpatki/a7df922273473a77dfbc742a4be4b618.
- This commit restores the behavior of Rails 4.2 and Rails 5.0.0 to
  allow passing arguments and block at the same time but also deprecates
  it.
- Because, these arguments do not have any effect on the output of
  select when select is used with a block.
- Updated documentation to remove the example passing arguments and
  block at the same time to `CollectionProxy#select`.

Simply use its own method because `CollectionProxy` inherits `Relation`.

Simply use its own methods because `CollectionProxy` inherits `Relation`.

`length` is delegated to `records` (`load_target`) by
`ActiveRecord::Delegation`.

https://github.com/rails/rails/blob/v5.0.0/activerecord/lib/active_record/relation/delegation.rb#L38

Currently `CollectionProxy` inherits `Relation` therefore we can use
its own methods rather than delegating to collection association.

Currently `CollectionProxy` inherits `Relation` and `Relation` includes
`QueryMethods`. This method is completely duplicated.

https://github.com/rails/rails/blob/v5.0.0/activerecord/lib/active_record/relation/query_methods.rb#L271-L275

`#second`, `#third`, etc finder methods was added in 03855e79.
But the signature of these methods is inconsistent with the original
finder methods. And also the signature of `#first` and `#last` methods
is different from the original. This commit fixes the inconsistency.

`#first`, `#second`, ..., `#last` methods respects dirty target. But
`#take` doesn't respect it. This commit fixes the inconsistent behavior.

Fixes #25732.

Ruby 2.4 unifies Fixnum and Bignum into Integer: https://bugs.ruby-lang.org/issues/12005

* Forward compat with new unified Integer class in Ruby 2.4+.
* Backward compat with separate Fixnum/Bignum in Ruby 2.2 & 2.3.
* Drops needless Fixnum distinction in docs, preferring Integer.

Clarifying this separation and enforcing relation immutability is the
culmination of the previous efforts to remove the mutator method
delegations.

The focus of this change is to make the API more accessible.
References to method and classes should be linked to make it easy to
navigate around.

This patch makes exzessiv use of `rdoc-ref:` to provide more readable
docs. This makes it possible to document `ActiveRecord::Base#save` even
though the method is within a separate module
`ActiveRecord::Persistence`. The goal here is to bring the API closer to
the actual code that you would write.

This commit only deals with Active Record. The other gems will be
updated accordingly but in different commits. The pass through Active
Record is not completely finished yet. A follow up commit will change
the spots I haven't yet had the time to update.

/cc @fxn