feat: align CLI with go-jsonnet

Motivation:
Close CLI compatibility gaps with go-jsonnet, including option parsing, output behavior, environment/JPATH handling, and stack accounting semantics.

Modification:
Update CLI config and main flow, add JVM CLI compatibility tests, and keep tail-call trampolines from consuming the user-facing maxStack budget while preserving maxStack failures for non-tail recursion.

Result:
The PR branch is represented as one cohesive commit and the JVM CI failure is fixed by aligning tests with the intended tail-recursive stack behavior.

References:
#1068

Author: He-Pin

build.mill

@@ -382,6 +382,84 @@ object sjsonnet extends VersionFileModule {
     def forkArgs =
       Seq("-Xss" + stackSize, "--enable-native-access=ALL-UNNAMED")
 
+    override def prependShellScript = mill.util.Jvm.universalScript(
+      shellCommands =
+        s"""if [ -z "$$JAVA_HOME" ] ; then
+           |  JAVACMD="java"
+           |else
+           |  JAVACMD="$$JAVA_HOME/bin/java"
+           |fi
+           |SJSONNET_JAVA_OPTS=""
+           |if "$$JAVACMD" --sun-misc-unsafe-memory-access=allow -version >/dev/null 2>&1; then
+           |  SJSONNET_JAVA_OPTS="--sun-misc-unsafe-memory-access=allow"
+           |fi
+           |exec "$$JAVACMD" -Xss$stackSize --enable-native-access=ALL-UNNAMED $$SJSONNET_JAVA_OPTS $$JAVA_OPTS -cp "$$0" 'sjsonnet.SjsonnetMain' "$$@"""".stripMargin,
+      cmdCommands =
+        s"""set "JAVACMD=java.exe"
+           |if not "%JAVA_HOME%"=="" set "JAVACMD=%JAVA_HOME%\\bin\\java.exe"
+           |set "SJSONNET_JAVA_OPTS="
+           |"%JAVACMD%" --sun-misc-unsafe-memory-access=allow -version >nul 2>&1
+           |if "%errorlevel%" == "0" set "SJSONNET_JAVA_OPTS=--sun-misc-unsafe-memory-access=allow"
+           |"%JAVACMD%" -Xss$stackSize --enable-native-access=ALL-UNNAMED %SJSONNET_JAVA_OPTS% %JAVA_OPTS% -cp "%~dpnx0" "sjsonnet.SjsonnetMain" %*""".stripMargin
+    )
+
+    def assemblySmoke = Task {
+      val jar = assembly().path
+      val jarCommand =
+        if (scala.util.Properties.isWin) Seq[os.Shellable](jar)
+        else
+          Seq[os.Shellable](
+            "env",
+            "-u",
+            "JDK_JAVA_OPTIONS",
+            "-u",
+            "JAVA_TOOL_OPTIONS",
+            jar
+          )
+      def callJar(args: os.Shellable*) =
+        os.proc((jarCommand ++ args)*).call(
+          stdout = os.Pipe,
+          stderr = os.Pipe,
+          check = false
+        )
+
+      val version = callJar("--version")
+      assert(
+        version.exitCode == 0,
+        s"--version failed with exit ${version.exitCode}: ${version.err.text()}"
+      )
+      assert(version.err.text().isEmpty, s"--version stderr was not empty: ${version.err.text()}")
+
+      val help = callJar("--help")
+      val helpOut = help.out.text()
+      val helpErr = help.err.text()
+      assert(help.exitCode == 0, s"--help failed with exit ${help.exitCode}: $helpErr")
+      assert(helpErr.isEmpty, s"--help stderr was not empty: $helpErr")
+      assert(!helpOut.contains("Missing argument"), helpOut)
+      assert(!helpOut.contains("Unknown argument"), helpOut)
+
+      val stack = callJar(
+        "--exec",
+        "--max-stack",
+        "2",
+        "local f(n) = if n == 0 then 0 else f(n - 1); f(3)"
+      )
+      val stackErr = stack.err.text()
+      assert(stack.exitCode != 0, s"--max-stack unexpectedly exited ${stack.exitCode}")
+      assert(stackErr.contains("Max stack frames exceeded."), stackErr)
+
+      val defaultStack = callJar(
+        "--exec",
+        "local f(n) = if n == 0 then 0 else f(n - 1); f(1000)"
+      )
+      val defaultStackErr = defaultStack.err.text()
+      assert(
+        defaultStack.exitCode != 0,
+        s"default max-stack unexpectedly exited ${defaultStack.exitCode}"
+      )
+      assert(defaultStackErr.contains("Max stack frames exceeded."), defaultStackErr)
+    }
+
     def scalacOptions = super.scalacOptions() ++ Seq("-release", "17") ++
       (if (JvmWorkerUtil.isScala3(scalaVersion())) Seq("-Yfuture-lazy-vals") else Seq.empty)
     def javacOptions = super.javacOptions() ++ Seq("--release", "17")

readme.md

@@ -13,8 +13,8 @@ Expected Signature: Sjsonnet 0.7.0
 usage: sjsonnet [sjsonnet-options] script-file
   -A --tla-str <str>                  <var>[=<val>] Provide top-level arguments as string. 'If <val>
                                       is omitted, get from environment var <var>
-  -J --jpath <str>                    Specify an additional library search dir (left-most wins
-                                      unless reverse-jpaths-priority is set)
+  -J --jpath <str>                    Specify an additional library search dir (right-most wins,
+                                      matching go-jsonnet)
   -S --string                         Expect a string, manifest as plain text
   -V --ext-str <str>                  <var>[=<val>] Provide 'external' variable as string. 'If <val>
                                       is omitted, get from environment var <var>
@@ -44,9 +44,11 @@ usage: sjsonnet [sjsonnet-options] script-file
   --profile <str>                     Profile evaluation and write results to a file. Format:
                                       --profile <file> or --profile <format>:<file> where format is
                                       'text' (default) or 'flamegraph'
-  --reverse-jpaths-priority           If set, reverses the import order of specified jpaths (so that the
-                                      rightmost wins)
+  --reverse-jpaths-priority           Deprecated compatibility flag; --jpath already uses
+                                      right-most-wins priority
   -s --max-stack <int>                Number of allowed stack frames (default 500)
+  -t --max-trace <int>                Max length of stack trace before cropping (default 20, 0 means
+                                      unlimited)
   --strict                            Enforce some additional syntax limitations
   --throw-error-for-invalid-sets      Throw an error if a set operation is used on a non-set
   --tla-code <str>                    <var>[=<val>] Provide top-level arguments as Jsonnet code. 'If
@@ -55,6 +57,7 @@ usage: sjsonnet [sjsonnet-options] script-file
                                       code from the file
   --tla-str-file <str>                <var>=<file> Provide top-level arguments variable as string from
                                       the file
+  --version                           Print version
   -y --yaml-stream                    Write output as a YAML stream of JSON documents
   --yaml-debug                        Generate source line comments in the output YAML doc to make it
                                       easier to figure out where values come from.

sjsonnet/src-jvm-native/sjsonnet/Config.scala

@@ -7,8 +7,7 @@ final case class Config(
     @arg(
       name = "jpath",
       short = 'J',
-      doc =
-        "Specify an additional library search dir (left-most wins unless reverse-jpaths-priority is set)"
+      doc = "Specify an additional library search dir (right-most wins, matching go-jsonnet)"
     )
     private val jpaths: List[String] = Nil,
     @arg(
@@ -134,7 +133,7 @@ final case class Config(
     throwErrorForInvalidSets: Flag = Flag(),
     @arg(
       name = "reverse-jpaths-priority",
-      doc = """If set, reverses the import order of specified jpaths (so that the rightmost wins)"""
+      doc = """Deprecated compatibility flag; --jpath already uses right-most-wins priority"""
     )
     reverseJpathsPriority: Flag = Flag(),
     @arg(
@@ -159,12 +158,23 @@ final case class Config(
       doc = "Print runtime statistics (thunks, calls, imports, timing) to stderr after evaluation"
     )
     debugStats: Flag = Flag(),
+    @arg(
+      name = "version",
+      doc = "Print version"
+    )
+    version: Flag = Flag(),
     @arg(
       name = "max-stack",
       short = 's',
       doc = "Number of allowed stack frames (default 500)"
     )
     maxStack: Int = 500,
+    @arg(
+      name = "max-trace",
+      short = 't',
+      doc = "Max length of stack trace before cropping (default 20, 0 means unlimited)"
+    )
+    maxTrace: Int = 20,
     @arg(
       name = "profile",
       doc =
@@ -182,16 +192,15 @@ final case class Config(
    * Returns the sequence of jpaths, combining command-line flags and the JSONNET_PATH environment
    * variable.
    *
-   * JSONNET_PATH directories always have lower priority than --jpath flags. Within JSONNET_PATH,
-   * the left-most entry has the highest priority, matching the behavior of the C++ and Go
-   * implementations.
+   * JSONNET_PATH directories always have lower priority than --jpath flags. Command-line --jpath
+   * flags use right-most-wins priority, while JSONNET_PATH keeps left-most-wins priority, matching
+   * the behavior of the C++ and Go implementations.
    *
-   * The --reverse-jpaths-priority flag only affects the ordering of --jpath flags (reversing them
-   * so that the rightmost wins, matching go-jsonnet behavior). JSONNET_PATH entries are always
-   * appended after the (possibly reversed) --jpath flags.
+   * The --reverse-jpaths-priority flag is retained for CLI compatibility and no longer changes
+   * ordering because sjsonnet now matches go-jsonnet by default. JSONNET_PATH entries are always
+   * appended after --jpath flags.
    *
-   * For example, `JSONNET_PATH=a:b sjsonnet -J c -J d` results in search order: c, d, a, b (default
-   * mode). With --reverse-jpaths-priority, the order becomes: d, c, a, b.
+   * For example, `JSONNET_PATH=a:b sjsonnet -J c -J d` results in search order: d, c, a, b.
    *
    * See [[https://jsonnet-libs.github.io/jsonnet-training-course/lesson2.html#jsonnet_path]] for
    * details.
@@ -209,8 +218,7 @@ final case class Config(
   def getOrderedJpaths(jsonnetPathEnv: Option[String]): Seq[String] = {
     val envValue = jsonnetPathEnv.getOrElse(System.getenv("JSONNET_PATH"))
     val envPaths = Config.jsonnetPathEntries(envValue)
-    val orderedJpaths = if (reverseJpathsPriority.value) jpaths.reverse else jpaths
-    orderedJpaths ++ envPaths
+    jpaths.reverse ++ envPaths
   }
 }