The docs for `ActiveRecord::Associations::CollectionProxy` describe
`ActiveRecord::Associations::Association`. I've moved them to
association and rewrote collection proxy's docs to be more applicable to
what the class actually does.`

[ci skip]

Formerly it was returning arguments (`records` array).

Reset scope after delete on collection association to clear stale
offsets of removed records.

This reverts commit 487a1061.

This `#--` is necessary for the doc of `distinct`.

[ci skip]

Most of the time the table and predicate_builder
passed to Relation.new are exactly the
arel_table and predicate builder of the
given klass. This uses klass.arel_table
and klass.predicate_builder as the defaults,
so we don't have to pass them in most cases.

This does change the signaure of both Relation and
AssocationRelation. Are we ok with that?

Passing `true` to force an association to reload its records from the
database was deprecated in 5.0 and removed in 5.1.

Since `Relation` includes `Enumerable`, it is enough to use `super`
simply.

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.