Module system

.gitignore

@@ -11,6 +11,7 @@ cabal-dev
 .hpc
 .hsenv
 .cabal-sandbox/
+.cabal-local/
 cabal.sandbox.config
 *.prof
 *.aux

README.md

@@ -14,6 +14,7 @@ bugs. You should under no circumstances be using this in a production setting.
 - A pen and paper formalization of the type system is
     defined in the `./spec` directory, and pdf builds are available as artifacts from the [Spec PDF
     workflow](https://github.com/argotorg/solcore/actions/workflows/spec.yml?query=branch%3Amain).
+- The implemented module and namespace behavior is documented in [`doc/module-system.md`](doc/module-system.md).
 
 Bug reports and feedback are very welcome.
 

doc/module-system.md

@@ -0,0 +1,239 @@
+# Module and Namespace System
+
+This document describes the intended Solcore module and namespace system.
+
+## 1. Entry File and Library Roots
+
+- The entry file is the path passed to `-f` / `--file`.
+- The main library root is configured with `--root`.
+- The default main library root is the current working directory.
+- The std library root is configured with `--include`. With the default options this is `std`.
+- External libraries are registered explicitly with repeated `--lib NAME=DIR` flags.
+
+## 2. Module Identity and File Mapping
+
+- Module identity is logical, not canonical-path-based.
+- A module id is `(library, logical module path)`.
+- Libraries are:
+  - the main library
+  - the std library
+  - named external libraries
+- `foo.bar` maps to `foo/bar.solc`.
+- Directories are not modules.
+- `foo` and `foo.bar` therefore refer to different files.
+- The source file path is stored separately from module identity.
+- If two logical module paths reach the same physical file, they are still treated as different modules when their module ids differ.
+
+## 3. Import Syntax
+
+Supported forms:
+
+```solidity
+import M;
+import M as A;
+import M.{X, Y};
+import M.{*};
+import M.{*} hiding {X};
+import lib.foo.bar;
+import @ext.foo.bar;
+```
+
+Import path kinds:
+
+- `import foo.bar;`
+  - relative to the importing module's logical directory
+- `import lib.foo.bar;`
+  - from the current library root
+- `import @ext.foo.bar;`
+  - from the external library registered as `ext`
+
+Current std-specific behavior:
+
+- `import std;` resolves to the std library root from any library.
+- `import std.dispatch;` resolves to `dispatch.solc` under the std root.
+- Bare imports do not fall back to the std root.
+- Imports do not have constructor-specific selector syntax.
+  Exported constructors are accessed through qualified constructor paths such as `T.C`, `M.T.C`, or `alias.T.C`.
+
+## 4. Import Visibility and Qualification
+
+- `import M;` does not open names into unqualified scope.
+- `import M as A;` binds only `A`.
+- `import M.{X, Y};` imports selected exported names into unqualified scope.
+- `import M.{*};` imports all exported item names into unqualified scope.
+- `import M.{...} hiding {X, Y};` removes names from the selector result after expansion.
+- Items inside `{...}` may mix simple item names and `*`.
+  Dotted item paths are not supported there.
+
+Default module bindings:
+
+- `import foo.bar;` binds `bar`.
+- `import foo.bar as B;` binds `B` and does not bind `bar`.
+- Non-alias module imports also support full-path qualification, so `import foo.bar;` allows both `bar.x` and `foo.bar.x`.
+- If two imports would bind the same final segment, it is an error.
+  For example, `import foo.bar; import baz.bar;` is rejected.
+
+Validation rules:
+
+- Duplicate qualifier names are rejected.
+- Duplicate explicit names inside one selective import are rejected.
+- Duplicate names inside one `hiding {...}` list are rejected.
+- Unknown selected names are rejected.
+- Unknown hidden names are rejected.
+- Ambiguous names introduced by selective or glob imports are rejected.
+
+## 5. Export Syntax and Public Interfaces
+
+Supported forms:
+
+```solidity
+export {X, Y};
+export {*};
+export {T(C1, C2)};
+export {T(*)};
+export {M.*, *};
+export M;
+export M as N;
+export M.{X, Y};
+export M.{T(C1, C2)};
+export M.{T(*)};
+export M.*;
+```
+
+Current behavior:
+
+- A module may contain multiple export declarations.
+- The public interface is the union of all export declarations after expansion.
+- If a module has no export declarations, its public interface is empty.
+- `export` declarations do not add names to the current module's local scope.
+- Only exported names and re-exported modules are visible to importers.
+
+Expansion rules:
+
+- `export {X}` exports a local item.
+- `export {T(C1, C2)}` exports the local data type `T` and the named constructors of `T`.
+- `export {T(*)}` exports the local data type `T` and all constructors of `T`.
+- `export {*} ` exports all local importable top-level items, but not subordinate constructors.
+- `export {M.*}` re-exports all exported item names from `M`.
+- `export M;` re-exports the module under its final segment.
+- `export M as N;` re-exports the module under `N`.
+- `export M.{X, Y};` re-exports selected item names from `M`.
+- `export M.{T(C1, C2)};` re-exports the imported data type `T` and the named constructors of `T` that are visible through `M`.
+- `export M.{T(*)};` re-exports the imported data type `T` and all constructors of `T` that are visible through `M`.
+- `export M.*;` re-exports all exported item names from `M`, preserving constructor visibility on exported data types, but not the module binding itself.
+
+Constructor-export rules:
+
+- Constructor names are not exported as standalone top-level items.
+  They must be exported through a data type item such as `T(C1, C2)` or `T(*)`.
+- `T(C1, C2)` and `T(*)` always imply export of the type `T` itself.
+- `*` never implies export of constructors.
+
+Validation rules:
+
+- Unknown local exports are rejected.
+- Unknown re-exported names are rejected.
+- Naming a constructor that does not belong to the selected data type is rejected.
+- Re-exporting a constructor that is not visible through the source module is rejected.
+- Re-exporting two different underlying items under the same public name is rejected.
+- Re-exporting two different module targets under the same public module name is rejected.
+- Repeated exports of the same underlying item are normalized, so forms such as `export {main, *};` are accepted.
+
+Instance behavior:
+
+- Instances are import-visible whenever their defining module is imported.
+- Instances are not named individually in export lists.
+
+## 6. Namespaces and Name Resolution
+
+Current duplicate checking is enforced separately for:
+
+- the type namespace
+  - contracts
+  - data types
+  - type synonyms
+  - classes
+- the term namespace
+  - functions
+  - constructors
+  - values
+
+Unqualified lookup order:
+
+1. Local lexical scope
+2. Current module top-level declarations and names introduced by `import M.{...}` / `import M.{*}` are treated at the same priority
+3. If that combined non-local set contains more than one candidate in the same namespace, validation fails with a hard error
+4. Otherwise unresolved
+
+Current behavior:
+
+- Local parameters and local variables still shadow non-local names.
+- Current-module top-level names no longer silently shadow selected or glob-imported names.
+- Selected or glob-imported names no longer silently shadow current-module top-level names.
+- Re-importing the same underlying declaration is normalized, so importing `std.{*}` and then `std.{uint256}` does not fail by itself.
+
+## 7. Constructors and Dot Shorthand
+
+Constructors remain term-level names, but they are canonicalized after resolution to `Type.Constructor` form.
+
+Constructor visibility:
+
+- `export {T}` exports the type only; external modules cannot name any constructors of `T`.
+- `export {T(C1, C2)}` exports only the named constructors of `T`.
+- `export {T(*)}` exports all constructors of `T`.
+- Imports do not add constructors as unqualified names.
+  Instead, exported constructors are accessed through qualified paths such as `T.C`, `mod.T.C`, and `alias.T.C`.
+
+Examples of accepted source forms:
+
+- `Option.Some`
+- `mod.Option.Some`
+- `alias.Option.Some`
+- `.Some` when expected type context is available
+
+Current behavior:
+
+- Bare constructor names are not resolved by default in the qualified-constructor model.
+- `data Foo = Foo` remains valid because type and term namespaces are separate.
+- A hidden constructor cannot be named from another module in either expressions or patterns.
+
+Dot shorthand:
+
+- `.K` is resolved during contextual typing, not during the initial name-resolution pass.
+- Pattern shorthand uses the expected scrutinee type.
+- Expression shorthand uses the surrounding expected type.
+- Nested shorthand works when outer context determines the constructor family.
+- `.K` only resolves if `K` is visible from the current module on the expected data type.
+- Missing expected type, non-data expected type, or missing constructor name is an error.
+
+Pattern matching and exhaustiveness:
+
+- Inside the defining module, pattern matching sees the full constructor set of a data type.
+- Outside the defining module, only visible constructors may appear in patterns.
+- If some constructors of a data type are hidden from the current module, matches on that type are treated as non-exhaustive unless they contain a wildcard or catch-all arm.
+- If all constructors of a data type are visible, ordinary exhaustiveness checking applies.
+
+## 8. Pragmas
+
+- Pragmas are module-local.
+- Pragmas do not propagate through imports.
+- Imported instances are trusted during checking without importing the defining module's pragma environment.
+
+## 9. Recursive Modules
+
+- Import cycles are allowed.
+- The loader computes strongly connected components of the import graph.
+- A recursive component is compiled as a recursive module group.
+- Public interfaces inside a recursive group are computed by fixed-point iteration.
+- Compile surfaces for recursive groups are also computed by fixed-point iteration.
+- Self-imports and mutual re-export cycles are therefore supported.
+- If interface or compile-surface expansion does not stabilize, compilation fails for the group.
+
+## 10. External Libraries
+
+- External libraries are configured with `--lib NAME=DIR`.
+- Source code imports them with `@NAME.module.path`.
+- The external library name is part of module identity.
+- Relative imports inside an external library stay within that external library.
+- `lib.*` inside an external library resolves from that external library's root.
+- Version selection and dependency lockfiles are not part of the language-level implementation yet.

sol-core.cabal

@@ -73,6 +73,8 @@ library
       Solcore.Desugarer.ReplaceFunTypeArgs
       Solcore.Desugarer.UniqueTypeGen
       Solcore.Frontend.Lexer.SolcoreLexer
+      Solcore.Frontend.Module.Identity
+      Solcore.Frontend.Module.Loader
       Solcore.Frontend.Parser.SolcoreParser
       Solcore.Frontend.Pretty.SolcorePretty
       Solcore.Frontend.Pretty.Name

src/Solcore/Desugarer/FieldAccess.hs

@@ -38,22 +38,30 @@ type NmEquation = Equation Name
 fieldDesugarer :: CompUnit Name -> CompUnit Name
 fieldDesugarer (CompUnit ims topdecls) = CompUnit ims (extras <> topdecls')
   where
+    existingDataTypes =
+      Set.fromList
+        [ dataName dt
+          | TDataDef dt <- topdecls
+        ]
     (extras, topdecls') = mapAccumL go mempty topdecls
-    go acc (TContr c) = (acc <> extraTopDeclsForContract c, TContr (transContract c))
+    go acc (TContr c) =
+      let hasSingletonCollision =
+            singletonNameForContract (Contract.name c) `Set.member` existingDataTypes
+       in (acc <> extraTopDeclsForContract (not hasSingletonCollision) c, TContr (transContract c))
     go acc v = (acc, v)
 
 --------------------------------
 -- # Extra Top Decls
 --------------------------------
 
-extraTopDeclsForContract :: NmContract -> [NmTopDecl]
-extraTopDeclsForContract (Contract cname _ts cdecls) = do
+extraTopDeclsForContract :: Bool -> NmContract -> [NmTopDecl]
+extraTopDeclsForContract includeSingleton (Contract cname _ts cdecls) = do
   let singName = singletonNameForContract cname
   let contractSingDecl = TDataDef $ DataTy singName [] [Constr singName []]
 
   let fields = getFields cdecls
   let (_fieldTypes, extraFieldDecls) = foldl' (flip contractFieldStep) ([], []) fields
-  (contractSingDecl : extraFieldDecls)
+  (if includeSingleton then contractSingDecl : extraFieldDecls else extraFieldDecls)
   where
     -- given a list of contract field types so far and topdecls for them, amends them with data for another field
     -- the types of previous fields are needed to construct field offset
@@ -71,14 +79,14 @@ extraTopDeclsForContractField cname (Field fname fty _minit) offset = [selDecl,
     selName = selectorNameForField cname fname
     selDecl = TDataDef $ DataTy selName [] [Constr selName []]
     selType = TyCon selName []
-    -- instance StructField(ContractStorage(CCtx), fld1_sel):StructField(uint, ()) {}
+    -- instance StructField(ContractStorage(CCtx), fld1_sel):CStructField(uint, ()) {}
     ctxTy = TyCon "ContractStorage" [singletonTypeForContract cname]
     sfInstance =
       Instance
         { instDefault = False,
           instVars = [],
           instContext = [],
-          instName = "StructField",
+          instName = "CStructField",
           paramsTy = [translateFieldType fty, offset],
           mainTy = TyCon "StructField" [ctxTy, selType],
           instFunctions = []

src/Solcore/Desugarer/IndirectCall.hs

@@ -39,6 +39,7 @@ instance Desugar (TopDecl Name) where
   desugar (TInstDef i) = TInstDef <$> desugar i
   desugar (TDataDef d) = pure $ TDataDef d
   desugar (TSym s) = pure $ TSym s
+  desugar (TExportDecl d) = pure $ TExportDecl d
   desugar (TPragmaDecl d) = pure $ TPragmaDecl d
   desugar (TMutualDef ms) = TMutualDef <$> desugar ms
 
@@ -145,6 +146,7 @@ instance Collect (TopDecl Name) where
   collect (TInstDef _) = []
   collect (TDataDef _) = []
   collect (TSym _) = []
+  collect (TExportDecl _) = []
   collect (TPragmaDecl _) = []
   collect (TMutualDef ms) = collect ms
 

src/Solcore/Frontend/Lexer/SolcoreLexer.x

@@ -40,6 +40,9 @@ tokens :-
 
         <0>    "contract"                        {simpleToken TContract}
         <0>    "import"                          {simpleToken TImport}
+        <0>    "export"                          {simpleToken TExport}
+        <0>    "hiding"                          {simpleToken THiding}
+        <0>    "as"                              {simpleToken TAs}
         <0>    "let"                             {simpleToken TLet}
         <0>    "data"                            {simpleToken TData}
         <0>    "."                               {simpleToken TDot}
@@ -165,6 +168,9 @@ data Lexeme
   | TString { unStr :: String }
   | TContract
   | TImport
+  | TExport
+  | THiding
+  | TAs
   | TLet
   | TEq
   | TDot
@@ -238,6 +244,9 @@ mkIdent (st, _, _, str) len
       "match" -> return $ Token (position st) TMatch
       "data" -> return $ Token (position st) TData
       "import" -> return $ Token (position st) TImport
+      "export" -> return $ Token (position st) TExport
+      "hiding" -> return $ Token (position st) THiding
+      "as" -> return $ Token (position st) TAs
       "contract" -> return $ Token (position st) TContract
       "function" -> return $ Token (position st) TFunction
       "constructor" -> return $ Token (position st) TConstructor