Report warning (or error) if magic comment is not in top of file

[bjornregnell]

Is your feature request related to a problem? Please describe. package should be on top, but also magic comments; I have seen students putting //> using not on top several times but instead writing package etc on top

Describe the solution you'd like Report a warning and a hint if //> is not first in source.

Describe alternatives you've considered Or even perhaps make it an error. (It probably won't compile anyway if magic comment is lost)

Additional context Currently (scala-cli 1.4.0) the error message is diffult to understand for a beginner:

$ scala-cli version
Scala CLI version: 1.4.0
Scala version (default): 3.4.2

$ cat test-os.scala 
package x
//> using scala 3.4.2
//> using toolkit default
@main def run = println(os.pwd)

$ scala-cli run test-os.scala 
Compiling project (Scala 3.4.2, JVM (17))
[error] ./test-os.scala:4:25
[error] Not found: os
[error] @main def run = println(os.pwd)
[error]                         ^^
Error compiling project (Scala 3.4.2, JVM (17))
Compilation failed

[mertant]

To add to this, the described issue - using directives that fail silently/are ignored silently - occurs not only with misplaced Scala code and package declarations, but also with block comments /* and ScalaDoc comments /**.

Somewhat unusually, the only thing[1] that may be placed above the using directive in the file are single-line comments //. (And of course the shebang header #!....) See example code below.

To emphasize: single-line comments are allowed but block comments in the same place are not.[2] So single-line comments and block comments are not interchangeable, which is highly unexpected in Scala. The solution (e.g. reformat the block comment as single-line comments) is likely to be unintuitive for many.

Therefore I concur that it would be good user experience to see some warnings about directives being ignored, if not due to preceding code, then at the very least due to preceding comments.[3]

• [1] At least, the only thing according to my own experimentation.
• [2] The fact that this occurs with block comments and ScalaDoc comments but not with single-line comments make me suspect that this and the issue below, where it's reported "There is no issue with line comments", have causes that are related:
  • https://github.com/VirtusLab/scala-cli/issues/2382
• [3] An even better solution would perhaps be if the parsing behaviour was changed so that any block comments are simply ignored when looking for directives, just as single-line comments currently are; broken scripts like the example below would start to compile successfully. But I don't know about the feasibility of implementing this.

---

Example of a broken script (using directive is silently ignored):

// Single-line comment: no problem.
// Another single-line comment. Still no problem.
/* Block comment: this breaks everything! But if you delete it or move it down a couple lines, the script compiles successfully. */
//> using dep org.scalameta::munit::1.0.2

import munit.FunSuite
println("Success: Munit dependencies were found.")

$ scala compile ./scripts/using-directive-broken-example-dep.sc 
Compiling project (Scala 3.7.0, JVM (23))
[error] ./scripts/using-directive-broken-example-dep.sc:6:8
[error] Not found: munit - did you mean Unit?
[error] import munit.FunSuite
[error]        ^^^^^
Error compiling project (Scala 3.7.0, JVM (23))
Compilation failed

The same script starts to compile successfully if we remove the block comment line.