Improvements for standalone script support (#6015)

- Remove hard requirement for root build file. Now that Mill can support
ad-hoc scripts, we do not want to force people to create a root build
file just to run scripts.

- Cache instantiated script modules to prevent duplicate evaluation

- Gracefully handle `ScriptModule#parseHeaderData` when script file is
renamed or deleted

- Properly quote main class name in launcher scripts to make top-level
methods wrapped in classes named `Foo$package` work

- Bump MainArgs to `0.7.7` to take advantage of simpler
`mainargs.Parser` syntax

- Add `example.{javalib,kotlinlib}.basic[2-script-crawler]` examples,
mirroring the `example.scalalib.basic[2-script-builtins]` but using
explicit instead of bundled libraries

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: lihaoyi

core/internal/cli/src/mill/internal/MillCliConfig.scala

@@ -169,8 +169,6 @@ case class MillCliConfig(
     ).count(_.value)
 }
 
-import mainargs.ParserForClass
-
 // We want this in a separate source file, but to avoid stale --help output due
 // to under-compilation, we have it in this file
 // see https://github.com/com-lihaoyi/mill/issues/2315
@@ -213,21 +211,22 @@ Advanced and internal command-line flags not intended for common usage. Use at y
 Advanced Options:
 """
 
-  lazy val parser: ParserForClass[MillCliConfig] = mainargs.ParserForClass[MillCliConfig]
+  lazy val parser: mainargs.ParserForClass[MillCliConfig] = mainargs.Parser[MillCliConfig]
 
-  private lazy val helpAdvancedParser: ParserForClass[MillCliConfig] = new ParserForClass(
-    parser.main.copy(argSigs0 = parser.main.argSigs0.collect {
-      case a if !isUnsupported(a) && a.hidden =>
-        a.copy(
-          hidden = false,
-          // Hack to work around `a.copy` not propagating the name mapping correctly, so we have
-          // to manually map the name ourselves. Doesn't affect runtime behavior since this is
-          // just used for --help-advanced printing and not for argument parsing
-          unMappedName = a.mappedName(mainargs.Util.kebabCaseNameMapper)
-        )
-    }),
-    parser.companion
-  )
+  private lazy val helpAdvancedParser: mainargs.ParserForClass[MillCliConfig] =
+    new mainargs.ParserForClass(
+      parser.main.copy(argSigs0 = parser.main.argSigs0.collect {
+        case a if !isUnsupported(a) && a.hidden =>
+          a.copy(
+            hidden = false,
+            // Hack to work around `a.copy` not propagating the name mapping correctly, so we have
+            // to manually map the name ourselves. Doesn't affect runtime behavior since this is
+            // just used for --help-advanced printing and not for argument parsing
+            unMappedName = a.mappedName(mainargs.Util.kebabCaseNameMapper)
+          )
+      }),
+      parser.companion
+    )
 
   lazy val shortUsageText: String =
     "Please specify a task to evaluate\n" +

example/javalib/basic/2-script-crawler/Crawler.java

@@ -0,0 +1,104 @@
+//| mvnDeps:
+//| - info.picocli:picocli:4.7.6
+//| - com.squareup.okhttp3:okhttp:4.12.0
+//| - com.fasterxml.jackson.core:jackson-databind:2.17.2
+
+import com.fasterxml.jackson.databind.*;
+import com.fasterxml.jackson.core.util.DefaultIndenter;
+import com.fasterxml.jackson.core.util.DefaultPrettyPrinter;
+import okhttp3.*;
+import picocli.CommandLine;
+import java.io.*;
+import java.nio.file.*;
+import java.util.*;
+import java.util.concurrent.Callable;
+
+@CommandLine.Command(name = "Crawler", mixinStandardHelpOptions = true)
+public class Crawler implements Callable<Integer> {
+
+  @CommandLine.Option(
+    names = {"--start-article"},
+    required = true,
+    description = "Starting article title"
+  )
+  private String startArticle;
+
+  @CommandLine.Option(
+    names = {"--depth"},
+    required = true,
+    description = "Depth of crawl"
+  )
+  private int depth;
+
+  private static final OkHttpClient client = new OkHttpClient();
+  private static final ObjectMapper mapper = new ObjectMapper();
+
+  public static List<String> fetchLinks(String title) throws IOException {
+    var url = new HttpUrl.Builder()
+      .scheme("https")
+      .host("en.wikipedia.org")
+      .addPathSegments("w/api.php")
+      .addQueryParameter("action", "query")
+      .addQueryParameter("titles", title)
+      .addQueryParameter("prop", "links")
+      .addQueryParameter("format", "json")
+      .build();
+
+    var request = new Request.Builder()
+      .url(url)
+      .header("User-Agent", "WikiFetcherBot/1.0 (https://example.com; [email protected])")
+      .build();
+    try (Response response = client.newCall(request).execute()) {
+      if (!response.isSuccessful())
+        throw new IOException("Unexpected code " + response);
+
+      JsonNode root = mapper.readTree(response.body().byteStream());
+      JsonNode pages = root.path("query").path("pages");
+      List<String> links = new ArrayList<>();
+
+      for (Iterator<JsonNode> it = pages.elements(); it.hasNext();) {
+        JsonNode linkArr = it.next().get("links");
+        if (linkArr != null && linkArr.isArray()) {
+          for (JsonNode link : linkArr) {
+            JsonNode titleNode = link.get("title");
+            if (titleNode != null) links.add(titleNode.asText());
+          }
+        }
+      }
+      return links;
+    }
+  }
+
+  @Override
+  public Integer call() throws Exception {
+    Set<String> seen = new HashSet<>();
+    Set<String> current = new HashSet<>();
+    seen.add(startArticle);
+    current.add(startArticle);
+
+    for (int i = 0; i < depth; i++) {
+      Set<String> next = new HashSet<>();
+      for (String article : current) {
+        for (String link : fetchLinks(article)) {
+          if (!seen.contains(link)) next.add(link);
+        }
+      }
+      seen.addAll(next);
+      current = next;
+    }
+
+    Path output = Paths.get("fetched.json");
+    try (Writer w = Files.newBufferedWriter(output)) {
+      DefaultPrettyPrinter printer = new DefaultPrettyPrinter();
+      printer.indentArraysWith(new DefaultIndenter("    ", "\n"));
+      printer.indentObjectsWith(new DefaultIndenter("    ", "\n"));
+      mapper.writer(printer).writeValue(w, seen);
+    }
+    return 0;
+  }
+
+  public static void main(String[] args) {
+    int exitCode = new CommandLine(new Crawler()).execute(args);
+    System.exit(exitCode);
+  }
+}

example/javalib/basic/2-script-crawler/build.mill

@@ -0,0 +1,20 @@
+// Mill Single-file Java programs can make it more convenient to script simple command-line
+// workflows interacting with files, subprocesses, and HTTP endpoints. For example, below is
+// a simple script using these libraries to crawl wikipedia and save the crawl results to a file:
+
+//// SNIPPET:FILE
+/** See Also: Crawler.java */
+
+/** Usage
+> ./mill Crawler.java --start-article=singapore --depth=2
+
+> cat fetched.json
+[
+    "Calling code",
+    "+65",
+    "British Empire",
+    "1st Parliament of Singapore",
+    ...
+]
+
+*/

example/kotlinlib/basic/2-script-crawler/Crawler.kt

@@ -0,0 +1,59 @@
+//| mvnDeps:
+//| - org.jetbrains.kotlinx:kotlinx-cli:0.3.6
+//| - com.squareup.okhttp3:okhttp:4.12.0
+//| - org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3
+
+import kotlinx.cli.*
+import kotlinx.serialization.json.*
+import okhttp3.*
+import java.nio.file.*
+
+fun fetchLinks(title: String): List<String> {
+    val client = OkHttpClient()
+    val url = HttpUrl.Builder()
+        .scheme("https")
+        .host("en.wikipedia.org")
+        .addPathSegments("w/api.php")
+        .addQueryParameter("action", "query")
+        .addQueryParameter("titles", title)
+        .addQueryParameter("prop", "links")
+        .addQueryParameter("format", "json")
+        .build()
+
+    val request = Request.Builder()
+        .url(url)
+        .header("User-Agent", "WikiFetcherBot/1.0 (https://example.com; [email protected])")
+        .build()
+
+    client.newCall(request).execute().use { resp ->
+        val body = resp.body?.string() ?: return emptyList()
+        val json = Json.parseToJsonElement(body).jsonObject
+        val pages = json["query"]?.jsonObject?.get("pages")?.jsonObject ?: return emptyList()
+        return pages.values.flatMap { page ->
+            page.jsonObject["links"]
+                ?.jsonArray
+                ?.mapNotNull { it.jsonObject["title"]?.jsonPrimitive?.content }
+                ?: emptyList()
+        }
+    }
+}
+
+fun main(args: Array<String>) {
+    val parser = ArgParser("wiki-fetcher")
+    val startArticle by parser.option(ArgType.String, description = "Starting Wikipedia article").required()
+    val depth by parser.option(ArgType.Int, description = "Depth of link traversal").required()
+    parser.parse(args)
+
+    var seen = mutableSetOf(startArticle)
+    var current = mutableSetOf(startArticle)
+
+    repeat(depth) {
+        val next = current.flatMap { fetchLinks(it) }.toSet()
+        current = (next - seen).toMutableSet()
+        seen += current
+    }
+
+    val jsonOut = Json { prettyPrint = true }
+        .encodeToString(JsonElement.serializer(), JsonArray(seen.map { JsonPrimitive(it) }))
+    Files.writeString(Paths.get("fetched.json"), jsonOut)
+}

example/kotlinlib/basic/2-script-crawler/build.mill

@@ -0,0 +1,20 @@
+// Mill Kotlin scripts can make it more convenient to script simple command-line workflows
+// interacting with files, subprocesses, and HTTP endpoints. For example, below is a simple
+// script using these libraries to crawl wikipedia and save the crawl results to a file:
+
+//// SNIPPET:FILE
+/** See Also: Crawler.kt */
+
+/** Usage
+> ./mill Crawler.kt --startArticle singapore --depth 2
+
+> cat fetched.json
+[
+    "Calling code",
+    "+65",
+    "British Empire",
+    "1st Parliament of Singapore",
+    ...
+]
+
+*/

example/large/multifile/10-multi-file-builds/foo/package.mill

@@ -3,5 +3,5 @@ import mill.*, scalalib.*
 
 object `package` extends build.MyModule {
   def moduleDeps = Seq(build.bar.qux.mymodule)
-  def mvnDeps = Seq(mvn"com.lihaoyi::mainargs:0.4.0")
+  def mvnDeps = Seq(mvn"com.lihaoyi::mainargs:0.7.7")
 }

example/large/multifile/10-multi-file-builds/foo/src/Foo.scala

@@ -1,5 +1,5 @@
 package foo
-import mainargs.{main, ParserForMethods, arg}
+import mainargs.{main, Parser, arg}
 object Foo {
   val value = "hello"
 
@@ -12,5 +12,5 @@ object Foo {
     bar.qux.BarQux.printText(barQuxText)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }

example/scalalib/basic/1-script/Foo.scala

@@ -1,20 +1,18 @@
 //| jvmId: 11.0.28
 //| mvnDeps:
 //| - "com.lihaoyi::scalatags:0.13.1"
-//| - "com.lihaoyi::mainargs:0.7.6"
+//| - "com.lihaoyi::mainargs:0.7.7"
 import scalatags.Text.all.*
-import mainargs.{main, ParserForMethods}
+import mainargs.{main, Parser}
 
-object Foo {
-  def generateHtml(text: String) = {
-    h1(text).toString
-  }
-
-  @main
-  def main(text: String) = {
-    println("Jvm Version: " + System.getProperty("java.version"))
-    println(generateHtml(text))
-  }
+def generateHtml(text: String) = {
+  h1(text).toString
+}
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+@main
+def main(text: String) = {
+  println("Jvm Version: " + System.getProperty("java.version"))
+  println(generateHtml(text))
 }
+
+def main(args: Array[String]): Unit = Parser(this).runOrExit(args)

example/scalalib/basic/1-script/FooTests.scala

@@ -2,14 +2,12 @@
 //| mvnDeps:
 //| - "com.google.guava:guava:33.3.0-jre"
 import com.google.common.html.HtmlEscapers.htmlEscaper
-object FooTests {
-  def main(args: Array[String]): Unit = {
-    val result = Foo.generateHtml("hello")
-    assert(result == "<h1>hello</h1>")
-    println(result)
-    val result2 = Foo.generateHtml("<hello>")
-    val expected2 = "<h1>" + htmlEscaper().escape("<hello>") + "</h1>"
-    assert(result2 == expected2)
-    println(result2)
-  }
+def main(args: Array[String]): Unit = {
+  val result = generateHtml("hello")
+  assert(result == "<h1>hello</h1>")
+  println(result)
+  val result2 = generateHtml("<hello>")
+  val expected2 = "<h1>" + htmlEscaper().escape("<hello>") + "</h1>"
+  assert(result2 == expected2)
+  println(result2)
 }

example/scalalib/basic/2-script-builtins/Foo.scala renamed to example/scalalib/basic/2-script-builtins/Crawler.scala

@@ -28,4 +28,4 @@ def main(startArticle: String, depth: Int) = {
   os.write(os.pwd / "fetched.json", upickle.stream(seen, indent = 4))
 }
 
-def main(args: Array[String]): Unit = mainargs.ParserForMethods(this).runOrExit(args)
+def main(args: Array[String]): Unit = mainargs.Parser(this).runOrExit(args)