Make it easier to work with multi-file using-directives

[bjornregnell]

Is your feature request related to a problem? Please describe.

It is currently not easy to work with multi-file using directives as it is not obvious (to me, despite searching docs) how to silence warnings. (The warning is intrusive as it underlines all directives in vscode).

The solution is to:

scala-cli config suppress-warning.directives-in-multiple-files true

but I had problems finding it and there is not much info here: https://scala-cli.virtuslab.org/docs/commands/basics#warning-suppression

Describe the solution you'd like

Improve documentation of how to silence the warning on the doc pages. This is related to scripting and publishing, two use cases where directives in separate files in the same dir may be useful. Perhaps a page or heading about "Working with using-directives in multiple files", perhaps under the "Cookbook" section in the scala-cli docs?

BTW: When asking Claude about this the AI was confused, so it hadn't understood after accessing current scala-cli docs that it is possible to permanently suppress the warning.

Describe alternatives you've considered

Live with the warning, but that is not so nice as there will be squiggly yellow lines all over the place in using directives in e.g. vscode with metals and if there is a yellow warning it is a bit difficult so see other things that are highlighted etc.

Additional context

See also discussion here: https://discord.com/channels/632150470000902164/901153021638082660/1499782069935538337

[bjornregnell]

More info on my use case: I'm working on a repo where I'm using scala-cli to publish to maven central. It is a micro-lib in a single file and the user either gets it from maven or just copies the file. I want using directives to be firendly to the copy-paste-use-case and hence have put the publishing-related using-directives in another file called publish.scala but then i get the warning about using-directives in multiple files.

[bjornregnell]

Finally found this page: https://scala-cli.virtuslab.org/docs/guides/advanced/verbosity#warnings-about-using-directives-spread-in-multiple-files

When entering this "suppress warning multiple files" in the search box, I am presented this page: https://scala-cli.virtuslab.org/docs/reference/cli-options#suppress-warning-options
but at that page there is no explanation of how to actually write the config command, there is just the option with preceding --
So I did not get that I should write:
scala-cli config suppress-warning.directives-in-multiple-files true

[bjornregnell]

Perhaps vscode/metals could suggest to silence the warning? (There was no such "quickfix" that I could find in the warning pop up). But that is perhaps an issue on metals? Should I open that there?

[spamegg1]

There are use cases where, by default, there has to / should be using directives in multiple files, in addition to a project.scala file.
Generally we could call these "scripts/ folder usage". (I'd like to see more of this, since some repos still rely on fragile Bash scripts.)

One specific case is mine where, the "main project" is a Scala-cli project with a project.scala file, but there are some additional script files in scripts/, in the spirit of replacing Bash scripting with Scala scripting, to perform various tasks in specific situations (such as downloading a stress testing dependency outside of the main project).

An alternative to the suggested solution could be to just get rid of the warning altogether. It does not bother me but it might bother others.

In addition to the suggested solution, I'd like a directive like:

//> using config ... true/false

It would be nice if this could override the "global" config of Scala-cli on a per-project basis.

[Gedochao]

In addition to the suggested solution, I'd like a directive like:

//> using config ... true/false

It would be nice if this could override the "global" config of Scala-cli on a per-project basis.

Mixed feelings about this, but I'm pretty sure this warrants a separate feature request ticket 😅