Clarify spec for package syms

[scabug]

According to SLS ch. 2 second para,

"Bindings of different kinds have a precedence defined on them: Definitions (local or inherited) have highest precedence, followed by explicit imports, followed by wildcard imports, followed by package members, which have lowest precedence."

However, scalac (both 2.7.x and trunk) behave differently as illustrated,

A.scala:

package p

class BitSet

B.scala

package p

import scala.collection.BitSet

object Test {
 val b : BitSet = new scala.collection.mutable.BitSet
}

scalac produces the following output,

B.scala:3: warning: imported BitSet is permanently hidden by definition of class BitSet in package p
import scala.collection.BitSet
       ^
B.scala:6: error: type mismatch;
 found   : scala.collection.mutable.BitSet
 required: p.BitSet
 val b : BitSet = new scala.collection.mutable.BitSet

indicating that the package-local definition p.BitSet has taken precedence over the explicit import of scala.collection.BitSet in B.scala.

The spec and the compiler should agree, and arguably the specified behaviour makes more intuitive sense than the current actual behaviour.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-2458?orig=1
Reporter: @milessabin
Affected Versions: 2.9.3, 2.10.3, 2.11.0-RC1

[scabug]

@odersky said:
I tried to change the behavior to match the spec, but lots of code broke, so I backed out and made the spec conform to current behavior. It now reads:

Bindings of different kinds have a precedence defined on them:
Definitions and declatarations have the highest precedence, no
matter whether they are local, or inherited, or made available by a
package clause. Explicit imports have the next highest precedence and
wildcard imports have the lowest precedence.

[scabug]

@Blaisorblade said:
The bug seems still there, though in a different form as the spec text is much more complicated now. In particular, a definition in compilation unit A made available in compilation unit B has topmost priority right inside the packaging, even though the spec claims it has the lowest priority, but it has indeed the lowest priority (as specified) inside any object nested in the packaging.
https://groups.google.com/d/topic/scala-internals/-Rquc2HBYLk/discussion

[scabug]

@retronym said:
Here's an example of why we need to update the spec: http://youtrack.jetbrains.com/issue/SCL-5848

[scabug]

@retronym said:
Further discussion: scala/scala-dist#96

[scabug]

@retronym said:
scala/scala#3626

[scabug]

@retronym said:
Quoth @adriaanm

I'd rather introduce this in 2.11.1 under -Xsource:2.12 / -Xfuture. We shouldn't have RC2 break code that compiled in RC1 unless warranted by some serious regression.

[scabug]

@retronym said:
Before we close this ticket, we should also add a clarification to the spec along the lines of:

https://issues.scala-lang.org/browse/SI-8559?focusedCommentId=69367&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-69367

[scabug]

@gkossakowski said:
The 2.11.2 is out so I'm rescheduling the issue for 2.11.3.

[scabug]

@retronym said:
Updating fix-by version to 2.11.5.

[scabug]

@milessabin said:
I'm not clear what the current consensus on this is now: is the spec correct and the compiler in error? Or vice versa?

[scabug]

@som-snytt said:
I'll update Jason's branch and submit it to fix the implementation.

The spec help is scala/scala#5151

[scabug]

@som-snytt said:
This was closed without Jason's rework-in-progress at https://github.com/som-snytt/scala/tree/ticket/2458 for the bug part.

[scabug]

@som-snytt said:
The PR is scala/scala#5339.

Note that it doesn't yet fix the pernicious package object paulpism at #9552.