Include stabilization tracking issue

[casey]

!includes are unstable. I think they are widely used, and are now much less hacky now that #1618 has been merged, so I want to try to stabilize them.

Things we should do before stabilizing:

• Figure out final syntax. I'm leaning towards import "PATH", with no ! and a string for the path.
• Figure out --fmt behavior. Since --fmt is unstable, we can make breaking changes to it later, but it would be nice not to. We should probably change --fmt to formatting/checking all justfiles, since we have a map of paths to source files.
• Do we want breadth first (report errors in parent file first) or depth first (report errors in child file first) error reporting?

[neunenak]

Things we should do before stabilizing:

* Figure out final syntax. I'm leaning towards `import "PATH"`, with no `!` and a string for the path.

It would be good if the final syntax had some room for concisely adding options for configuring details about import. E.g. you might want to use something like import --require "PATH" to indicate that just should fail with an error if the path doesn't exist, or import --optional "PATH" to indicate that if the file doesn't exist just should ignore it (not necessarily dedicated to that shell argument-style syntax, just using it as an example). #1580 also brings up the idea of including files remotely like terraform, and it would be good if there was room in the syntax to support that even if it's not implemented immediately.

Alternatively, if there's no reason to stick with the ! syntax, then maybe there could just be separate directives like import, import-required, import-optional, import-from-url, etc., that all take a single string argument in the same way but have different semantics for how they handle the import.

[casey]

If we do import "PATH", and "PATH" is only allowed to be a static string, then I think we can do all of these things, since any variation will be an error.

[neunenak]

There's this tracking issue: #929 for concerns with a full-fledged module system. It occurs to me that it would be good to decide if includes should grow as a feature to encompass everything that users might want out of a just module system. If yes, then I think it's not a big deal to change the keyword from !include to import; but if no, then it might be good to reserve import for that use and leave include alone.

As an example of what other projects do, the typst typesetting language project, which I've contributed to a little bit, has a distinction between import and include keywords: https://typst.app/docs/reference/scripting#modules that's pretty similar to the idea of "use include for simply dumping raw text, use import for a more complex module system".

[casey]

I was thinking that we would use the Rust syntax:

mod foo "foo.just" # module named foo whose source is `foo.just`

mod foo # path can be omitted if it is module name + `.just`

use foo::bar # bring bar from foo into scope

use foo::* # bring everything from foo into scope

# then this:
import "foo.just"
  
# is equivalent to something like:
mod foo "foo.just"
use foo::*

[casey]

I just merged #1771 to stabilize !include path as import "path". This is going to be a breaking change for the many users of !include, which sucks, but supporting both versions side by side would have been pretty gnarly.

[casey]

I decided that it would take a while to figure out the behavior of --fmt with respect to includes, and that error reporting order could be changed later, so we might as well stabilize now.