SI-8134 SI-5954 Fix companions in package object under separate comp.

The tests cases enclosed exhibited two failures modes under
separate compilation.

  1. When a synthetic companion object for a case- or implicit-class
     defined in a package object is called for,
     `Namer#ensureCompanionObject` is used to check for an explicitly
     defined companion before decided to create a synthetic one.
     This lookup of an existing companion symbol by `companionObjectOf`
     would locate a symbol backed by a class file which was in the
     scope of the enclosing package class. Furthermore, because the
     owner of that symbol is the package object class that has now
     been noted as corresponding to a source file in the current
     run, the class-file backed module symbol is *also* deemed to
     be from the current run. (This logic is in `Run#compiles`.)

     Thinking the companion module already existed, no synthetic
     module was created, which would lead to a crash in extension
     methods, which needs to add methods to it.

  2. In cases when the code explicitly contains the companion pair,
     we still ran into problems in the backend whereby the class-file
     based and source-file based symbols for the module ended up in
     the same scope (of the package class). This tripped an assertion
     in `Symbol#companionModule`.

We get into these problems because of the eager manner in which
class-file based package object are opened in `openPackageModule`.
The members of the module are copied into the scope of the enclosing
package:

    scala> ScalaPackage.info.member(nme.List)
    res0: $r#59116.intp#45094.global#28436.Symbol#29451 = value List#2462

    scala> ScalaPackage.info.member(nme.PACKAGE).info.member(nme.List)
    res1: $r#59116.intp#45094.global#28436.Symbol#29451 = value List#2462

