SI-6565 Adds missing flag values to reflection API

Among the flags requested by our users, the most popular are definitely
PARAMACCESSOR and CASEACCESSOR. Among other things that are missing in
2.10.x are SYNTHETIC and its close friend ARTIFACT. Apparently, SYNTHETIC
was was added somewhen during the 2.11.0-M* development cycle, so I only
has to introduce ARTIFACT.

There was also METHOD as requested by Paul in https://github.com/xeno-by/declosurify/blob/ce6c55b04086c755102227dd8124b0bf0dac46e1/src/main/scala/macros.scala#L102,
but the absence of that one is compensated by the fact that it’s only needed
when manually creating symbols, and for that we already have Symbol.newMethodSymbol.

This doesn't remove the necessity to see SI-6267 through (read the recently
updated issue description for more information!), but that'd be a significant
change, so let's delay it until better times.
SI-7533 Adds Symbol.isAbstract

Amazingly enough, we've missed the fact that non-type symbols can also
be abstract. Having been enlightened by this, I'm exposing isDeferred
and merging it along with isAbstractType and isAbstractClass into the
unified Symbol.isAbstract method.
SI-6733 LOCAL, isLocal, and private[this]

Due to an unfortunate name collision, internal.Symbols#Symbol.isLocal
means something different from Flag.LOCAL. Therefore api.Symbols#Symbol.isLocal
was directly violating its documentation.

Since we can’t give api#isLocal an implementation different from internal#isLocal,
we have to rename, and for that occasion I have come up with names
api#isPrivateThis and api#isProtectedThis, which in my opinion suits the
public API better than internal#isPrivateLocal and internal#isProtectedLocal.

Given the extraordinary circumstances of having no way for api#isLocal
to work correctly, I’m forced to remove api#isLocal without a deprecation
notice, exercising our right to break experimental APIs, something that
we have never done before for reflection or macros. This is sad.
disambiguates uses of “local” in internal symbol API

There’s been a conflation of two distinct meanings of the word “local”
in the internal symbol API: the first meaning being “local to this”
(as in has the LOCAL flag set), the second meaning being “local to block”
(as in declared in a block, i.e. having owner being a term symbol).

Especially confusing is the fact that sym.isLocal isn’t the same as
sym.hasFlag(LOCAL), which has led to now fixed SI-6733.

This commit fixes the semantic mess by deprecating both Symbol.isLocal and
Symbol.hasLocalFlag (that we were forced to use, because Symbol.isLocal
had already been taken), and replacing them with Symbol.isLocalToThis
and Symbol.isLocalToBlock. Unfortunately, we can’t remove the deprecated
methods right away, because they are used in SBT, so I had to take small
steps.
proceeds with the quest of removing `local` from names

Continuing in the direction set by the parent commit, this commit
rephrases some more usages of `local` in names and comments in typer.
SI-8187 api#Symbol.name now has precise type

I don’t remember why we didn’t have written it as `def name: NameType`
in the first place (probably because of path-dependent bugs that were
popping up every now and then when we were developing the first version
of reflection API), but now there are definitely no obstacles to that.
does away with implicits in StandardLiftables

Less magic - less opportunities for mystification.
fixes indentation in Annotations.scala
SI-8190 erasure identities for types in reflection API

Makes sure that almost every abstract type declared in reflection API
erases to a unique class, so that they can be adequately used for
method overloading to the same extent that tags allow them to be used
in pattern matching.

The only two exceptions from this rule are the types whose implementations
we do not control: FlagSet that is implemented as Long and RuntimeClass
that is implemented as java.lang.Class[_].
additional class tags for reflection API

Introduces a test that iterates all abstract types in reflection API
and makes sure that every one of them has an associated class tag.

After being introduced, the test has immediately failed exposing
the lack of tags for TreeCopier, Mirror and RuntimeClass, which has been
subsequently fixed in this commit.
SI-6379 adds MethodSymbol.exception

Following Simon’s request, this commit introduces a dedicated API
that can be used to acquire the list of exceptions thrown by a method,
abstracting away from whether it’s a Java or a Scala artifact.
SI-8192 adds ClassSymbol.isPrimaryConstructor

Exposes a popular code pattern in macros as a dedicated reflection API.
This simple commit, however, ended up being not so simple, as it often
happens with our compiler.

When writing a test for the new API, I realized that our (pre-existing)
MethodSymbol.isPrimaryConstructor API returns nonsensical results for
implementation artifacts (trait mixin ctors, module class ctors).

What’s even more funny is that according to our reflection internals,
even Java classes have primary constructors. Well, that’s not surprising,
because `primaryConstructor` is just `decl(ctorName).alternatives.head`.
Good thing that package classes don’t have constructors or that would
elevate the situation to three fries short of a happy meal.

