Replace import $file syntax with flat package namespacing (#4462)

Fixes #4459
Fixes #3894

With this PR, all `.mill` files in a folder are in the same flat
`package` namespace, similar to how normal Scala files work. The
previous `import $file` syntax was inherited from Ammonite, and
unfortunately never took off across the Scala community. In effect this
makes `.mill` files behave almost exactly like `.scala` files, which is
part of the longer term goal of removing special handling for `.mill`
files.

The code generation for the helper files is not changed at all in this
PR, rather we just make use of Scala 3's `export` clauses to make them
available under the main `build.mill`/`package.mill` file as well

There is the caveat that the `package object`s in `.mill` files can be
referenced via `build.foo.bar` without the trailing `.package`.
Implementing this caveat is the cause of a lot of the hackiness in the
codegen, which will hopefully go away once the upstream language feature
lands scala/improvement-proposals#100

We leave the codegenned `import _root_.{build_ => $file}` in place so
`import $file` will continue to work to ease in the migration, but are
no longer the recommended way of referencing helper files

Author: lihaoyi

docs/modules/ROOT/pages/large/multi-file-builds.adoc

@@ -9,8 +9,5 @@ include::partial$example/large/multi/10-multi-file-builds.adoc[]
 
 include::partial$example/large/multi/11-helper-files.adoc[]
 
-== Legacy `.sc` extension
-
-include::partial$example/large/multi/12-helper-files-sc.adoc[]
 
 

example/large/multi/11-helper-files/build.mill

@@ -5,8 +5,7 @@
 package build
 import $packages._
 import mill._, scalalib._
-import $file.foo.versions
-import $file.util.MyModule
+import foo.versions
 
 object `package` extends RootModule with MyModule {
   def forkEnv = Map(

example/large/multi/11-helper-files/foo/package.mill

@@ -1,10 +1,9 @@
 package build.foo
 import mill._, scalalib._
-import $file.util
-import $file.foo.versions.myProjectVersion
-object `package` extends RootModule with build_.util.MyModule {
+import versions.myProjectVersion
+object `package` extends RootModule with build.MyModule {
   def forkEnv = Map(
-    "MY_SCALA_VERSION" -> util.myScalaVersion,
+    "MY_SCALA_VERSION" -> build.myScalaVersion,
     "MY_PROJECT_VERSION" -> myProjectVersion
   )
 }

example/large/multi/13-helper-files-mill-scala/build.mill.scala renamed to example/large/multi/12-helper-files-mill-scala/build.mill.scala

@@ -1,13 +1,11 @@
 package build
 import $packages._
 import mill._, scalalib._
-import $file.foo.versions
-import $file.util.MyModule
 
 object `package` extends RootModule with MyModule {
   def forkEnv = Map(
     "MY_SCALA_VERSION" -> build.scalaVersion(),
-    "MY_PROJECT_VERSION" -> versions.myProjectVersion
+    "MY_PROJECT_VERSION" -> build.foo.myProjectVersion
   )
 }
 ///** See Also: util.mill.scala */

example/large/multi/12-helper-files-mill-scala/foo/package.mill.scala

@@ -0,0 +1,8 @@
+package build.foo
+import mill._, scalalib._
+object `package` extends RootModule with build.MyModule {
+  def forkEnv = Map(
+    "MY_SCALA_VERSION" -> build.myScalaVersion,
+    "MY_PROJECT_VERSION" -> myProjectVersion
+  )
+}