This seems to require a two-pronged defense:

  1. When we attach a pre-existing symbol for a package object symbol
     to the tree of its new source, unlink the "forwarder" symbols
     (its decls from the enclosing
     package class.

  2. In `Flatten`, in the spirit of `replaceSymbolInCurrentScope`,
     remove static member modules from the scope of the enclosing
     package object (aka `exitingFlatten(nestedModule.owner)`).

This commit also removes the warnings about defining companions
in package objects and converts those neg tests to pos (with
-Xfatal-warnings to prove they are warning free.)

Defining nested classes/objects in package objects still has
a drawback: you can't shift a class from the package to the
package object, or vice versa, in a binary compatible manner,
because of the `package$` prefix on the flattened name of
nested classes. For this reason, the `-Xlint` warning about
this remains. This issue is tracked as SI-4344.

However, if one heeds this warning and incrementatlly recompiles,
we no longer need to run into a DoubleDefinition error (which
was dressed up with a more specific diagnostic in SI-5760.)
The neg test case for that bug has been converted to a pos.
SI-5954 Invalidate TypeRef cache when opening package object

I noticed that the pos/5954d was tripping a println "assertion".
This stemmed from an inconsistency between
`TypeRef#{parents, baseTypeSeq}` for a package objects compiled
from source that also has a class file from a previous compilation
run.

I've elevated the println to a devWarning, and changed
`updatePosFlags`, the home of this evil symbol overwriting,
to invalidate the caches in the symbols info. Yuck.

I believe that this symptom is peculiar to package objects because
of the way that the completer for packages calls `parents` during
the Namer phase for package objects, before we switch the symbol
to represent the package-object-from-source. But it seems prudent
to defensively invalidate the caches for any symbol that finds its
way into `updatePosFlags`.
SI-5954 Add a TODO comment with an idea for future work

As the prophet once said:

  "'Tis better to never do at all than to have do and undo"

Let's try that in 2.12.
SI-7570 top-level codegen for toolboxes

Provides a way to inject top-level classes, traits and modules into
toolbox universes.

Previously that was impossible, because compile and eval both wrap their
arguments into an enclosing method of a synthetic module, which makes it
impossible to later on refer to any definitions from the outside.
SI-6411 reflection is now aware of posterasure

The `transformedType` method, which is used to bring Scala types to Java
world, was written in pre-valueclass times. Therefore, this method only
called transforms from erasure, uncurry and refChecks.

Now runtime reflection becomes aware of posterasure and as a consequence
methods, which have value classes in their signatures, can be called
without having to wrap them in catch-a-crash clause.

Another facet to this fix was the realization that value classes need
to be unwrapped, e.g. C(2) needs to be transformed to just 2, when they
are used naked in method signatures (i.e. `c` in `def foo(c: C)` needs
to be unwrapped, whereas `cs: List[C]`, `cs: C*` and even `cs: Array[C]`
do not).
updates the test for by-name value class parameters
unifies method and constructor handling in JavaMirrors

This automatically brings performance fixes and correct handling of
values class / by-name params into the constructor land.
SI-7328 FieldMirrors now support value classes
SI-8092 More verify for f-interpolator

Attempt to verify the nooks and crannies of the format string.

Allows all syntax in the javadoc, including arg indexes. If the
specifier after an arg has an index that doesn't refer to the arg,
a warning is issued and the missing `%s` is prepended (just as
for a part with a leading `%n`).

Other enhancements include detecting that a `Formattable` wasn't
supplied to `%#s`.

Error messages attempt to be pithy but descriptive.
SI-7933 REPL javax.script eval is cached result

The problem is that the repl underneath the script engine evaluates input to
val res0..resN, so it is a one shot operation. To allow repetition,
compile(script) now returns a CompiledScript object whose eval method can be
called any number of times.
add -Xsource:version to scalac man page

The flag was added in d43618a (PR #3340) by @huitseeker.
SI-8134 Address pull request feedback

Aesthetics only.
SI-8092 Refactor f-interp

A denshish refactor makes the FormatInterpolator a nice bundle
that destructures its input and flattens out the classes to
give the code some elbow room. Everything shifts left.

The `checkType` method is refolded and renamed `pickAcceptable`.

An additional test case captures the leading edge test, that
a % should follow a hole, and which is the most basic
requirement.
SI-8215: Correcting typo and splitting a long sentence in MatchIterator doc

Follow-up to 9c0ca62
SI-6169 Refine java wildcard bounds using corresponding tparam

Also fixes part of SI-8197. Necessary complement to SI-1786 (#2518),
because we now infer tighter bounds for RHSs to conform to.

When opening an existential, Java puts constraints in the typing environment
that are derived from the bounds on the type parameters of the existentially
quantified type, so let's do the same for existentials over java-defined
classes in skolemizeExistential...

Example from test case:

```
public class Exist<T extends String> {
  // java helpfully re-interprets Exist<?> as Exist<? extends String>
  public Exist<?> foo() { throw new RuntimeException(); }
}
```

In Scala syntax, given a java-defined `class C[T <: String]`, the
existential type `C[_]` is improved to `C[_ <: String]` before skolemization,
which models what Java does (track the bounds as type constraints in the typing environment)

(Also tried doing this once during class file parsing or
when creating the existential type, but that causes cyclic errors
because it happens too early.)
SI-6169 more accurate check for raw java type encoded as existential
SI-6169 initialize before .typeParams -- just in case
SI-8207 Allow import qualified by self reference

This regressed in SI-6815 / #2374. We check if the result of
`typedQualifier(Ident(selfReference))` is a stable identifier
pattern. But we actually see the expansion to `C.this`, which
doesn't qualify.

This commit adds a special cases to `importSig` to compensate.
This is safe enough, because the syntax prevents the following:

	scala> class C { import C.this.toString }
	<console>:1: error: '.' expected but '}' found.
	       class C { import C.this.toString }
	                                        ^
So loosening the check here doesn't admit invalid programs.
I've backed this up with a `neg` test.

The enclosed test also checks that we can use the self
reference in a singleton type, and as a qualifier in
a type selection (These weren't actually broken.)

Maybe it would be more principled to avoid expanding the self
reference in `typedIdent`. I can imagine that the current situation
is a pain for refactoring tools that try to implement a rename
refactoring, for example.

Seems a bit risky at the minute, but I've noted the idea
in a comment.
addresses pull request feedback
SI-6948 Make the Abstract* classes public.

Several weaknesses in the implementation converge and force multiply.

1) Type constructor inference is not persistent. During implicit search
it will give up after the first seen parent even if some deeper base type
(even another direct parent) would satisfy the search.

2) Type inference is not aware of access restrictions. Inferred types are
calculated with disregard for whether the inferred type is visible at
the point of inference. That means that package-private types - which may be
private for any number of good reasons, such as not wanting them to appear in
bytecode thus creating binary compatibility obligations - are not private.
There is no such thing as a qualified private type.

  package p {
    trait PublicInterface[T] { def foo(): Int }
    private[p] trait ImplementationOnly[T] extends PublicInterface[T] { def foo(): Int = 1 }
    class PublicClass extends ImplementationOnly[PublicClass]
  }
  package q {
    object Test {
      def f[A, CC[X]](xs: CC[A]): CC[A] = xs
      def g = f(new p.PublicClass) // inferred type: p.ImplementationOnly[p.PublicClass]
      def h = g.foo()
      // Bytecode contains:
      // public p.ImplementationOnly<p.PublicClass> g();
      // public int h();
      //    0: aload_0
      //    1: invokevirtual #30                 // Method g:()Lp/ImplementationOnly;
      //    4: invokeinterface #33,  1           // InterfaceMethod p/ImplementationOnly.foo:()I
      //    9: ireturn
    }
  }

3) The trait encoding leads to a proliferation of forwarder methods, so much so that
1.5 Mb of bytecode was taken off of the standard library size by creating abstract classes
which act as central mixin points so that leaf classes can inherit some methods the
old fashioned way rather than each receiving their own copy of every trait defined method.
This was done for 2.10 through the creation of the Abstract* classes, all of which were
given reduced visibility to keep them out of the API.

  private[collection] class AbstractSeq extends ...

This achieved its intended goal very nicely, but also some unintended ones.

In combination with 1) above:

  scala> val rand = new scala.util.Random()
  rand: scala.util.Random = scala.util.Random@7f85a53b

  // this works
  scala> rand.shuffle(0 to 5)
  res1: scala.collection.immutable.IndexedSeq[Int] = Vector(4, 0, 1, 2, 5, 3)

  // and this doesn't! good luck reasoning that one out
  scala> rand.shuffle(0 until 5)
  <console>:9: error: Cannot construct a collection of type scala.collection.AbstractSeq[Int]
    with elements of type Int based on a collection of type scala.collection.AbstractSeq[Int].
                rand.shuffle(0 until 5)
                            ^

  // Somewhat comically, in scala 2.9 it was flipped: to failed (differently), until worked.
  scala> scala.util.Random.shuffle(0 to 5)
  <console>:8: error: type mismatch;
   found   : scala.collection.immutable.Range.Inclusive
   required: ?CC[?T]

  scala> scala.util.Random.shuffle(0 until 5)
  res2: scala.collection.immutable.IndexedSeq[Int] = Vector(4, 3, 1, 2, 0)

In combination with 2) above:

  scala> def f[A, CC[X]](xs: CC[A]): CC[A] = xs
  f: [A, CC[X]](xs: CC[A])CC[A]

  scala> var x = f(1 until 10)
  x: scala.collection.AbstractSeq[Int] = Range(1, 2, 3, 4, 5, 6, 7, 8, 9)

  // It has inferred a type for our value which it will not allow us to use or even to reference.
  scala> var y: scala.collection.AbstractSeq[Int] = x
  <console>:10: error: class AbstractSeq in package collection cannot be accessed in package collection
         var y: scala.collection.AbstractSeq[Int] = x
                                 ^
  // This one is a straight regression - in scala 2.9,
  scala> var x = f(1 until 10)
  x: scala.collection.immutable.IndexedSeq[Int] = Range(1, 2, 3, 4, 5, 6, 7, 8, 9)

Since 1) and 2) are essentially unfixable - at least by me - I propose
to ameliorate these regressions by attacking the symptoms at the leaves.
That means making all the Abstract* classes public - keeping in mind that
they must already be assumed to be in the binary compatibility footprint,
since they have been leaking throughout their existence. This only impacts
the inference of inaccessible collections types - it doesn't help with the
more serious issue with type inference.