deprecate 3.1-migration, err on import

compiler/src/dotty/tools/dotc/config/SourceVersion.scala

@@ -17,5 +17,12 @@ enum SourceVersion:
 
 object SourceVersion extends Property.Key[SourceVersion]:
 
-  val allSourceVersionNames = values.toList.map(_.toString.toTermName)
+  /** language versions that may appear in a language import, are deprecated, but not removed from the standard library. */
+  val illegalSourceVersionNames = List("3.1-migration").map(_.toTermName)
+
+  /** language versions that the compiler recognises. */
+  val validSourceVersionNames = values.toList.map(_.toString.toTermName)
+
+  /** All source versions that can be recognised from a language import. e.g. `import language.3.1` */
+  val allSourceVersionNames = validSourceVersionNames ::: illegalSourceVersionNames
 end SourceVersion

compiler/src/dotty/tools/dotc/parsing/Parsers.scala

@@ -3150,6 +3150,15 @@ object Parsers {
               syntaxError(i"source version import is only allowed at the toplevel", id.span)
             else if ctx.compilationUnit.sourceVersion.isDefined then
               syntaxError(i"duplicate source version import", id.span)
+            else if illegalSourceVersionNames.contains(imported) then
+              val candidate =
+                val nonMigration = imported.toString.replace("-migration", "")
+                validSourceVersionNames.find(_.show == nonMigration)
+              val baseMsg = i"`$imported` is not a valid source version"
+              val msg = candidate match
+                case Some(member) => i"$baseMsg, did you mean language.`$member`?"
+                case _ => baseMsg
+              syntaxError(msg, id.span)
             else
               ctx.compilationUnit.sourceVersion = Some(SourceVersion.valueOf(imported.toString))
         case None =>

library/src/scala/runtime/stdLibPatches/language.scala

@@ -149,10 +149,13 @@ object language:
   object `3.0`
 
   /** Set source version to 3.1-migration.
+    *
+    * This is a no-op, and should not be used. A syntax error will be reported upon import.
     *
     * @see [[https://docs.scala-lang.org/scala3/guides/migration/compatibility-intro.html]]
     */
   @compileTimeOnly("`3.1-migration` can only be used at compile time in import statements")
+  @deprecated("`3.1-migration` is not valid, use `3.1` instead", since = "3.2")
   object `3.1-migration`
 
   /** Set source version to 3.1

tests/neg/i12457.scala

@@ -1,3 +1,3 @@
-import language.`3.1-migration`
+import language.`3.1`
 
 trait X [ X <: Z , Z >: X [ R     ] ] // error

tests/neg/source-import-3-1-migration.check

@@ -0,0 +1,4 @@
+-- Error: tests/neg/source-import-3-1-migration.scala:1:16 -------------------------------------------------------------
+1 |import language.`3.1-migration` // error
+  |                ^^^^^^^^^^^^^^^
+  |                `3.1-migration` is not a valid source version, did you mean language.`3.1`?

tests/neg/source-import-3-1-migration.scala

@@ -0,0 +1 @@
+import language.`3.1-migration` // error