interim

Centralize loading of DBIx::Class::Exception

No functional, nor even load-order changes

Remove hostile test added by stupid-me 7 years ago in 3bb4eb8f

Remove bizarre $_[$#_] idiom from the codebase

Zero functional changes

Only normalize conditions during resolution time, instead on every ->search

The normalization operation isn't cheap. Should result in no changes.

Add an explicit deduplication of identical condition in cond normalizer

In order to make everything work consistently add a "lax serializer" based
on Data::Dumper, as Storable is sensitive to IV vs PVIV differences.

While at it tighten up the serialize/dump env in DBIC::_Util

Fix SQLA condition normalizer sometimes stripping -value ops

Extract two stateless DBIHacks routines into a utility package

Further commits will need them in places where $storage isn't yet available.
There are zero functional changes

Best read under -C -C -M --color-words

Some cosmetic fixes in ANFANG

(travis) Temporarily allow-fail all trusty-based builds

Until the fallout from https://www.traviscistatus.com/incidents/2p40l49r3yxd
( https://github.com/travis-ci/travis-ci/issues/6439 ) is fixed...

(travis) Fix unixodbc-dev overwrite on newer CI images

(travis) Remove makefile fixup, now hardcoded in the subrepo

(travis) Work around RT#116788

(travis) Build cperl 5.25.x properly

(travis) Better diagnostics when perl compilation bails out

Bump version to accomodate pre-beta testers

Add missing contribs ( GH#6 / GH#28 )

Also mailmap fixups to go with 93f1cd05

Some (very minor) fixups of emit_dups calls in e570488a

Fix "overriden" typo

(travis) cPerl 5.24.0 has shipped

Enable the schema SanChecks on 5.8 as well

See how DarkPAN will react to this - it may be just fine. Backing it out in
a standalone commit so it can be reinstated easily before stable

Fix inexplicable 5.8.x C3 errors - roll back e6efde04

The optimization ends up breaking the entire C3 subsystem at a crucial time
when add_columns has to see the correct register_column in order for IC::DT
to populate the right column_info.

Most importantly it seems that Class::C3::XS makes this optimization entirely
moot (in fact minimal testing indicates things getting *faster* instead)

Recognize more authorship based on the historic repo (if available)

Merge the ResultSource diagnostics rework

                            ...And this is what the products that we make do:
                            these are the consequences. They either empower
                            people, or they steal bits of their lives.
                            Because experiences are all we have in life:
                            if you think about them as grains of sand in an
                            hour glass, once those grains are gone – they are
                            gone. And experiences with people and experiences
                            with things: they use up the same grains.

                            That's why we have a profound responsibility to
                            respect the experiences of the people that we
                            build for...

                            -- Aral Balkan:  Free is a Lie  TNW 2014
                               https://youtu.be/upu0gwGi4FE?t=1548

This set of commits is unusual - the 2+kloc of changes (in lib/ alone) do not
add any new runtime functionality, nor do these changes alter significantly
any aspect of DBIC's runtime operation. Instead this is a culmination of a
nearly 4 months long death-march [1] ensuring the increasingly complex and
more frequent ( courtesy of rising use of Moo(se) ) failure modes can be
reasoned about and acted upon by ordinary users, without the need to reach
out to a support channel.

The changeset has been extensively tested against 247 downstream CPAN dists
(as described at the end of commit 12e7015a) and against several darkpan
test suites. As of this merge there are no known issues except RT#114440 [2]
and a number of dists (enumerated in 12e7015a) now emitting *REALLY LOUD*
though warranted and actionable, diagnostic messages.

The diagnostic is emitted directly on STDERR - this was a deliberate choice
designed to:

 1) prevent various test suites from failing due to unexpected warnings

 2) make the warnings *harder* to silence by a well meaning but often too
    eager-yet-not-sufficiently-dilligent staffer, before the warnings had
    a chance to reach a senior developer

What follows is a little bit of gory technical details on the commit series,
as the work is both generic/interesting enough to be applied to other large
scale systems, and is "clever" enough to not be easily reasoned about without
a summary. Think of this as a blog post within an unusual medium ;)

=== BACKGROUND
==============

Some necessary history: DBIC as a project is rather old [3][4]. When it got
started Moose wasn't a thing. Neither (for perspective) was jQuery or even
Tw(i)tt(e)r. The software it was modeled on (Class::DBI) has "single-level"
metadata: you have one class per table, and columns/accessor were defined on
that class and that was it. At the time mst made the brilliant decision to
keep the original class-based API (so that the CDBI test suite can be reused
almost verbatim, see ea2e61bf) while at the same time moving the metadata to
a "metaclass instance" of sorts. The way this worked was for each level of:

- Individual Result Class (class itself, not instance)
- Result Class attached to a Schema class
- Result Class attached to a Schema instance

to have a separate copy-on-the-spot created metadata instance object of
DBIx::Class::ResultSource. One can easily see this by executing:

~/dbic_checkout$ perl -Ilib -It/lib -MDBICTest -MData::Dumper -e '
  my $s = DBICTest->init_schema;
  $Data::Dumper::Maxdepth = 1;
  warn Dumper [
    DBICTest::Schema::Artist->result_source_instance,
    DBICTest::Schema->source("Artist"),
    $s->source("Artist"),
  ]
'

The technique (and ingenious design) worked great. The downside was that
nobody ever really audited the entire stack past the original implementation.
The codebase grew, and mistakes started to seep in: sometimes modifications
(add_columns, etc) would happen on a derivative metadata instance, while the
getters would still be invoked on the "parent" (which at this point was
oblivious of its "child" existence, and vice versa). In addition there was a
weird accessor split: given a result instance one could reach *different*
metadata instances via either result_source() or result_source_instance(). To
add insult to the injury the latter method is never defined anywhere, and was
always dynamically brought to life at runtime via an accessor maker call on
each individual class [5].

If that wasn't bad enough, some (but crucially *not* all) routines used to
manipulate resultsource metadata were proxied [6] to the main Result classes,
also aiming at allowing the reuse of the existing Class::DBI test suite, and
to provide a more familiar environment to Class::DBI converts. The complete
map of current metadata manipulation methods and their visibility from a
typical ResultClass can be seen at the end of commit message 28ef9468.

The downside was that to an outsider it would seem only natural that if in
order to make something metadata-related happen, one normally calls:

  SomeResultClass->set_primary_key

then it makes sense that one should be able to override it via:

  sub SomeResultClass::set_primary_key {
    my $ret = shift->next::method(@_);
    { do extra stuff }
  }

That thinking has been applied to pretty much all straight-pass-through
getters in the wild, with the expectation that DBIC will respect them
throughout, like e.g. [7]. In reality this never happened - half of DBIC
would never even look at the Result class and instead simply called the
needed method on the result source instance directly. As noted in 28ef9468:
the overwhelmingly common practice is to hook a method in a Result class and
to "hope for the best". A rare example of "doing it right" would be
DBIx::Class::ResultSource::MultipleTableInheritance [8], but as can be seen
from its SYNOPSIS the API is rather counterintuitive ( what is table_class()
anyway?! ) and more importantly - the earlier example seems "just right".

Another innovation (remember: pre-Moose) was the use of the just-in-time
implemented [9] alternative C3 method resolution order (MRO)[10] right on top
of the default perl DFS MRO. While DBIC used multiple inheritance (MI) from
the start, with all the corresponding problems [11][12][13] and non-scalable
"solutions" [14], it wasn't until C3 MRO became available that the true
potential of the resulting plugin system became clear. To this day (mid-2016)
MI, as used within the DBIC ecosystem, remains the single most flexible (and
thus superior given the problem domain) plugin-system on CPAN, easily
surpassing rigid delegation, and having an upper hand on role-based solutions
as promoted by the Moo(se) ecosystem. It must be noted that delegation and/or
roles are not without uses - they are an excellent (and frankly should be a
default) choice for many application-level systems. It is the mid-level to
low-level libraries like DBIC, where the stateless nature of a predictable
yet non-coordinated call-order resolution truly begins to shine.

=== PROBLEM(S)
==============

