Module System

[mohammadfawaz]

Closes #28770

This PR introduces a structured module system for Leo, enabling multi-file programs under the src/ directory with clear rules for module layout and resolution.

📁 Example Directory Structure

src
├── common.leo
├── main.leo
├── outer.leo
├── outer
│   ├── inner.leo

📦 Modules and Their Access Paths

Given the structure above, the following modules are defined:

1. common.leo defines module common, accessible from main.leo via: common::<item>
2. outer.leo defines module outer, accessible from main.leo via: outer::<item>
3. outer/inner.leo defines submodule outer::inner, accessible from:
   • main.leo: outer::inner::<item>
   • outer.leo: inner::<item>

📏 Module Layout Rules

This PR also enforces new rules to prevent ambiguity and ensure consistency:

1. Leaf modules (i.e. modules without submodules) must be defined in a single file: foo.leo
2. Modules with submodules must be defined by an optional top-level foo.leo file and a foo/ directory containing the submodules:

   foo.leo        # defines module `foo` - this is optional
   foo/
     ├── bar.leo  # defines submodule `foo::bar`
   

Only relative paths are implemented so far. That means that items in outer.leo cannot be accessed from items in inner.leo, for example. This is limiting for now but will no longer be an issue when we add absolute paths.

The changes were tedious but not particularly complicated. The largest changes in the compiler is the replacement of Expression::Identifier with Expression::Path.

For now, modules can only have struct, inline, and const. We may decide to relax that restriction in the future.

I've added support for modules in the current interpreter and added some tests. Hopefully mirroring this implementation in the new interpreter won't cause too much trouble.

[mohammadfawaz]

Note: I have not yet updated all the parser tests because that would make this PR very large (~20k lines) due to the Identifier {..} to Path {..} change. Since those changes are trivial, I will make them after the review is done.

[mikebenfield]

more serious review to come

[mikebenfield]

if program a.aleo imports b.aleo, and b.aleo has a struct in a module some_module::SomeStruct, do we intend for a.aleo to be able to refer to that as b.aleo/some_module::SomeStruct ? I think we likely want that, but right now that doesn't parse.

[mohammadfawaz]

if program a.aleo imports b.aleo, and b.aleo has a struct in a module some_module::SomeStruct, do we intend for a.aleo to be able to refer to that as b.aleo/some_module::SomeStruct ? I think we likely want that, but right now that doesn't parse.

This doesn't work today even without the module stuff right? And struct naming is global at the moment? But yeah would certainly be nice to have all that stuff working as one would expect.

[mohammadfawaz]

Addressed the first wave of comments in fef78a1

[mohammadfawaz]

if program a.aleo imports b.aleo, and b.aleo has a struct in a module some_module::SomeStruct, do we intend for a.aleo to be able to refer to that as b.aleo/some_module::SomeStruct ? I think we likely want that, but right now that doesn't parse.

Alright so yeah we can make this work but only if b.aleo/ is added so that we can treat this path as a special one and legalize some_module::SomeStruct before looking for it in the symbol table. This is a bit inconsistent though since we don't require b.aleo for external structs at the moment.

[mikebenfield]

This is a bit inconsistent though since we don't require b.aleo for external structs at the moment.

Right yeah I wasn't really thinking about that. Maybe we just don't worry about it until the external structs stuff is complete.

[d0cd]

It would be helpful to have one of the existing leo-examples adapted to use the new module system. Or even add a new one!

Can we also file an issue in leo-docs-source to document this?

[d0cd]

Overall, the PR looks good! Left some relatively minor nits and questions. This should be good to go after the parser expectations are in.

There is also a fairly extensive example here: ProvableHQ/leo-examples#17