chore: emit better errors for strings with bad indentation port google/jsonnet#1261 (#596)

refs: #578

Author: He-Pin

sjsonnet/src/sjsonnet/Error.scala

@@ -86,14 +86,18 @@ object Error {
   }
 }
 
-class ParseError(msg: String, stack: List[Error.Frame] = Nil, underlying: Option[Throwable] = None)
+class ParseError(
+    msg: String,
+    stack: List[Error.Frame] = Nil,
+    underlying: Option[Throwable] = None,
+    val offset: Int = -1)
     extends Error(msg, stack, underlying) {
 
   override protected def copy(
       msg: String = msg,
       stack: List[Error.Frame] = stack,
       underlying: Option[Throwable] = underlying): sjsonnet.ParseError =
-    new ParseError(msg, stack, underlying)
+    new ParseError(msg, stack, underlying, offset)
 }
 
 class StaticError(msg: String, stack: List[Error.Frame] = Nil, underlying: Option[Throwable] = None)

sjsonnet/src/sjsonnet/Importer.scala

@@ -209,16 +209,23 @@ class CachedResolver(
       ev: EvalErrorScope): Either[Error, (Expr, FileScope)] = {
     parseCache.getOrElseUpdate(
       (path, content.contentHash()), {
-        val parsed = fastparse.parse(
-          content.getParserInput(),
-          parser(path).document(_)
-        ) match {
-          case f @ Parsed.Failure(_, _, _) =>
-            val traced = f.trace()
-            val pos = new Position(new FileScope(path), traced.index)
-            Left(new ParseError(traced.msg).addFrame(pos))
-          case Parsed.Success(r, _) => Right(r)
-        }
+        val parsed =
+          try {
+            fastparse.parse(
+              content.getParserInput(),
+              parser(path).document(_)
+            ) match {
+              case f @ Parsed.Failure(_, _, _) =>
+                val traced = f.trace()
+                val pos = new Position(new FileScope(path), traced.index)
+                Left(new ParseError(traced.msg).addFrame(pos))
+              case Parsed.Success(r, _) => Right(r)
+            }
+          } catch {
+            case e: ParseError if e.offset >= 0 =>
+              val pos = new Position(new FileScope(path), e.offset)
+              Left(new ParseError(e.getMessage).addFrame(pos))
+          }
         parsed.flatMap { case (e, fs) => process(e, fs) }
       }
     )

sjsonnet/src/sjsonnet/Parser.scala

@@ -68,6 +68,7 @@ object Parser {
 
   private val emptyLazyArray = new Array[Lazy](0)
   private val isSpaceOrTab: Char => Boolean = c => c == ' ' || c == '\t'
+
 }
 
 class Parser(
@@ -91,6 +92,10 @@ class Parser(
     }
   }
 
+  private def failParse(msg: String, offset: Int): Nothing = {
+    throw new ParseError(msg, offset = offset)
+  }
+
   def Pos[$: P]: P[Position] = Index.map(offset => new Position(fileScope, offset))
 
   def id[$: P]: P[String] = P(
@@ -284,7 +289,8 @@ class Parser(
 
   def maybeChompedTripleBarString[$: P]: P[Seq[String]] = tripleBarString.map {
     case (true, lines) =>
-      lines.dropRight(1) ++ Seq(lines.last.stripLineEnd)
+      val last = lines.length - 1
+      lines.updated(last, lines(last).stripLineEnd)
     case (false, lines) =>
       lines
   }
@@ -314,14 +320,67 @@ class Parser(
     }
   )
 
+  private def describeWhitespace(whitespace: String): String = {
+    var spaces = 0
+    var tabs = 0
+    for (c <- whitespace) {
+      if (c == ' ') spaces += 1
+      else if (c == '\t') tabs += 1
+    }
+    if (spaces > 0 && tabs > 0) {
+      s"${spaces} ${if (spaces == 1) "space" else "spaces"} and ${tabs} ${
+          if (tabs == 1) "tab" else "tabs"
+        }"
+    } else if (spaces > 0) {
+      s"${spaces} ${if (spaces == 1) "space" else "spaces"}"
+    } else if (tabs > 0) {
+      s"${tabs} ${if (tabs == 1) "tab" else "tabs"}"
+    } else {
+      "no indentation"
+    }
+  }
+
   def tripleBarStringBody[$: P](indent: String, sep: String): P[Seq[String]] = P(
-    // Because we already parsed the indentation, we special case the first line and only look for the content.
+    // First line: indentation already consumed, just capture content up to the line separator.
     (CharsWhile(!sep.contains(_), 0) ~~ sep).!.flatMapX { firstLine =>
-      // That's the core of the parsing. Either we have an empty line or we have indentation + content + new line separator.
-      (sep.! | (indent.! ~~ (CharsWhile(!sep.contains(_), 0) ~~ sep).!).map(_._2))
+      // Subsequent lines: empty line (just separator) | indented line with whitespace check.
+      (sep.! | tripleBarStringIndentedLine(indent, sep))
         .opaque("|||-block line must either be an empty line or start with at least one whitespace")
         .repX
-        .map(Seq(firstLine) ++ _)
+        .map(firstLine +: _)
+    }
+  )
+
+  private def tripleBarStringIndentedLine[$: P](indent: String, sep: String): P[String] = P(
+    // Parse whitespace once, then check if it matches the expected indentation.
+    (CharsWhile(isSpaceOrTab, 0).! ~~ Index).flatMapX { case (whitespace, wsEndOffset) =>
+      if (whitespace.isEmpty) {
+        // No whitespace at all — not an indented line (e.g. ||| terminator without leading spaces).
+        Fail.opaque("expected indentation for text block line")
+      } else if (whitespace.startsWith(indent)) {
+        // Indentation matches — parse the rest of the line content after the indent.
+        (CharsWhile(!sep.contains(_), 0) ~~ sep).!.map { content =>
+          whitespace.substring(indent.length) + content
+        }
+      } else {
+        val isTerminator = P.current.input.isReachable(wsEndOffset + 2) &&
+          P.current.input(wsEndOffset) == '|' &&
+          P.current.input(wsEndOffset + 1) == '|' &&
+          P.current.input(wsEndOffset + 2) == '|'
+        if (isTerminator) {
+          // This is the ||| terminator line — fail to let the outer parser match |||.
+          Fail.opaque("text block terminator |||")
+        } else {
+          // Indentation mismatch — emit a detailed error.
+          val expectedDescription = describeWhitespace(indent)
+          val actualDescription = describeWhitespace(whitespace)
+          failParse(
+            "text block indentation mismatch: expected at least " +
+            expectedDescription + ", found " + actualDescription,
+            wsEndOffset
+          )
+        }
+      }
     }
   )
 

sjsonnet/test/resources/test_suite/error.parse.text_block_bad_whitespace.jsonnet.golden

@@ -1,3 +1,3 @@
-sjsonnet.ParseError: Expected "|||":19:2, found "bar\n|||\n"
+sjsonnet.ParseError: text block indentation mismatch: expected at least 4 spaces, found 1 tab
     at .(error.parse.text_block_bad_whitespace.jsonnet:19:2)
 

sjsonnet/test/resources/test_suite/error.parse.text_block_indent_spaces.jsonnet

@@ -0,0 +1,20 @@
+/*
+Copyright 2026 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+|||
+    foo
+  bar
+|||

sjsonnet/test/resources/test_suite/error.parse.text_block_indent_spaces.jsonnet.golden

@@ -0,0 +1,2 @@
+sjsonnet.ParseError: text block indentation mismatch: expected at least 4 spaces, found 2 spaces
+    at .(error.parse.text_block_indent_spaces.jsonnet:19:3)