Things stayed undisturbed for a while, until around 2012~2013 folks started
showing up with more and more complaints which all traced to Moo(se)-based
subclassing. Originally the C3 MRO composition worked just fine, because
almost invariably a ->load_components() call (which explicitly switches the
callER MRO) would have happened early enough in the life of any end-user
Result/ResultSource class. But when extends()/with() got more prominent this
was lost. The more complex the inheritance chain - the more likely that the
topmost leaf class is in fact stuck under DFS mro with everything going
sideways from there. Sometimes with truly mindbending failure cases as [15].
There was no clear solution at the time, and aside from some toothless
documentation warnings [16] nothing was done to address this (in fact even
the doc-patch itself is incomplete as noted in [17]).

The inconsistencies, and the resulting mistakes, however, were all localized,
and even though the problems were often major, each instance was sufficiently
different (and bizarre) that each individual deployment could neither report
them properly, nor find the time to reason through the layers of history in
order to arrive at a solution they fully understand. Yet the original design
which solidified towards the end of 2007 was *just* good enough to keep being
kicked down the road.

But people kept writing more and more MOP-inspired stuff. Given the general
tendency of perl code to get "all over the place", the desire was only
natural to standardize on "one true way" of doing OO throughout an entire
end-user project/app.  And there were more and more ways in the wild to
combine/abstract individual Result classes and ResultSet components. The
comprehensive DBIx::Class::Helpers [18] are just the tip of the heap of
all possible permutations DBIC is exposed to. Towards mid-2015 it became
utterly untenable to brush off problems with "meh, just don't do that and all
will be be fine".

On the personal front I first ran into the baroque jenga tower head-on when
I tried to make sense of the ResultSource subsystem in an airport lounge
pre-YAPC::EU 2011 (Riga). I honestly do not remember *why* I started digging
in this direction but the result of that attempt (and the later effort to
revive it) got immortalized in my local tree [19]. Enough said.

Next was the dash to implement sane relationship resolution semantics in
03f6d1f7, and then in 350e8d57 (which was actually needed to allow for
d0cefd99 to take place... sigh). During that journey 4006691d made a subtle
but fatal in the long run change - it upset the balance of which source
instance object we looked at during *some* (but not all) codepaths. The
really sad part is that I had the feeling that something is not right, and
even made a record of it as the last paragraph of 350e8d57. But light
testing did not reveal anything, and I irresponsibly shipped everything
as-is a bit later. It wasn't until Oct 2015 that someone noticed this being
an actual problem [20]. Early attempts to fix it quickly demonstrated just
how deep the rabbit hole goes, and were the main reason the entirety of
this work was undertaken: the accumulated debt simply did not leave any room
for a half-way solution :/

=== SOLUTION(S)
===============

The writeup below describes only the final set of commits: it does not cover
driving into and backing out of at least 3 dead-ends, nor does it cover the
5 distinct rewrites and re-shuffles of the entire stack as more and more
involved testing revealed more and more involved failure modes. I must stress
that if you plan to undertake a similar crusade against another projects
architectural debt you are in for a rough (but *not* impossible!) ride. The
height of the "tenacity-bar" necessary to pull off such work is not reflected
in any way within the seemingly effortless walkthrough that follows. It is
also worth acknowledging that the code at times is incredibly terse and hard
to follow: this was a deliberate choice as the extra diagnostic sites that
are enabled during runtime had to be implemented as "close to the VM", so to
speak, as possible. In isolation none of the contortions are warranted, but
because I ended up with so many of them the result does pay off. See comments
within individual commit messages for various performance impacts for more
info.

As first order of business some mechanism was needed to track the logical
relationship between the 3 levels of ResultSource instances as shown earlier
in this writeup. Luckily, the user-unfriendly nature of the metadata stack
meant there are very few spots on CPAN (and to the best of my knowledge
on DarkPAN) that do anything exotic with the subsystem. This means the
simplest thing would in fact work and was implemented as 534aff61: corral
all instantiations of ResultSource objects (and Schema objects while we are
at it) [21]. This code ensured that nothing in the stack will create an
instance of either class-type without our knowledge. With that in place, we
also provide an explicit clone method [22] encouraging folks to use that
whenever possible. The switch of all relevant callsites within DBIC itself
was verified through another check within new [23], guarded by the same
compile-time assertion constant (which in turn was provided by both the CI
and the local smoke-script from 5b87fc0f)

With the above in place, ensuring 99.99% of the ResultSource "derivative"
instances were obtained via $rsrc->clone, it was time for 0ff33686. A simple
private registry hash with object addresses as keys and this hash as values:

{
  derivatives => {
    addr_derived_rsrc_1 => $reference_to_infohash_of_derived_rsrc_1,
    addr_derived_rsrc_2 => $reference_to_infohash_of_derived_rsrc_2,
    ...
  },
  weakref => $weak_reference_of_self,
}

As necessary for any structure holding addresses of object references, a
CLONE "renumbering" routine takes care of keeping everything in sync on
iThread spawns (if you believe that iThreads are evil and one shouldn't go
through the trouble: be reminded that any call of fork() within a Win32 perl
is effectively an iThread, and fork() can and *is* being called by some CPAN
modules [24] implicitly).

Now that we had a good handle on "what came from where", the first major
diagnostic milestone 73f54e27 could be covered. As can be seen in the table
of methods in commit 28ef9468 there are only a handful of attributes on an
actual ResultSource class. A couple new Class::Accessor::Grouped method types
were added, which would behave just like the 'simple' and 'component_class'
they were replacing, but with a twist:

 - any setter-based change would record its callsite in any derivative that
   was being tracked by 0ff33686, effectively marking that derivative stale
 - any getter call would consult its own entry in the metadata instance
   "stale log", and complain that things have moved on based on the callsite
   the setter left earlier

The result is the exact warning as described in commit message 73f54e27. Of
course there are some extra considerations - some high-level setters (e.g.
remove_columns) do call a getter underneath to do their job. These cases had
to be short-circuited by using a local()-based "setter callstack" mark. But
in general the changeset has been surprisingly non-invasive: once the proper
hook points were identified the rest was a breeze. There was also a brief
scratching of heads when the last stages of DarkPAN tests emitted errors
which I myself could not explain for a while, until the reason (and trivial
solution) were identified in d56e05c7 and [25].

As a brief detour, I considered switching ResultSource to a proper Moo class,
but quickly abandoned this idea as there are no provision for clean get-time
triggers. Nevertheless the attempt was a useful demonstration what does it
take to switch a low-level class (which means many somewhat questionable uses
by consumers in the wild) to Moo(se) with zero loss of functionality. The
result is preserved for posterity as 8ae83f0e [26].

