Improve warning message and add doc page

Also, add back tests

Author: odersky

compiler/src/dotty/tools/dotc/typer/Checking.scala

@@ -1249,8 +1249,10 @@ trait Checking {
 
   def checkMatchable(tp: Type, pos: SrcPos, pattern: Boolean)(using Context): Unit =
     if !tp.derivesFrom(defn.MatchableClass) && sourceVersion.isAtLeast(`3.1-migration`) then
-      val kind = if pattern then "pattern selector " else ""
-      report.warning(em"${kind}type $tp should not be scrutinized", pos)
+      val kind = if pattern then "pattern selector" else "value"
+      report.warning(
+        em"""${kind} should be an instance of Matchable,
+            |but it has unmatchable type $tp instead""", pos)
 }
 
 trait ReChecking extends Checking {

docs/docs/reference/other-new-features/matchable.md

@@ -0,0 +1,68 @@
+layout: doc-page
+title: The Matchable Trait
+---
+
+A new trait `Matchable` controls the ability to pattern match.
+
+### The Problem
+
+The Scala 3 standard library has a type `IArray` for immutable
+arrays that is defined like this:
+
+```scala
+  opaque type IArray[+T] = Array[_ <: T]
+```
+The `IArray` type offers extension methods for `length` and `apply`, but not for `update`; hence it seems values of type `IArray` cannot be updated.
+
+However, there is a potential hole due to pattern matching. Consider:
+```scala
+val imm: IArray[Int] = ...
+imm match
+  case a: Array[Int] => a(0) = 1
+```
+The test will succeed at runtime since `IArray`s _are_ represented as
+`Array`s at runtime. But if we allowed it, it would break the fundamental abstraction of immutable arrays.
+
+__Aside:__ One could also achieve the same by casting:
+```scala
+imm.asInstanceOf[Array[Int]](0) = 1
+```
+But that is not as much of a problem since in Scala `asInstanceOf` is understood to be low-level and unsafe. By contrast, a pattern match that compiles without warning or error should not break abstractions.
+
+Note also that the problem is not tied to opaque types as match selectors. The following slight variant with a value of parametric
+type `T` as match selector leads to the same problem:
+
+```scala
+def f[T](x: T) = x match
+  case a: Array[Int] => a(0) = 0
+f(imm)
+```
+Finally, note that the problem is not linked to just opaque types. No unbounded type parameter or abstract type should be decomposable with a pattern match.
+
+### The Solution
+
+There is a new type `scala.Matchable` that controls pattern matching. When typing a pattern match of a constructor pattern `C(...)` or
+a type pattern `_: C` it is required that the selector type conforms
+to `Matchable`. If that's not the case a warning is issued. For instance when compiling the example at the start of this section we get:
+```
+> sc ../new/test.scala -source 3.1
+-- Warning: ../new/test.scala:4:12 ---------------------------------------------
+4 |    case a: Array[Int] => a(0) = 0
+  |            ^^^^^^^^^^
+  |            pattern selector should be an instance of Matchable,
+  |            but it has unmatchable type IArray[Int] instead
+```
+To allow migration from Scala 2 and cross-compiling
+between Scala 2 and 3 the warning is turned on only for `-source 3.1-migration` or higher.
+
+`Matchable` is a universal trait with `Any` as its parent class. It is
+extended by both `AnyVal` and `AnyRef`. Since `Matchable` is a supertype of every concrete value or reference class it means that instances of such classes can be matched as before. However, match selectors of the following types will produce a warning:
+
+ - Type `Any`: if pattern matching is required one should use `Matchable` instead.
+ - Unbounded type parameters and abstract types: If pattern matching is required they should have an upper bound `Matchable`.
+ - Type parameters and abstract types that are only bounded by some
+   universal trait: Again, `Matchable` should be added as a bound.
+
+`Matchable` is currently a marker trait without any methods. Over time
+we might migrate methods `getClass` and `isInstanceOf` to it, since these are closely related to pattern-matching.
+

docs/sidebar.yml

@@ -105,6 +105,8 @@ sidebar:
               url: docs/reference/other-new-features/parameter-untupling.html
             - title: Kind Polymorphism
               url: docs/reference/other-new-features/kind-polymorphism.html
+            - title: Matchable Trait
+              url: docs/reference/other-new-features/matchable.html
             - title: threadUnsafe Annotation
               url: docs/reference/other-new-features/threadUnsafe-annotation.html
             - title: targetName Annotation

tests/neg-custom-args/i7314.scala

@@ -0,0 +1,9 @@
+@main def Test =
+  // conversion out of the opaque type:
+  val imm1 = IArray(1,2,3) // supposedly immutable
+  println(imm1(0)) // 1
+  imm1 match {
+    case a: Array[Int] =>  // error: should not be scrutinized
+      a(0) = 0
+  }
+  println(imm1(0)) // 0

tests/neg-custom-args/matchable.scala

@@ -0,0 +1,27 @@
+def foo[T](x: T): Matchable =
+  println(x.getClass())   // ok
+  println(x.isInstanceOf[Int]) // ok
+  x match
+    case x: Int =>   // error: should not be scrutinized
+      println("int")
+      x
+    case x: String =>  // error: should not be scrutinized
+      println("string")
+      x
+  List(x) match
+    case (x: Int) :: Nil =>  // error: should not be scrutinized
+      println("int")
+      x
+    case List(x: String) =>  // error: should not be scrutinized
+      println("string")
+      x
+    case List(y :: Nil) =>  // error: should not be scrutinized
+      y :: Nil
+    case _ =>
+      x   // error: should not be scrutinized
+
+@main def Test =
+  val x: Matchable = foo(1)
+  val y: Matchable = foo("hello")
+  assert(x != y)
+

tests/run/matchable.check

@@ -0,0 +1,8 @@
+class java.lang.Integer
+true
+int
+int
+class java.lang.String
+false
+string
+string

tests/run/matchable.scala

@@ -0,0 +1,29 @@
+def foo[T](x: T): Matchable =
+  println(x.getClass())
+  println(x.isInstanceOf[Int])
+  x match
+    case x: Int =>
+      println("int")
+      x
+    case x: String =>
+      println("string")
+      x
+  List(x) match
+    case (x: Int) :: Nil =>
+      println("int")
+      x
+    case List(x: String) =>
+      println("string")
+      x
+    case List(y :: Nil) =>
+      y :: Nil
+    case _ =>
+      g(x)
+
+def g[T <: Matchable](x: T) = x
+
+@main def Test =
+  val x: Matchable = foo(1)
+  val y: Matchable = foo("hello")
+  assert(x != y)
+