fix: convert format parse errors from Internal Error to user-facing messages (#1076)

Motivation:
Jsonnet documents `std.format(str, vals)` as Python-style percent
formatting, and documents the `%` operator as shorthand for
`std.format`. Malformed percent-format specs are therefore user input
errors, not interpreter failures.

Before this PR, sjsonnet's format scanner/lowering path could throw
plain JVM exceptions for malformed specs such as `%z`, a trailing `%`,
or an unterminated named label. Those exceptions surfaced as `Internal
Error` with Java stack traces, while Python and other Jsonnet
implementations report user-facing format/runtime errors.

Modification:
- Add `parseFormatOrFail` around both cached format-string parsing and
legacy lowered-format conversion.
- Preserve existing sjsonnet `Error` values unchanged.
- Convert `NonFatal` parser/lowering exceptions to `Error.fail(...,
pos)` so malformed format specs are reported at the Jsonnet expression
position.
- Add regression tests for invalid conversions, truncated format specs,
unterminated named labels, the `%` shorthand path, and representative
successful formats.

Result:
Malformed format strings now produce user-facing sjsonnet errors instead
of leaking Java stack traces. The `%` shorthand still uses the same
formatting implementation; its diagnostic keeps the existing
binary-operator stack shape, so it does not add a `[std.format]` builtin
frame. The table below includes the old sjsonnet behavior from `master`
before this PR.

| Case | Python `%` formatting | C++ jsonnet observed | go-jsonnet
observed | jrsonnet observed | sjsonnet before this PR | sjsonnet after
this PR |
|---|---|---|---|---|---|---|
| `std.format("%z", [1])` | `ValueError: unsupported format character z`
| `RUNTIME ERROR: Unrecognised conversion type: z` | `RUNTIME ERROR:
Unrecognised conversion type: z` | `format error: unrecognized
conversion type: z` | `[std.format] Internal Error`, caused by
`Unrecognized conversion type: z` | `[std.format] Unrecognized
conversion type: z` |
| `std.format("hello %", [1])` | `ValueError: incomplete format` |
`RUNTIME ERROR: Truncated format code.` | `RUNTIME ERROR: Truncated
format code.` | `format error: truncated format code` | `[std.format]
Internal Error`, caused by `Truncated format code at end of string` |
`[std.format] Truncated format code at end of string` |
| `std.format("%(key", {key: 1})` | `ValueError: incomplete format key`
| `RUNTIME ERROR: Truncated format code.` | `RUNTIME ERROR: Truncated
format code.` | `format error: truncated format code` | `[std.format]
Internal Error`, caused by `Unterminated ( in format spec` |
`[std.format] Unterminated ( in format spec` |
| `"%z" % [1]` | same malformed `%z` error | `RUNTIME ERROR:
Unrecognised conversion type: z` | `RUNTIME ERROR: Unrecognised
conversion type: z` | `format error: unrecognized conversion type: z` |
`Internal Error`, caused by `Unrecognized conversion type: z` |
`Unrecognized conversion type: z` |

References:
- Official Jsonnet `std.format` documentation:
https://jsonnet.org/ref/stdlib.html#std-format
- Python printf-style string formatting:
https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting

Author: He-Pin

sjsonnet/src/sjsonnet/Format.scala

@@ -1,5 +1,7 @@
 package sjsonnet
 
+import scala.util.control.NonFatal
+
 /**
  * Minimal re-implementation of Python's `%` formatting logic, since Jsonnet's `%` formatter is
  * basically "do whatever python does", with a link to:
@@ -273,7 +275,7 @@ object Format {
   }
 
   def format(s: String, values0: Val, pos: Position)(implicit evaluator: EvalScope): Val.Str = {
-    val parsed = parseFormatCached(s, evaluator.formatCache)
+    val parsed = parseFormatOrFail(pos)(parseFormatCached(s, evaluator.formatCache))
     format(parsed, values0, pos)
   }
 
@@ -558,9 +560,19 @@ object Format {
 
   def format(leading: String, chunks: scala.Seq[(FormatSpec, String)], values0: Val, pos: Position)(
       implicit evaluator: EvalScope): Val.Str = {
-    format(lowerParsedFormat((leading, chunks)), values0, pos)
+    val parsed = parseFormatOrFail(pos)(lowerParsedFormat((leading, chunks)))
+    format(parsed, values0, pos)
   }
 
+  private def parseFormatOrFail(pos: Position)(parse: => RuntimeFormat)(implicit
+      evaluator: EvalErrorScope): RuntimeFormat =
+    try parse
+    catch {
+      case e: Error    => throw e
+      case NonFatal(e) =>
+        Error.fail(e.getMessage, pos)
+    }
+
   private def appendLeading(output: java.lang.StringBuilder, parsed: RuntimeFormat): Unit = {
     val source = parsed.source
     if (source != null) output.append(source, parsed.leadingStart, parsed.leadingEnd)

sjsonnet/test/resources/new_test_suite/error.format_invalid_conversion.jsonnet

@@ -0,0 +1 @@
+std.format("%z", [1])

sjsonnet/test/resources/new_test_suite/error.format_invalid_conversion.jsonnet.golden

@@ -0,0 +1,2 @@
+sjsonnet.Error: [std.format] Unrecognized conversion type: z
+    at [<root>].(error.format_invalid_conversion.jsonnet:1:11)

sjsonnet/test/resources/new_test_suite/error.format_operator_invalid_conversion.jsonnet

@@ -0,0 +1 @@
+"%z" % [1]

sjsonnet/test/resources/new_test_suite/error.format_operator_invalid_conversion.jsonnet.golden

@@ -0,0 +1 @@
+sjsonnet.Error: Unrecognized conversion type: z

sjsonnet/test/resources/new_test_suite/error.format_truncated.jsonnet

@@ -0,0 +1 @@
+std.format("hello %", [])

sjsonnet/test/resources/new_test_suite/error.format_truncated.jsonnet.golden

@@ -0,0 +1,2 @@
+sjsonnet.Error: [std.format] Truncated format code at end of string
+    at [<root>].(error.format_truncated.jsonnet:1:11)

sjsonnet/test/resources/new_test_suite/error.format_unterminated_label.jsonnet

@@ -0,0 +1 @@
+std.format("%(key", { key: "value" })

sjsonnet/test/resources/new_test_suite/error.format_unterminated_label.jsonnet.golden

@@ -0,0 +1 @@
+sjsonnet.Error: [std.format] Unterminated ( in format spec

sjsonnet/test/resources/new_test_suite/format_error_messages.jsonnet

@@ -0,0 +1,5 @@
+std.assertEqual(std.format("100%% done %s", ["yes"]), "100% done yes") &&
+std.assertEqual(std.format("%*s", [10, "hello"]), "     hello") &&
+std.assertEqual(std.format("%.*f", [3, 3.14159]), "3.142") &&
+std.assertEqual(std.format("%#x", [255]), "0xff") &&
+true