While working on the above and f064a2ab (the solution to RT#107462 [20]), it
occurred to me that the confusion of having both result_source_instance()
and result_source() can be reduced further by forcing all "getter" calls to
go through result_source() which is defined in Row.pm and is thus always
available. The result was the improved diagnostic as described in the commit
message of e570488a, but also a useful set of assertions that were used to
weed out many of the wrinkles [27].

The next major step was to resolve once and for all the fallout from
incorrect inheritance composition. The highly dynamic nature of all Perl's
programs, an "eternal compile/execute/compile/execute... cycle", meant that
just "fixing things" as DBIC sees them would not work - calling set_mro()
could do little when called late enough. This led to the revert of the
originally-promising "forced c3-fication" of the stack 7648acb5. Instead
the practical design turned out to be "let the user know and carry on".

The first part of getting there was to devise a way to precisely and very
quickly tell "what does a class look like right now?" I have been brooding
over how to do this since mid-February, but it wasn't until I noticed
the excellent App::Isa::Splain [28] by @kentfredric, that the final interface
came into focus: 296248c3 (with several minor fixups later on). Here I want
to take a moment to apologize to @kentfredric, as he was led on a several
week long wild-goose chase due to a misguided comment of mine [29] :(

Amusingly while implementing this I hit a wall related to perl 5.8 (for the
first time in 6+ years): As stated in the timings at the end of commit
message 296248c3 and as elaborated in [30] - the non-core MRO is just too
expensive to work with. This resulted in a 1.5 week long detour to try to
squeeze every last ounce of performance. Amusingly I ran into a lot of
"interesting" stuff along the way [31][32][33] The result was not only a
semi-usable 5.8 implementation, but even running on 5.10+ was sped up about
2 times in the end, which translated into tangible gains in the end: the
number cited as 16% in 12e7015a was originally 28%(!). The moral of this
story? - gerontoperlia [34] makes your modern foundation code better.

With a reliable way to tell what each methods "variant stack" looks like, it
was trivial to implement the 'valid_c3_composition' part of ::SanityChecker -
one would simply check a class' MRO, and in case of 'dfs' compare all stacks
to what they would look like if the MRO were 'c3' [35].

In parallel but unrelated to the above the ever increasing tightening of
various DBIC internal callpaths ( e5053694, d99f2db7, 3b020224 ) had to be
addressed in some way. The urgency truly "hit home" when testing revealed
RT#114440 [2] - it was nothing short of a miracle this code survived that
long without being utterly broken by other components. The solution came out
of crossing the work on describe_class_methods (296248c3) with the concept
of the fail_on_internal_call guard (77c3a5dc). We already have a list of
method "shadowing stacks" (to borrow @kentfredric's terminology) - if we find
a way to annotate methods in a way that we can tell when a "non-overrideable"
method was in fact overridden - we will be able to report this to the user.

The somewhat fallen out of favor subsystem of function attributes was chosen
to carry out the "annotation" task. It must be noted that this is one of the
few uses of attributes on CPAN that is architecturally consistent with how
attributes were originally implemented. An attribute is meant to attach to
a specific reference ( in our case a code reference ), instead of a name.
This is also why the FETCH/MODIFY_type_ATTRIBUTE API operates strictly with
references. As an illustration why tracking attributes by name is fraught
with peril consider the following:

perl -e '
  use Data::Dumper;
  use Moose;
  use MooseX::MethodAttributes;

  sub somemethod :Method_expected_to_always_returns_true { return 1 };

  around somemethod => sub { return 0 };

  warn Dumper {
    attributes => __PACKAGE__->meta->get_method("somemethod")->attributes,
    result => __PACKAGE__->somemethod
  };
'

It should also be noted that as of this merge describe_class_methods lacks
a mechanism to "see" code references captured by around-type modifiers, and
by extension the "around-ed" function's attributes will not appear in the
"shadowed stack". A future modification of Class::Method::Modifiers, allowing
minimal introspection of what was done to which coderef should alleviate most
of this problem.

Once all relevant methods were tagged with a 'DBIC_method_is_indirect_sugar'
attribute in 1b822bd3, it was trivial to implement the schema sanity check
no_indirect_method_overrides which simply ensures no user-provided method
"shadows" a superclass method with the 'sugar' attribute set [36].

The success of the attribute-based approach prompted a pass of annotating
all the methods DBIC generates for one reason or another: 09d8fb4a. Aside
from enabling the last improvement, it also allowed to replicate a part of
the DBIx::Class::IntrospectableM2M functionality in core, without elevating
the status of the m2m sugar methods in any way (the historic labeling of
these helpers as relationships is a long standing source of confusion). See
the commit message of 09d8fb4a for a couple use-cases.

The last piece of the puzzle 28ef9468 addressed the "override and hope for
the best" duality of ResultSource proxied methods as described at the start
of this writeup and at [37]. What we essentially do is add an around() [38]
for every method in ResultSource, which then checks whether it was called via
ResultSourceProxy (inherited from DBIx::Class::Core), or directly via the
ResultSource instance: i.e. MySchema::Result::Foo->proxied vs $rsrc->proxied
IFF we are called directly and there *is* an override of the same method on
the currently-used $rsrc->result_class we either follow one of the options
as given by an attribute annotation [37], or we emit a diag message so that
the user can do something about it.

That was easy wasn't it?

=== FINAL THOUGHTS
==================

This work took about 50 person-days to carry out, and for obvious reasons
expanded to cover a much larger period of actual wall-time. While I am by
far not the most efficient developer that I have met, I am pretty sure that
the process of planning, designing, implementing and testing all of this
could not have been significantly accelerated. Even at the (laughable) rate
of $50/h The Perl Foundation is willing to pay for unique talent [39] this
endeavor would cost at least $20,000 USD - way beyond the scope (and aim?)
of a TPF grant. On the other hand it would be surprising if this work can
be qualified as unnecessary. I personally estimate that the savings due to
the proper diagnostics alone will "make up" for the effort within the first
month of wide deployment of these improvements. Time will tell of course, as
the stream of questions is only about to start come the first days of August.

In any case - this project is by far not the only one in dire need of such
"humane" overhaul. Moo, Catalyst, various pieces of the toolchain, and other
staples of what is known as "modern perl5" are in similar or worse shape:
a situation which can *not* be rectified simply by "writing patches" without
a concerted effort directed by a single [40] dedicated individual.

I yet again strongly urge the "powers of Perl" to reconsider their hands-off
approach to funding the consistently shrinking pool of maintainers. *PLEASE*
consider stealing (in the spirit of tradition) the proven successful model of
RubyTogether [41] before you end up losing even more maintainers like myself.

Peter "ribasushi" Rabbitson
Outgoing maintainer of a cornerstone Perl5 ecosystem project

( in the future you may be needing https://archive.org/web/ to see some of these )

 [1] https://gist.github.com/ribasushi/6ea33c921927c7571f02e5c8b09688ef
 [2] https://rt.cpan.org/Ticket/Display.html?id=114440#txn-1627249
 [3] http://static.spanner.org/lists/cdbi/2005/07/25/90c9f5f1.html
 [4] http://lists.digitalcraftsmen.net/pipermail/classdbi/2005-August/000039.html
 [5] https://metacpan.org/source/RIBASUSHI/DBIx-Class-0.082840/lib/DBIx/Class/ResultSourceProxy/Table.pm#L17-21
 [6] https://metacpan.org/source/RIBASUSHI/DBIx-Class-0.082840/lib/DBIx/Class/ResultSourceProxy.pm#L53-87
 [7] https://metacpan.org/source/VANSTYN/RapidApp-1.2000/lib/RapidApp/DBIC/Component/VirtualColumnsExt.pm#L52-67
 [8] https://metacpan.org/pod/DBIx::Class::ResultSource::MultipleTableInheritance#SYNOPSIS
 [9] https://twitter.com/hashtag/dammitstevan
[10] https://en.wikipedia.org/wiki/C3_linearization
[11] https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem
[12] http://static.spanner.org/lists/cdbi/2005/07/25/caf44f84.html
[13] http://static.spanner.org/lists/cdbi/2005/07/26/e593c147.html
[14] http://static.spanner.org/lists/cdbi/2005/07/26/ea509a6a.html (... tell people "Be Careful!" )
[15] https://blog.afoolishmanifesto.com/posts/mros-and-you/
[16] https://metacpan.org/pod/DBIx::Class::ResultSet#ResultSet-subclassing-with-Moose-and-similar-constructor-providers
[17] https://github.com/dbsrgits/dbix-class/pull/49#issuecomment-47637403
[18] https://metacpan.org/release/DBIx-Class-Helpers
[19] http://i.imgur.com/A3acsCD.png
[20] https://rt.cpan.org/Ticket/Display.html?id=107462
[21] https://github.com/dbsrgits/dbix-class/blob/534aff61/lib/DBIx/Class/_Util.pm#L1082-L1135
[22] https://github.com/dbsrgits/dbix-class/blob/534aff61/lib/DBIx/Class/ResultSource.pm#L160-L184
[23] https://github.com/dbsrgits/dbix-class/blob/534aff61/lib/DBIx/Class/ResultSource.pm#L126-L143
[24] http://grep.cpan.me/?q=my+%5C%24pid%3D+fork+dist%3DXML-Twig
[25] https://github.com/ctrlo/GADS/pull/9/files
[26] http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits/DBIx-Class-Historic.git;a=commitdiff;h=8ae83f0e
[27] https://github.com/dbsrgits/dbix-class/blob/e570488a/t/lib/DBICTest/BaseSchema.pm#L379-L528
[28] https://metacpan.org/pod/App::Isa::Splain#SYNOPSIS
[29] https://github.com/kentnl/Devel-Isa-Explainer/issues/1#issuecomment-212248379
[30] https://github.com/dbsrgits/dbix-class/blob/12e7015a/lib/DBIx/Class/Schema/SanityChecker.pm#L92-L102
[31] https://twitter.com/ribasushi/status/753678208076242944
[32] https://github.com/dbsrgits/dbix-class/commit/296248c3#diff-c13797cc2e5864c4a1d6a92ba65871b6R801
[33] https://github.com/dbsrgits/dbix-class/blob/1cf2ad8b/lib/DBIx/Class/_Util.pm#L663-L664
[34] https://youtu.be/2Ln0YHtKgaI?t=3731
[35] https://github.com/dbsrgits/dbix-class/blob/12e7015a/lib/DBIx/Class/Schema/SanityChecker.pm#L484-L505
[36] https://github.com/dbsrgits/dbix-class/blob/12e7015a/lib/DBIx/Class/Schema/SanityChecker.pm#L359-L394
[37] https://github.com/dbsrgits/dbix-class/blob/28ef9468/lib/DBIx/Class/MethodAttributes.pm#L242-L298
[38] https://github.com/dbsrgits/dbix-class/blob/28ef9468/lib/DBIx/Class/ResultSourceProxy.pm#L137-L333
[39] http://news.perlfoundation.org/2016/02/grant-proposal-perl-6-performa.html#comment-38362169
[40] http://queue.acm.org/detail.cfm?id=2349257 ( ... quality happens only if somebody has the responsibility for it, and that "somebody" can be no more than one single person )
[41] https://rubytogether.org/roadmap

Prevent invisible skipping of ResultSource proxy overrides

*** NOTE ***
This does not add any new default functionality, nor does it alter DBIC's
behavior from how it solidified back in 2006: all this does is alert a user
when things are 99% not DWIM-ing (10 years overdue but better late than...)
*** NOTE ***

During the original design of DBIC the "ResultSourceProxy" system was
established in order to allow easy transition from Class::DBI. Sadly
it was not well abstracted away: it is rather difficult to use a custom
ResultSource subclass. The expansion of the DBIC project never addressed
this properly in the years since.

As a result when one wishes to override a part of the ResultSource
functionality, the overwhelmingly common practice is to hook a method in a
Result class and "hope for the best".

The subtle changes of various internal call-chains (mainly 4006691d) make
this silent uncertainty untenable. As a solution any such override will now
issue a descriptive warning that it has been bypassed during a direct
$rsrc->overriden_function invocation. A user now *must* determine how each
individual override must behave in this situation, and tag it with one of
the provided attributes.

For completeness the blueprint off which this solution was devised is
provided below:

  I = indirect (helper) method, never invoked by DBIC itself

* Rsrc method types
  . = rsrc_instance_specific_attribute type accessor (getter+setter)
  s = setter calling a . internally
  g = getter calling a . internally
  c = custom accessor

* Result method types
  P = proxied directly into ::Core via ::ResultSourceProxy (overridable)
  X = a ::Core proxy to ::ResultSource with extra logic (overridable)
  m = misc... stuff

    ___ Indirect methods ( the sanity checker warns when one "covers" these )
  /
 |   __ Rsrc methods somehow tied into the metadata state
 | /
 ||   _ Available to .../Result/... via ResultSourceProxy
 || /
 |||
 |||
DBIx::Class::ResultSource::View:
  .    is_virtual,
  .    deploy_depends_on,
  .    view_definition

DBIx::Class::ResultSource:
  c    schema

  .    source_name    # no proxy, but see FIXME at top of ::ResultSourceProxy

  .    _columns
  .    _ordered_columns
  .    _primaries
  .    _relationships
  .    _unique_constraints
  .P   column_info_from_storage
  .    name
  .P   result_class
  .P   resultset_attributes
  .P   resultset_class
  .P   source_info
  .    sqlt_deploy_callback

 IsX   add_column
  sX   add_columns
  sX   add_relationship,

 IsP   remove_column
  sP   remove_columns
  sP   add_unique_constraint
 IsP   add_unique_constraints
  sP   sequence
  sP   set_primary_key

 IgP   column_info
  gP   columns_info
  gP   columns

  gP   has_column
  gP   has_relationship
  gP   primary_columns
  gP   relationship_info
  gP   relationships

  gP   unique_constraint_columns
  gP   unique_constraint_names
  gP   unique_constraints

DBIx::Class::ResultSourceProxy::Table:
   m   table
   m   _init_result_source_instance

Expand annotations to cover all generated methods

This is needed for the next commit, as we need a reliable way to tell gened
methods apart from everything else. Given we will be taking the hit of adding
the attributes, just go ahead and annotate *everything*, to be done with all
auto-generated subs once and for all.

This also solves @vanstyn's long-time gripe of not being able to tell where
in a random schema one has declared m2m "relationships" (a typical customer is
*very* unlikely to be using DBIC::IntrospectableM2M)

As of this commit a typical Result can be introspected for m2m as follows:

~$ perl -Ilib -It/lib -MDBICTest -MPackage::Stash -e '

  my $meths = Package::Stash->new("DBICTest::Schema::Artwork")
                             ->get_all_symbols("CODE");

  for my $m (sort keys %$meths ) {
    print "$m\n" if grep {
      $_ =~ /^DBIC_method_is_m2m_sugar/
    } attributes::get($meths->{$m});
  }
'

While the more involved "complete method map" looks as follows:

~$ perl -Ilib -It/lib -MDBICTest -MPackage::Stash -e '

  my $meths = Package::Stash->new("DBICTest::Schema::CD")
                             ->get_all_symbols("CODE");

  for my $m (sort keys %$meths ) {
    if ( my @attrs = attributes::get($meths->{$m}) ) {
      print "\n$m\n";
      print "  $_\n" for @attrs;
    }
  }
'

Introducing DBIx::Class::Schema::SanityChecker

This gives us comprehensive diagnostic on incorrect component composition
and other hard to track... stuff.

Given the huge amount of changes to call chains (specifically the changes
in 77c3a5dc and e5053694), and the fallout seen on CPAN and darkpan due to
these modifications, the status quo became clearly untennable. To mitigate
the (often silent) breakage a brand new "sanity check" framework was
introduced as part of the ::Schema setup-cycle (and is enabled by default)

Same DBIx::Class::Helper v2.032002 test time shoots from 65.5s all the way
to 76.0s, a 16% slowdown. However the moment the framework is disabled by
flipping $schema->schema_sanity_checker to a defined-but-false value - the
startup impact is entirely gone.

The changset was extensively tested against the following set of downstream
dists (a superset of c8b1011e), with each warning hand-confirmed to be a
valid description of a real problem:

--- actual bash script passing on a *heavily* massaged PERL5LIB

set -o pipefail

export PERL_CPANM_OPT=
export PERL5LIB="/home/rabbit/devel/dbic/dbgit/lib:$PERL5LIB"
export DBICTEST_SQLT_DEPLOY=0
export DBIC_ASSERT_NO_ERRONEOUS_METAINSTANCE_USE=1
export DBIC_ASSERT_NO_FAILING_SANITY_CHECKS=1

# these fail with ERRONEOUS_METAINSTANCE_USE alone
# (S::L fails due to PG_DSN but I think is ok besides that)
for d in \
    DBICx::Shortcuts \
    DBIx::Class::Bootstrap::Simple \
    DBIx::Class::Preview \
    DBIx::Class::Schema::Loader \
    Pinto \
; do \
  DBIC_ASSERT_NO_ERRONEOUS_METAINSTANCE_USE=0 \
  DBIC_ASSERT_NO_FAILING_SANITY_CHECKS=0 \
  DBICTEST_PG_DSN= \
  cpanm -v --reinstall $d 2>&1 \
| tee -a /dev/shm/umpfh \
| grep -P -B1 'sanity check|emit_|^(Building and testing|Result:)' || exit 1 \
; done

# these emit various san-check related problems
for d in \
    RapidApp \
    Data::OFAC \
    DBIx::Class::VirtualColumns \
    "DBD::SQLite@1.35 Handel" \
    DBIx::Class::RDBOHelpers \
    CatalystX::CRUD::ModelAdapter::DBIC \
    DBICx::Indexing \
    DBICx::TestDatabase \
    DBIx::Class::BitField \
    DBIx::Class::I18NColumns \
    DBIx::Class::PhoneticSearch \
    DBIx::Class::RandomColumns \
    DBIx::Class::ResultSource::MultipleTableInheritance \
    DBIx::Class::Result::ProxyField \
    DBIx::Class::Schema::PopulateMore \
    DBIx::Class::Tree \
    Foorum \
    Interchange6::Schema \
    Test::DBIx::Class \
    TreePath \
; do \
  DBIC_ASSERT_NO_FAILING_SANITY_CHECKS=0 \
  cpanm -v --reinstall $d 2>&1 \
| tee -a /dev/shm/umpfh \
| grep -P -B1 'sanity check|emit_|^(Building and testing|Result:)' || exit 1 \
; done

# these are entirely unaffected \o/
for d in \
    Dancer2::Plugin::DBIC \
    App::DBCritic \
    App::DH \
    AproJo \
    Articulate \
    Authorization::RBAC \
    BackPAN::Index \
    Bio::Chado::Schema \
    Bot::BasicBot::Pluggable::Module::Notes \
    Bracket \
    Business::Cart::Generic \
    Business::DPD \
    Catalyst::Authentication::Credential::Facebook \
    Catalyst::Authentication::Store::DBIx::Class \
    Catalyst::Controller::DBIC::API \
    Catalyst::Model::DBIC::Plain \
    Catalyst::Model::DBIC::Schema \
    Catalyst::Model::DBIC::Schema::PerRequest \
    Catalyst::Model::FormFu \
    Catalyst::Plugin::Authentication::Store::DBIC \
    Catalyst::Plugin::Authorization::Abilities \
    Catalyst::Plugin::AutoCRUD \
    Catalyst::Plugin::DBIC::Schema::Profiler \
    Catalyst::Plugin::Session::Store::DBIC \
    Catalyst::TraitFor::Controller::DBIC::DoesPaging \
    Catalyst::TraitFor::Model::DBIC::Schema::RequestConnectionPool \
    Catalyst::TraitFor::Model::DBIC::Schema::Result \
    Catalyst::TraitFor::Model::DBIC::Schema::WithCurrentUser \
    Catalyst::View::CSV \
    CatalystX::Controller::ExtJS::REST::SimpleExcel \
    CatalystX::Crudite \
    CatalystX::Eta \
    CatalystX::OAuth2 \
    CatalystX::Resource \
    CGI::Application::Plugin::Authentication::Driver::DBIC \
    CGI::Application::Plugin::DBIC::Schema \
    CGI::Application::Plugin::DBIx::Class \
    CGI::Application::Plugin::ExtJS \
    CGI::Session::Driver::dbic \
    Cookieville \
    Dancer2::Plugin::Auth::Extensible::Provider::DBIC \
    Dancer2::Session::DBIC \
    Dancer::Plugin::Auth::Extensible::Provider::DBIC \
    Dancer::Plugin::Auth::RBAC::Credentials::DBIC \
    Dancer::Plugin::Auth::RBAC::Permissions::DBIC \
    Dancer::Plugin::DBIC \
    Dancer::Session::DBIC \
    Data::Morph \
    DBICx::AutoDoc \
    DBICx::Backend::Move \
    DBICx::DataDictionary \
    DBICx::Deploy \
    DBICx::Hooks \
    DBICx::MapMaker \
    DBICx::MaterializedPath \
    DBICx::Modeler \
    DBICx::Sugar \
    DBICx::TxnInsert \
    DBIx::Class::AlwaysUpdate \
    DBIx::Class::AuditAny \
    DBIx::Class::AuditLog \
    DBIx::Class::BatchUpdate \
    DBIx::Class::Candy \
    DBIx::Class::ColumnDefault \
    DBIx::Class::CompressColumns \
    DBIx::Class::Cursor::Cached \
    DBIx::Class::CustomPrefetch \
    DBIx::Class::DateTime::Epoch \
    DBIx::Class::DeleteAction \
    DBIx::Class::DeploymentHandler \
    DBIx::Class::DigestColumns \
    DBIx::Class::DynamicDefault \
    DBIx::Class::DynamicSubclass \
    DBIx::Class::EasyFixture \
    DBIx::Class::ElasticSync \
    DBIx::Class::EncodeColumns \
    DBIx::Class::EncodedColumn \
    DBIx::Class::Factory \
    DBIx::Class::Fixtures \
    DBIx::Class::ForceUTF8 \
    DBIx::Class::FormatColumns \
    DBIx::Class::FormTools \
    DBIx::Class::FromSledge \
    DBIx::Class::FrozenColumns \
    DBIx::Class::GeomColumns \
    DBIx::Class::Graph \
    DBIx::Class::Helpers \
    DBIx::Class::HTML::FormFu \
    DBIx::Class::HTMLWidget \
    DBIx::Class::Indexed \
    DBIx::Class::InflateColumn::Authen::Passphrase \
    DBIx::Class::InflateColumn::BigFloat \
    DBIx::Class::InflateColumn::Boolean \
    DBIx::Class::InflateColumn::Currency \
    DBIx::Class::InflateColumn::DateTime::Duration \
    DBIx::Class::InflateColumn::DateTime::WithTimeZone \
    DBIx::Class::InflateColumn::DateTimeX::Immutable \
    DBIx::Class::InflateColumn::FS \
    DBIx::Class::InflateColumn::IP \
    DBIx::Class::InflateColumn::Markup::Unified \
    DBIx::Class::InflateColumn::Math::Currency \
    DBIx::Class::InflateColumn::Object::Enum \
    DBIx::Class::InflateColumn::Path::Class \
    DBIx::Class::InflateColumn::Serializer \
    DBIx::Class::InflateColumn::Serializer::JSYNC \
    DBIx::Class::InflateColumn::Serializer::Role::HashContentAccessor \
    DBIx::Class::InflateColumn::Serializer::Sereal \
    DBIx::Class::InflateColumn::Time \
    DBIx::Class::InflateColumn::TimeMoment \
    DBIx::Class::InflateColumn::URI \
    DBIx::Class::IntrospectableM2M \
    DBIx::Class::Journal \
    DBIx::Class::LibXMLdoc \
    DBIx::Class::LookupColumn \
    DBIx::Class::MaterializedPath \
    DBIx::Class::Migration \
    DBIx::Class::Numeric \
    DBIx::Class::Objects \
    DBIx::Class::OptimisticLocking \
    DBIx::Class::ParameterizedJoinHack \
    DBIx::Class::PassphraseColumn \
    DBIx::Class::QueriesTime \
    DBIx::Class::QueryLog \
    DBIx::Class::QueryLog::WithStackTrace \
    DBIx::Class::QueryProfiler \
    DBIx::Class::RandomStringColumns \
    DBIx::Class::Relationship::Predicate \
    DBIx::Class::Report \
    DBIx::Class::Result::ColumnData \
    DBIx::Class::ResultSet::AccessorsEverywhere \
    DBIx::Class::ResultSet::Data::Pageset \
    DBIx::Class::ResultSet::Excel \
    DBIx::Class::ResultSet::Faceter \
    DBIx::Class::ResultSet::HashRef \
    DBIx::Class::ResultSet::RecursiveUpdate \
    DBIx::Class::Result::Validation \
    DBIx::Class::SaltedPasswords \
    DBIx::Class::Schema::Config \
    DBIx::Class::Schema::Diff \
    DBIx::Class::Schema::RestrictWithObject \
    DBIx::Class::Schema::ResultSetAccessors \
    DBIx::Class::Schema::Versioned::Inline \
    DBIx::Class::Service \
    DBIx::Class::SingletonRows \
    DBIx::Class::Storage::DBI::mysql::backup \
    DBIx::Class::Storage::DBI::ODBC::OPENEDGE \
    DBIx::Class::Storage::DBI::OpenEdge \
    DBIx::Class::StorageReadOnly \
    DBIx::Class::Storage::TxnEndHook \
    DBIx::Class::TimeStamp \
    DBIx::Class::Tokenize \
    DBIx::Class::TopoSort \
    DBIx::Class::Tree::CalculateSets \
    DBIx::Class::Tree::Mobius \
    DBIx::Class::UnicornLogger \
    DBIx::Class::UserStamp \
    DBIx::Class::UUIDColumns \
    DBIx::Class::Validation \
    DBIx::Class::Validation::Structure \
    DBIx::Class::WebForm \
    DBIx::Class::Wrapper \
    DBIx::Table::TestDataGenerator \
    Data::Importer \
    Dwimmer \
    ETLp \
    ExtJS::Generator::DBIC \
    Finance::QuoteDB \
    Form::Processor::Model::DBIC \
    Form::Sensible::Reflector::DBIC \
    FormValidator::Simple::Plugin::DBIC::Unique \
    Galileo \
    GenOO \
    HTML::FormFu::ExtJS \
    HTML::FormFu::Model::DBIC \
    HTML::FormHandler::Model::DBIC \
    Hyle \
    IronMan::Schema \
    KiokuDB::Backend::DBI \
    Log::Log4perl::Appender::DBIx::Class \
    Mixin::ExtraFields::Driver::DBIC \
    Module::CPANTS::ProcessCPAN \
    Mojolicious::Plugin::DBICAdmin \
    MooseX::Types::DBIx::Class \
    OpusVL::AppKit \
    OpusVL::AppKit::Schema::AppKitAuthDB \
    OpusVL::Preferences \
    OpusVL::SysParams \
    Prosody \
    Pulp \
    RackMan \
    Reaction \
    Schema::RackTables \
    Tapper::MCP \
    Tapper::Schema \
    Template::Provider::CustomDBIC \
    Template::Provider::DBIC \
    Template::Provider::PerContextDBIC \
    Template::Provider::PrefixDBIC \
    Test::DBIC::ExpectedQueries \
    Test::DBIC::Schema::Connector \
    Test::DBIx::Class::Schema \
    Test::Fixture::DBIC::Schema \
    Tie::DBIx::Class \
    Types::DBIx::Class \
    WebAPI::DBIC \
    WebNano::Controller::CRUD \
    Web::Util::DBIC::Paging \
    Web::Util::ExtPaging \
    WWW::Hashbang::Pastebin \
    WWW::RobotRules::DBIC \
    YAWF \
    YATT::Lite \
    Yeb::Plugin::DBIC \
    "DBD::SQLite@1.35 Catalyst::ActionRole::BuildDBICResult DBIx::NoSQL Jedi::Plugin::Session Jedi::Plugin::Auth" \
    "Test::More@1.001014 Test::DBIx::Class::Stats" \
    "Mojolicious@3.91 ExpenseTracker" \
    "Dancer2@0.166001 Strehler Strehler::Element::Extra Strehler::RSS" \
; do \
  cpanm -v --reinstall $d 2>&1 \
| tee -a /dev/shm/umpfh \
| grep -P -B1 '^(Building and testing|Result:)' || exit 1 \
; done

echo
echo 'YAY!'
exit 0

Annotate every indirect sugar-method

Now that the churn is over we can add annotations to each method a user ought
to never override. See next commit for the actual use case and diagnostics
emitter.

Unfortunately this adds yet another small compile-time hit, similar to
73f54e27 (a hit incurred regardless whether the upcoming validation framework
is used or not). Complete test of DBIx::Class::Helpers v2.032002 goes from
about ~64.6 seconds CPU time up to ~65.5, adding another ~1% of startup speed
loss. The savings in debugging sessions should make this all worth it... or
so one hopes.

Some test suite corrections ahead of next commits

Splitting this off for easier reading

An extra bit of diag on incomplete rsrc re-register

Due to the counterintuitive nature of the metadata subsystem, a user wishing
to modify the metadata for a result class at runtime (post $schema instance
initialization), may end up in a situation where *everything* appears to work
but falls apart on the next call to My::Schema->connect. In fact I myself made
this very mistake in https://github.com/ctrlo/GADS/pull/1/files, even though
I was pretty well aware of the dangers at the time.

In order to make this go away for good reuse the meta-metadata kept around to
track rsrc ancestry and modifications, and emit a warning alerting folks to
the potential problem (the *actual* problematic desync will also be warned
about at a later step by the stale-metadata diag).

Comprehensive diagnostic on incorrect ResultSource metadata use

This commit is the second part of the permanent RT#107462 solution f064a2ab.
Given the amount of changes to the resultsource metadata subsystem, I can
not be certain that everything has been accounted for, even despite the
comprehensive assertion harness added in the previous commits passing with
flying colors on the entire reverse dep list detailed in c8b1011e.

As Dave Howorth correctly pointed out in [1], the diagnostic of why something
stopped working within the metadata subsystem is pretty daunting, especially
given the ass-backward nature of DBIC's implementation of it. The (minimal
but present) performance hit is deemed worth it in order to be able to
present this information to downstream. One unexpected bit of good news is
that none of the downstreams tested emitted the warning, which is an extra
point of confidence that the main change of f064a2ab, and the even more
dangerous change in 9e36e3ec are both solid.

The gist here is that this:

~/devel/dbic$ perl -Ilib -It/lib -MDBICTest -e '
  my $art = DBICTest->init_schema->resultset("Artist")->find(1);

  DBICTest::Schema::Artist->add_column("foo");

  DBICTest::Schema->source("Artist")->add_columns("foo");

  $art->has_column("foo");
'

now emits a comprehensive non-trappable warning along the lines of:

DBIx::Class::ResultSource::Table=HASH(0x2a32660) (the metadata instance
of source 'Artist') is *OUTDATED*, and does not reflect the modifications
of its *ancestors* as follows:
  * DBIx::Class::ResultSource::Table=HASH(0x24ed770)->add_column(...) at -e line 4
  * DBIx::Class::ResultSource::Table=HASH(0x2955da8)->add_columns(...) at -e line 6
Stale metadata accessed by 'getter' DBIx::Class::ResultSource::Table=HASH(0x2a32660)->has_column(...)
  within the callstack beginning at lib/DBIx/Class/ResultSource.pm line 231.
DBIx::Class::ResultSource::get_rsrc_instance_specific_attribute(DBIx::Class::ResultSource::Table=HASH(0x2a32660), "_columns") called at (eval 95) line 2
DBIx::Class::ResultSource::_columns(DBIx::Class::ResultSource::Table=HASH(0x2a32660)) called at lib/DBIx/Class/ResultSource.pm line 732
DBIx::Class::ResultSource::has_column(DBIx::Class::ResultSource::Table=HASH(0x2a32660), "foo") called at (eval 70) line 19
DBIx::Class::ResultSourceProxy::has_column(DBICTest::Artist=HASH(0x311e338), "foo") called at -e line 8

The performance hit consistently measures in the ~1.5% range: the test suite
of @frioux's DBIx::Class::Helpers v2.032002 consistently completes within
roughly ~63.7 CPU seconds at the base of this branch, yet climbs to ~64.6 as
of this commit (on an idle low-clocked Xeon L3426)

The warning can not be disabled for the time being (aside from monkeypatching
DBIC::ResultSource) - the wide-range testing indicates it only fires on real
legitimate problems. Hopefully I am making the right call...

[1] http://lists.scsys.co.uk/pipermail/dbix-class/2016-January/012127.html

Centralize all user-side rsrc calls to go through result_source()

This ensures the user will always get a sensible exception when the rsrc
metadata object has not yet been initialized (as introduced in 5298bbb5):

Before:
 ~$ perl -e 'use base "DBIx::Class::Core"; __PACKAGE__->add_column("foo")'
 Can't locate object method "result_source_instance" via package "main" at .../ResultSourceProxy.pm line 29.

After:
 ~$ perl -e 'use base "DBIx::Class::Core"; __PACKAGE__->add_column("foo")'
 DBIx::Class::Row::result_source(): No ResultSource instance registered for 'main', did you forget to call main->table(...) ? at -e line 1

Add a shitload of assertions to track we are doing the right thing in all
cases. This more or less concludes the rsrc changeset necessary to resolve
all ambiguities. The next commit adds user-visible warnings when things go
off the rails

The changeset was successfully tested against the list of distributions
in c8b1011e with no ill effects being observed. Thus I am pretty damn
confident I rather nailed it >.>

Fold column_info() into columns_info()

Not sure how I never noticed the utter code duplication.

Resolve $rsrc instance duality on metadata traversal

Make result_source a straight wrapper around result_source_instance. This
should fix all the fallout introduced in 0.082800 (4006691d), which sadly
went undetected all the way until ~7 months after its release. Ultimately
this is my fault, as I had an early warning, and even later made a conjecture
which spot exactly may blow up in my face (read towards end of 350e8d57)

Exploit the fact that result_source_instance until very recently was a toss-up
between a CAG 'inherited' and a Class::Data::Inheritable (removed in 5e0eea35)
with CAG not really involved in result-instance level calls, and the latter
making it downright impractical due to the closure-based approach. Combined
with the fact that result_source was a 'simple'-type accessor pointing at
the '_result_source' hash-slot allows us (at least seemingly) to switch to a
setup where result_source is nothing but a wrapper around a CAG inherited
accessor result_source_instance which point to the named slot '_result_source'

The changeset is deceptively small, and is kept this way for easier auditing.
See next commit for the armada of additional testing to verify the entire
stack is in fact still solid.

Keep track of result source instance ancestry

The oddball external registry (instead of directly-linked objects) is due
to shit like 31399b48

For now this doesn't realy do anything: See several commits higher why this
is needed in the first place.

Fully separate parent and child resultsource metadata

Ensure that all attributes are shallow-copied on "clone". Currently this
means that the following are *NO LONGER* shared between rsrc clones:

_unique_constraints
_primaries
source_info

This seems just as cocky and reckless as the clusterfuck in 4006691d/RT#107462
and it most likely will have the same invisible-yet-dire consequences for
various downstreams. However there is a plan in place several commits ahead
allowing sidestepping the impossibility to debug a potential fallout.

Add a clone method to ResultSource, switch obvious spots to it

Not messing with the ::ResultSourceProxy::Table clusterfuck for now, too many
things can go wrong. Instead will explicitly instrument the callsites in
subsequent commits.

Also add assertions this does not get routed around: such use will throw from
here on out as long as one enables the necessary assert:

~$ DBIC_ASSERT_NO_ERRONEOUS_METAINSTANCE_USE=1 perl -Ilib -MDBIx::Class -e '
  bless ({}, "DBIx::Class::ResultSource")
'

Revert C3-fication d009cb7d and fixups 7f068248 and 983f766d

While on its surface this was a good idea, it actually hides problems even
more: by the time we arrive at a useful hook-point to check the current MRO,
something likely already changed it from under us, and the old effects are
all masked away for good.

So instead scale back as much as possible, and set 'c3' where needed as
lazily as practical. In order to satisfy the mro requirements imposed by
5e0eea35 we do the "flip" during the ->source() stage.

Additionally we record the original setting any time we switch the mro on
foreign classes (two such spots in the codebase). A later commit will use
this information to add the final bit of sanity to this clusterfuck.

Rename variables/shuffle some code, preparing for next commits

Zero functional changes

Read under -w

Abstract our internal capture_stderr test routine

Will need it for even more tests later on, but not sufficiently often to
warrant depending on Capture::Tiny - just go with what we need

Fix misleading error on deployment_statements in void ctx

Due to how Context::Preserve operates the following would result in a
non-sensical error:

perl -MDBIx::Class::Schema -e '
  DBIx::Class::Schema->connect("dbi:SQLite::memory:")->deployment_statements;
  1
'

Fix false negatives in lean_startup.t

Before this commit a 'use Devel::Dwarn' somewhere deep in e.g. ::SQLMaker
would *not* have been detected.

Also fix improperly applied C-ism: the following decidedly does not DTRT

 do 1 while { ... }

I never noticed this being a problem until a fatfingered `>&1` turned into
a `>1`, which in turn created a file named 1 in the current directory with
garbage in it, which *in turn* the `do 1 ...` tried to execute. Sigh...

Fix error-eating thinko from 6c7ca962

$@ is not visible in $SIG{__DIE__}

Restore TODO checking for Taint + pkg_gen inconsitencies

Now that https://github.com/Test-More/test-more/issues/683 we can bring the
TODO back - will get an alert for an eventual fix...

Add an explicit Sub::Quote dep in ::_Util

Failures too confusing otherwise

Work around the FIXME in the previous commit

Based on @haarg's excellent detective work: https://is.gd/perl_mro_taint_wtf

Get rid of Package::Stash \o/

Internal tooling advanced sufficiently without planning for any of that:
a good indicator things are on the right track!

Read under -w

Add a get_subname to _Util

Insulate DBIC::Carp from rogue can() overrides

Add more forceful (STDERR-direct) warning emitter

Switch some of the most critical announements to it

Fix POISON_ENV warning missed in both 5c33c8be and 44c1a75d

Silence inactionable warning (mainly on travis)

(travis) Switch to our own copy of the Firebird ODBC driver

Sourceforge is just way too unstable

(travis) Properly diagnose potential OOM in 50_after_success.bash

Idea originally introduced in ac4e80df

(travis) Add poisoning to the base non-clean build run

Fill in missing documentation in ::Schema / ::ResultSource

Audit all local() calls within lib/ and t/lib

Correct some of them to fire less frequently (local is *expensive*)

Expand describe_class_methods testing yet again

This should be the end of adjustments, so many corner cases...

Use a single cache struct for entirety of describe_class_methods

This will allow influencing the cache from outside like shown below, (but
please, DO NOT DO SO), and in turn will make sanity checks on 5.8 somewhat
acceptable *by default* \o/

  $...::__describe_class_query_cache->{"!internal!"} = {};

Add hash-based ISA lookup to RV of describe_class_methods

Expand signature of describe_class_methods for forward compat

It is likely extra options/attrs will need to be passed down the road -
hence do not lock ourselves into positional args

Raise the global lock timeouts

15 minutes on my laptop on battery with all assertions no longer cuts it :(

Add true/false non-singleton boolean objects

This will be needed for the sanitychecker on OLD_MRO

Extra test of UNIVERSAL handling in describe_class_methods

While parents of UNIVERSAL *do* "inherit" some of UNIVERSAL's methods, making
this circularity apparent is out of scope for this tool. Doing otherwise will
complicate consumer code for no apparent benefit. Thus add an explicit test
that "this is how it is".

Revert TempExtlib ( b46b85376 ) - new Sub::Quote shipped

Bring out the big-paranoia-harness - make describe_env infallible

As desmonstrated by the previous commit: testing is no substitute for proper
defensive programs. Stop-gap until this is spun off on its own

Fix describe_env failure on nonexistent @INC on Win32

Despite this code undergoing wide CPAN testing last year, and having zero
functional changes since, there were *still* bugs lurking inside :/

Minor cosmetic fix of describe_environment

Fix false-positives in the no-external-evals assert ( ddcc02d14 )

If there is no eval frame above the exception action - there is nothing to
report to the user

Add 'PERL_VERSION' foldable constant, switch lib-ish things over

No point changing the many $] references in .t's themselves

Minor improvements to the maint helper scripts

Restore 'timezone' field in column info ( extends eef9b484 )

The keys in the column info hash are semi-public API, and 'timezone' in
particular is used by DBIx::Class::InflateColumn::DateTime::WithTimeZone.

Keep documenting time_zone as the main name, but note that it's stored
under both keys.

Proper changelog after I bothced it in e400c82d

Ensure describe_environment does not break its output in half

Slight POD correction

Add changelog entry on 90c9dd1d, 757891ed and 89203568

Sample (not ideal - could be *SO* much better ) timings from included bencher:

Before (0.0828xx):
62951 byte-long query generated (via as_query()) in: 4.975237 seconds (take 1)
62951 byte-long query generated (via as_query()) in: 4.995723 seconds (take 2)
62951 byte-long query generated (via as_query()) in: 4.964793 seconds (take 3)
62951 byte-long query generated (via as_query()) in: 4.96168 seconds (take 4)
62951 byte-long query generated (via as_query()) in: 4.991396 seconds (take 5)
62951 byte-long query generated (via as_query()) in: 4.988478 seconds (take 6)
62951 byte-long query generated (via as_query()) in: 4.977612 seconds (take 7)
62951 byte-long query generated (via as_query()) in: 4.98648 seconds (take 8)
62951 byte-long query generated (via as_query()) in: 4.999984 seconds (take 9)

After:
62951 byte-long query generated (via as_query()) in: 0.429634 seconds (take 1)
62951 byte-long query generated (via as_query()) in: 0.416169 seconds (take 2)
62951 byte-long query generated (via as_query()) in: 0.430782 seconds (take 3)
62951 byte-long query generated (via as_query()) in: 0.416879 seconds (take 4)
62951 byte-long query generated (via as_query()) in: 0.426492 seconds (take 5)
62951 byte-long query generated (via as_query()) in: 0.428975 seconds (take 6)
62951 byte-long query generated (via as_query()) in: 0.413018 seconds (take 7)
62951 byte-long query generated (via as_query()) in: 0.428731 seconds (take 8)
62951 byte-long query generated (via as_query()) in: 0.413206 seconds (take 9)

Remove changelog entries included in 0.082830

Simplify our quote_sub override: Sub::Quote now has native attr support

Change the leaktracer to no longer rely on %Sub::Quote::QUOTED

Frees up @haarg to do as he sees fit in the future

Remove useless eval in the leaktracer on 5.8.3+

As a bonus fix a subtle bug where the very first ref encountered was never
traced, as the postincrement caused its slot to be deleted - ARGH!

Remove code forgotten in 085dbdd69

Remove preemptive DESTROY guard from 87f4bab0 / d63c9e64

It has been on CPAN sufficiently long, and would be needlesly pessimizing
the upcoming sanity check framework.

Allow alternative mro-type specification on method listing

This is needed for the mro sanity check further up

Account for 'poor man role application' method plumbing on 5.8

This also has the effect of greatly simplifying the OLD_MRO case

Properly handle UNIVERSAL ancestry in describe_class_methods

Obscure but possible nevertheless.

Fix describe_class_methods on non-mergeable DFS mro

Instead of trying to deduplicate - simply track which methods are locally
defined, and use that info combined with a reverse ISA-per-select-MRO to
build the final stack.

As a result the code is even more efficient and can now deal with real-life
insane hierarchies like:

https://metacpan.org/source/MJFLICK/DBIx-Class-Bootstrap-Simple-0.03/lib/DBIx/Class/Bootstrap/Simple.pm#L93

Name describe_class_methods arguments earlier

The attribute::get() caching seems to only add noise in benchmarks,
so remove that. Same for the pre-check on recursion - remove that as well

Fix m2m regression from 8a67d9cf (simple but deadly)

Add extra maint tooling - got tired of writing this smoke cmd by hand

(travis) Temporarily disable {halt_on_failure} for cperl

It is not clear whether there is a way around the root cause:
https://github.com/rurban/distroprefs/commit/30792f7e95ca76ac1c1e73d0662dce22168c9df9#commitcomment-17817389

(travis) Revert parts of e66f0ee0 and ee3a37d3

The typing of @array * $int got relaxed, and it turns out c5.22.2 worked
just fine *without* distroprefs, so I never noticed them being ignored

(travis) Work around a bad tradeoff in cperl-5.24-to-be

https://github.com/perl11/cperl/issues/153#issuecomment-224515895
http://irclog.perlgeek.de/perl11/2016-06-08#i_12624951

(travis) Add cperl master to the smoke roster, bump to 5.22.3

(travis) Report the perl (and vm state) early before deps can fail

(travis) Mini-utility to download travis reports

I've had enough waiting for their shit site :/

Base more tests on DBICTest::BaseSchema (needed further up)

And yet another INDIRECT guard missed in both e5053694 and d99f2db7

Introduce the describe_class_methods() utility function

This code will be needed several commits later to tie together the hierarchy
validation work.

Returns a comprehensive list of methods and related trivia. This required
way more code than one would hope, this part of perl is *really* hateful.

Read test changes under -w

Everything is implemented on "bare metal" (no Package::Stash, very aggressive
caching) as this needs to be as efficient as possible. Currently timings on
old and new MRO are roughly such on a downclocked X201 / M540:

~/devel/dbic$ perlbrew exec --with 5.8.5,5.16.2,5.24.0_rc1 \
  perl -T -Ilib -It/lib -MDBICTest -MTime::HiRes=time -e '
    my $t0 = time;
    sub tstamp {
      printf "%.6f\n", time - $t0;
      $t0 = time;
    }

    tstamp();

    for ( (qw(
      DBICTest::Schema::Artist
      DBICTest::Schema::CD
      DBICTest::Schema::Track
      main
    )) x 2 ) {
      print "describing $_\n";
      DBIx::Class::_Util::describe_class_methods($_);
      tstamp();
    }
  '

5.8.5
==========
0.000005
describing DBICTest::Schema::Artist
0.224748
describing DBICTest::Schema::CD
0.066118
describing DBICTest::Schema::Track
0.090433
describing main
0.003152
describing DBICTest::Schema::Artist
0.038846
describing DBICTest::Schema::CD
0.038390
describing DBICTest::Schema::Track
0.043453
describing main
0.002128

5.16.2
==========
0.000005
describing DBICTest::Schema::Artist
0.077804
describing DBICTest::Schema::CD
0.007684
describing DBICTest::Schema::Track
0.013071
describing main
0.001073
describing DBICTest::Schema::Artist
0.000109
describing DBICTest::Schema::CD
0.000096
describing DBICTest::Schema::Track
0.000098
describing main
0.000041

5.24.0_rc1
==========
0.000005
describing DBICTest::Schema::Artist
0.044058
describing DBICTest::Schema::CD
0.006093
describing DBICTest::Schema::Track
0.011004
describing main
0.000735
describing DBICTest::Schema::Artist
0.000118
describing DBICTest::Schema::CD
0.000114
describing DBICTest::Schema::Track
0.000113
describing main
0.000059

Additional sanity-checking of this deceptively simple code was performed by
sad brute-forcing of the entire test schema set ( at the time of this commit
the cumulative sum output was 0x1a65e78e316348104ab9cdc3e474c79096 )

perlbrew exec --with 5.8.5,5.10.0,5.16.2,5.18.0,5.20.0,5.24.0_rc1 \
perl -T -Ilib -It/lib -MDBICTest -e '
  use Math::BigInt;
  use Digest::MD5 "md5_hex";
  use List::Util 'shuffle';
  use Data::Dumper::Concise;
  use DBIx::Class::_Util qw( describe_class_methods uniq );

  my $sum = Math::BigInt->new(0);

  for ( shuffle uniq sort map { ( defined Scalar::Util::blessed $_ ) ? ref $_ : $_ } (
    qw(
      DBIx::Class::ResultSource
      DBIx::Class::Core
      DBIx::Class::ResultSet
      DBICTest::Schema
    ),
    ( map {
      $_,
      $_->result_class,
      $_->resultset_class,
    } map { DBICTest::Schema->source($_) } DBICTest::Schema->sources ),
  ) ) {
    my $desc = describe_class_methods($_);

    # unstable between invocations
    delete $desc->{cumulative_gen};

    # only available on 5.10+
    delete $desc->{methods}{DOES};

    # only available on 5.18+
    delete $desc->{methods}{"(("};

    $sum += Math::BigInt->new( "0x" . md5_hex(Dumper($desc)) );
  }

  print $sum->as_hex;
'

Introduce DBIC-specific method attribute support

When attribute support was added back in ed28f830 it was done in a weird
roundabout manner, with the only way to access the attributes via a chained
class accessor __attr_cache hidden behind a cascading method _attr_cache.

This is wasteful and rather inelegant. To mitigate this, and the propensity
of DBIC to eat any attribute it can lay its hands on, introduce special
handling for attributes prefixed with DBIC_

Any such attributes are handled by a much simpler storage system, and are
not made available to the legacy _attr_cache interface.

Attribute handling got too complex - move it into a component

No functional changes, just c/p code around
For some reason git diff -C -C -M doesn't work here...