At the moment, I’m too scared to fiddle with internal#Symbol.primaryConstructor,
because that could easily break someone right before RC1, so I simply
documented the findings in SI-8193 and postponed the actual work, except
for one thing - isJavaDefined symbols no longer have primary constructors.
SI-6484 adds Universe.typeOf[T](x: T)

This is a nice addition to Universe.typeOf[T], quite frequently useful
for inspecting ad-hoc types.

As promised by https://github.com/scala/scala/pull/1741, which represented
my previous stab at adding this API, I ran into problems when trying to
introduce the API naively.

  def typeOf[T](implicit ttag: TypeTag[T]): Type
  def typeOf[T: TypeTag](x: T): Type

The first problem came from the fact that even though they don't look
ambiguous, under certain circumstances, the couple of typeOf overloads
can become ambiguous. Concretely, ambiguity happens when T <: TypeTag[T],
which makes the compiler uncapable to choose an overload to typecheck
`typeOf[T](<materialized>: TypeTag[T])`. Luckily, defining x as a by-name
parameter fixes the problem.

  def typeOf[T](implicit ttag: TypeTag[T]): Type
  def typeOf[T: TypeTag](x: => T): Type

The second problem manifested itself in reification of snippets that
contained calls to typeOf. Apparently, materialized tags get rolled back
by reify as products of macro expansion, becoming replaced with
`implicitly[TypeTag[T]]`. Afterwards, subsequent rollback of TypeTree's
strips the replacement of its type argument, producing bare `implicitly`.
Back then when typeOf wasn't overloaded, this abomination typechecked
and worked correctly, but now, due to some weird reason, it stopped.
I have worked around this by performing the rollback on a larger scale -
instead of hunting down materialized tags, this commit detects calls
to typeOf and removes their implicit argument lists altogether.
SI-8194 adds Universe.symbolOf[T]

A very frequent use for a result of typeOf is obtaining an underlying
type symbol. Another thing that comes up occasionally at stack overflow
is a request to add facilities for reification of symbols.

This naturally suggests that our reflection API would benefit from a method
called symbolOf that can take a term or type argument and return an underlying
symbol.

While an API to extract a term symbol from an expression needs some time
to be designed and then implemented robustly (we don’t have untyped macros
so we’ll have to account for various desugarings), meaning that we probably
won’t have time for that in 2.11, a type symbol extractor seems to be
a very low-hanging fruit.
adds showDeclaration(sym: Symbol): String

As per Paul’s request, this commit exposes Symbol.defString, although
in a different way to ensure consistency with our other prettyprinting
facilities provided in the reflection API.
splits Type.normalize into dealias and etaExpand

normalize is a highly overloaded name and it also conflates two distinct
operators, so how about we give our users self-explaning atomic tools instead.
adds Type.typeArgs

It’s very probable that this is the single most requested method in the
entire reflection API of Scala 2.10.
SI-8063 exposes much needed conveniences for Type

As per Jason’s request, Type now features such important convenience
methods as typeArgs, typeParams, paramss, resultType and finalResultType
without requiring to perform any casts.
adds Type.companionType

Introduces a dedicated facility to go from a type to a type of its companion.
Previously we had to do something really horrible for that, something like:
tp.typeSymbol.companionSymbol.typeSignature.
sane semantics for Symbols.companionSymbol

While playing with tests for Type.companionType, I figured out that
companionSymbol isn’t what it seems to be:

scala> ScalaPackage.companionSymbol
res5: $r.intp.global.Symbol = <none>

scala> ScalaPackageClass.companionSymbol
res6: $r.intp.global.Symbol = package scala

Or even funnier observation:

scala> class C; object C
defined class C
defined object C

scala> val classC = typeOf[C].typeSymbol
classC: $r.intp.global.Symbol = class C

scala> val moduleC = classC.companionSymbol
moduleC: $r.intp.global.Symbol = object C

scala> classC.companionSymbol == moduleC
res0: Boolean = true

scala> moduleC.companionSymbol == classC
res1: Boolean = true

scala> moduleC.moduleClass.companionSymbol == moduleC
res2: Boolean = true

Of course, I rushed to clean this up, so that `companionSymbol` only
returns something other than NoSymbol if the target has a companion in
the common sense, not wrt the internal “class with the same name in the
same package” convention of scalac, and that `companionSymbol` for
module classes is a class, not a source module.

Unfortunately it’s not that easy, because api.Symbol#companionSymbol
has the same name as internal.Symbol#companionSymbol, so we can’t change
the behavior of the former without changing the behavior of the latter.

Therefore I deprecated api.Symbol#companionSymbol and introduced a replacement
called api.Symbol#companion with sane semantics.