rsscript: module name disambiguation (use-as aliasing + qualified calls)

Modules could not de-prefix because a file referencing a same-leaf name
owned by two modules had no way to disambiguate. Add both mechanisms the
user opted into:

- `use module.name as alias`: UseDecl.alias (AST) + parser `as <ident>`;
  the resolver keys imports by local name -> (module prefix, real name);
  the formatter round-trips the alias; the cast check exempts `as` in a
  `use` header.
- Qualified `module.fn()` calls: a lowercase `module.fn()` parses as a
  receiver call, so the resolver collapses a ReceiverCall whose receiver
  names a module (not an in-scope local) and whose method is that module's
  free function to the mangled symbol. Supports multi-segment module paths.
- Two `use` declarations binding the same local name are now a hard
  RS0015 diagnostic instead of a silent last-one-wins shadow.

Spec §14.8 corrected: the resolution order no longer claims a
fully-qualified `module.name` form that did not exist, and now documents
aliasing, qualified calls, and the duplicate-import diagnostic.

Tests: module_isolation unit tests (alias, qualified, multi-segment),
checker_lowering integration tests (alias + qualified end-to-end),
formatter alias round-trip, and a duplicate-import fail fixture.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: olwang

crates/rsscript/src/analyzer.rs

@@ -1187,6 +1187,9 @@ impl Analyzer<'_> {
         let mut seen_module: HashSet<String> = HashSet::new();
         let mut seen_use: HashSet<String> = HashSet::new();
         let mut seen_non_organization_item: HashSet<String> = HashSet::new();
+        // Per file, the local import names already bound, so a second import that
+        // would silently shadow the first is rejected instead of overwritten.
+        let mut seen_import_local: HashMap<String, HashSet<String>> = HashMap::new();
         let items = self.syntax_program.items.clone();
         for item in &items {
             let file = item_span_file(item);
@@ -1223,6 +1226,18 @@ impl Analyzer<'_> {
                             "`use` is source-organization metadata and must appear before declarations.",
                         );
                     }
+                    if let Some(local) = use_decl.local_name()
+                        && !seen_import_local
+                            .entry(file.clone())
+                            .or_default()
+                            .insert(local.to_string())
+                    {
+                        self.unsupported_syntax(
+                            use_decl.span.clone(),
+                            "duplicate import name",
+                            "Two `use` declarations bind the same local name in this file. Rename one with `use module.name as other_name` so each import is unambiguous.",
+                        );
+                    }
                     seen_use.insert(file);
                 }
                 Item::Type(_)

crates/rsscript/src/checks/forbidden.rs

@@ -111,7 +111,10 @@ fn token_can_start_expr(token: &crate::lexer::Token) -> bool {
 
 fn check_implicit_conversion_attempts(analyzer: &mut Analyzer<'_>) {
     for index in 0..analyzer.tokens.len() {
-        if !analyzer.tokens[index].is_ident_text("as") || as_belongs_to_with(analyzer, index) {
+        if !analyzer.tokens[index].is_ident_text("as")
+            || as_belongs_to_with(analyzer, index)
+            || as_belongs_to_use(analyzer, index)
+        {
             continue;
         }
         analyzer.diagnostics.push(
@@ -131,6 +134,25 @@ fn check_implicit_conversion_attempts(analyzer: &mut Analyzer<'_>) {
     }
 }
 
+/// `use module.name as alias` — the `as` renames an import and is not a cast. A
+/// use header is only identifiers and dots before the `as`, so scanning back to a
+/// `use` keyword without crossing any other token confirms the import context.
+fn as_belongs_to_use(analyzer: &Analyzer<'_>, as_index: usize) -> bool {
+    for token in analyzer.tokens[..as_index].iter().rev() {
+        if token.is_ident_text("use") {
+            return true;
+        }
+        let is_path_token = matches!(
+            token.kind,
+            crate::lexer::TokenKind::Ident(_) | crate::lexer::TokenKind::Keyword(_)
+        ) || token.symbol(".");
+        if !is_path_token {
+            return false;
+        }
+    }
+    false
+}
+
 fn as_belongs_to_with(analyzer: &Analyzer<'_>, as_index: usize) -> bool {
     for token in analyzer.tokens[..as_index].iter().rev() {
         if token.is_ident_text("with") {

crates/rsscript/src/formatter.rs

@@ -124,6 +124,10 @@ impl Formatter {
                 Item::Use(u) => {
                     self.out.push_str("use ");
                     self.out.push_str(&u.path.join("."));
+                    if let Some(alias) = &u.alias {
+                        self.out.push_str(" as ");
+                        self.out.push_str(alias);
+                    }
                     self.out.push('\n');
                 }
             }
@@ -1907,6 +1911,17 @@ impl Writer for BufferWriter {
         assert_eq!(format_source("pin.rss", &formatted), formatted);
     }
 
+    #[test]
+    fn round_trips_use_alias() {
+        let source = "module app\n\nuse helpers.count as helpers_count\n\nfn run() -> Int {\n    return helpers_count()\n}\n";
+        let formatted = format_source("alias.rss", source);
+        assert!(
+            formatted.contains("use helpers.count as helpers_count"),
+            "formatter dropped the use alias:\n{formatted}"
+        );
+        assert_eq!(format_source("alias.rss", &formatted), formatted);
+    }
+
     #[test]
     fn renders_list_slice_patterns() {
         let source = r#"features: local

crates/rsscript/src/syntax/ast.rs

@@ -142,9 +142,22 @@ pub struct ModuleDecl {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UseDecl {
     pub path: Vec<String>,
+    /// Optional `as <alias>` local name. When present, the import is referenced
+    /// in this file by the alias instead of the path's last segment.
+    pub alias: Option<String>,
     pub span: Span,
 }
 
+impl UseDecl {
+    /// The local name this import is referenced by in its file: the alias when
+    /// present, otherwise the path's last segment.
+    pub fn local_name(&self) -> Option<&str> {
+        self.alias
+            .as_deref()
+            .or_else(|| self.path.last().map(String::as_str))
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TypeKind {
     Class,

crates/rsscript/src/syntax/module_isolation.rs

@@ -82,16 +82,18 @@ struct Resolver {
     /// `SCREAMING_SNAKE_CASE`, so their mangled symbol is upper-cased to stay
     /// consistent between declaration and reference.
     module_consts: HashMap<String, HashSet<String>>,
-    /// file -> (imported bare name -> module prefix it was imported from).
-    file_imports: HashMap<String, HashMap<String, String>>,
+    /// file -> (local import name -> (module prefix, real symbol name)). The
+    /// local name is the `as` alias when present, otherwise the path's last
+    /// segment; the real name is always the path's last segment.
+    file_imports: HashMap<String, HashMap<String, (String, String)>>,
 }
 
 impl Resolver {
     fn build(program: &Program, file_module: &HashMap<String, String>) -> Self {
         let mut module_defs: HashMap<String, HashSet<String>> = HashMap::new();
         let mut module_types: HashMap<String, HashSet<String>> = HashMap::new();
         let mut module_consts: HashMap<String, HashSet<String>> = HashMap::new();
-        let mut file_imports: HashMap<String, HashMap<String, String>> = HashMap::new();
+        let mut file_imports: HashMap<String, HashMap<String, (String, String)>> = HashMap::new();
 
         for item in &program.items {
             let Some(file) = item_file(item) else {
@@ -156,12 +158,16 @@ impl Resolver {
                 }
                 Item::Use(decl) => {
                     if decl.path.len() >= 2 {
-                        let name = decl.path[decl.path.len() - 1].clone();
+                        let real_name = decl.path[decl.path.len() - 1].clone();
                         let import_prefix = module_prefix(&decl.path[..decl.path.len() - 1]);
+                        let local = decl
+                            .local_name()
+                            .map(str::to_string)
+                            .unwrap_or_else(|| real_name.clone());
                         file_imports
                             .entry(decl.span.file.clone())
                             .or_default()
-                            .insert(name, import_prefix);
+                            .insert(local, (import_prefix, real_name));
                     }
                 }
                 Item::Module(_) => {}
@@ -206,42 +212,46 @@ impl Resolver {
         {
             return Some(self.mangle_value(prefix, name));
         }
-        // Otherwise a `use module.name` import that names a known module symbol.
-        if let Some(import_prefix) = self
+        // Otherwise a `use module.name [as local]` import that names a known
+        // module symbol. The reference uses the local name; the mangled symbol
+        // uses the imported module's real name.
+        if let Some((import_prefix, real)) = self
             .file_imports
             .get(file)
             .and_then(|imports| imports.get(name))
             && self
                 .module_defs
                 .get(import_prefix)
-                .is_some_and(|names| names.contains(name))
+                .is_some_and(|names| names.contains(real))
         {
-            return Some(self.mangle_value(import_prefix, name));
+            return Some(self.mangle_value(import_prefix, real));
         }
         None
     }
 
-    /// The module prefix that owns type `name` as seen from `file` (own module,
-    /// then `use` import), or `None` if it is not a module-scoped type.
-    fn resolve_type_module(&self, file: &str, name: &str) -> Option<String> {
+    /// The `(module prefix, real type name)` that owns type `name` as seen from
+    /// `file` (own module, then `use` import), or `None` if it is not a
+    /// module-scoped type. The real name differs from `name` when `name` is a
+    /// `use … as` alias.
+    fn resolve_type_module(&self, file: &str, name: &str) -> Option<(String, String)> {
         if let Some(prefix) = self.file_module.get(file)
             && self
                 .module_types
                 .get(prefix)
                 .is_some_and(|types| types.contains(name))
         {
-            return Some(prefix.clone());
+            return Some((prefix.clone(), name.to_string()));
         }
-        if let Some(import_prefix) = self
+        if let Some((import_prefix, real)) = self
             .file_imports
             .get(file)
             .and_then(|imports| imports.get(name))
             && self
                 .module_types
                 .get(import_prefix)
-                .is_some_and(|types| types.contains(name))
+                .is_some_and(|types| types.contains(real))
         {
-            return Some(import_prefix.clone());
+            return Some((import_prefix.clone(), real.clone()));
         }
         None
     }
@@ -250,7 +260,7 @@ impl Resolver {
     /// namespace names a module-scoped type, return its mangled type name.
     fn resolve_type_namespace(&self, file: &str, namespace: &str) -> Option<String> {
         self.resolve_type_module(file, namespace)
-            .map(|prefix| format!("{prefix}{MODULE_SEP}{namespace}"))
+            .map(|(prefix, real)| format!("{prefix}{MODULE_SEP}{real}"))
     }
 
     fn rewrite(&self, program: &mut Program) {
@@ -539,9 +549,9 @@ impl Resolver {
                 // where the access lives in a different file than the declaration.
                 if let Expr::Ident(type_name, _) = base.as_ref()
                     && !scope.contains(type_name)
-                    && let Some(type_module) = self.resolve_type_module(file, type_name)
+                    && let Some((type_module, real_type)) = self.resolve_type_module(file, type_name)
                 {
-                    let flat = flatten_associated_const(type_name, name);
+                    let flat = flatten_associated_const(&real_type, name);
                     if self
                         .module_defs
                         .get(&type_module)
@@ -634,7 +644,23 @@ impl Resolver {
                     *callee = Callee::Name(format!("{prefix}{MODULE_SEP}{name}"));
                 }
             }
-            Callee::ReceiverCall { receiver, .. } => {
+            Callee::ReceiverCall {
+                receiver, method, ..
+            } => {
+                // A lowercase `module.fn()` parses as a receiver call, but if the
+                // receiver names a module (not a local in scope) whose free
+                // function is `method`, it is a module-qualified call: collapse it
+                // to the module's mangled symbol. Otherwise it is a real value
+                // receiver call and only the receiver is rewritten.
+                if let Some(prefix) = module_path_of_receiver(receiver, scope)
+                    && self
+                        .module_defs
+                        .get(&prefix)
+                        .is_some_and(|names| names.contains(method))
+                {
+                    *callee = Callee::Name(format!("{prefix}{MODULE_SEP}{method}"));
+                    return;
+                }
                 self.rewrite_expr(receiver, file, scope);
             }
         }
@@ -814,6 +840,80 @@ mod tests {
         isolate_module_namespaces(&mut program);
         assert!(function_names(&program).contains(&"main".to_string()));
     }
+
+    fn body_of(program: &Program, name: &str) -> String {
+        let function = program
+            .items
+            .iter()
+            .find_map(|item| match item {
+                Item::Function(function) if function.name == name => Some(function),
+                _ => None,
+            })
+            .unwrap_or_else(|| panic!("{name} present"));
+        format!("{:?}", function.body)
+    }
+
+    #[test]
+    fn aliased_import_resolves_to_the_imported_module_symbol() {
+        // `use lib.count as lib_count` lets `app` reference `lib`'s `count` under
+        // a distinct local name; the reference resolves to the real module symbol.
+        let lib = parse_source(
+            "lib.rss",
+            "module lib\n\nfn count() -> Int {\n    return 1\n}\n",
+        );
+        let app = parse_source(
+            "app.rss",
+            "module app\n\nuse lib.count as lib_count\n\nfn run() -> Int {\n    return lib_count()\n}\n",
+        );
+        let mut program = merge_programs([lib, app]);
+        isolate_module_namespaces(&mut program);
+        let body = body_of(&program, "app__run");
+        assert!(
+            body.contains("lib__count"),
+            "alias should resolve to lib__count: {body}"
+        );
+    }
+
+    #[test]
+    fn qualified_module_call_resolves_to_the_module_symbol() {
+        // `helpers.count()` names the owner at the call site, with no `use`.
+        let helpers = parse_source(
+            "helpers.rss",
+            "module helpers\n\nfn count() -> Int {\n    return 1\n}\n",
+        );
+        let app = parse_source(
+            "app.rss",
+            "module app\n\nfn run() -> Int {\n    return helpers.count()\n}\n",
+        );
+        let mut program = merge_programs([helpers, app]);
+        isolate_module_namespaces(&mut program);
+        let body = body_of(&program, "app__run");
+        assert!(
+            body.contains("helpers__count"),
+            "qualified call should resolve to helpers__count: {body}"
+        );
+    }
+
+    #[test]
+    fn multi_segment_qualified_module_call_resolves() {
+        // A dotted module path (`a.b`) is mangled to `a_b` and the call collapses
+        // to its module-qualified symbol.
+        let inner = parse_source(
+            "inner.rss",
+            "module a.b\n\nfn count() -> Int {\n    return 1\n}\n",
+        );
+        let app = parse_source(
+            "app.rss",
+            "module app\n\nfn run() -> Int {\n    return a.b.count()\n}\n",
+        );
+        let mut program = merge_programs([inner, app]);
+        isolate_module_namespaces(&mut program);
+        let body = body_of(&program, "app__run");
+        assert!(
+            body.contains("a_b__count"),
+            "multi-segment qualified call should resolve to a_b__count: {body}"
+        );
+    }
 }
 
 /// The flattened symbol for an associated constant `Type.MEMBER`, matching the
@@ -823,6 +923,37 @@ fn flatten_associated_const(type_name: &str, member: &str) -> String {
     format!("{type_name}_{member}").to_uppercase()
 }
 
+/// If `receiver` is a chain of plain identifiers (`a` or `a.b.c`) whose root is
+/// not shadowed by a local binding, return the candidate module prefix (encoded
+/// with the same injective scheme as declarations). Anything else (a method call,
+/// an indexed value, a literal, or a root that names an in-scope local) is a
+/// value receiver, not a module path.
+fn module_path_of_receiver(receiver: &Expr, scope: &HashSet<String>) -> Option<String> {
+    fn collect(expr: &Expr, segments: &mut Vec<String>) -> bool {
+        match expr {
+            Expr::Ident(name, _) => {
+                segments.push(name.clone());
+                true
+            }
+            Expr::Field { base, name, .. } => {
+                collect(base, segments) && {
+                    segments.push(name.clone());
+                    true
+                }
+            }
+            _ => false,
+        }
+    }
+    let mut segments = Vec::new();
+    if !collect(receiver, &mut segments) || segments.is_empty() {
+        return None;
+    }
+    if scope.contains(&segments[0]) {
+        return None;
+    }
+    Some(module_prefix(&segments))
+}
+
 fn item_file(item: &Item) -> Option<&str> {
     Some(match item {
         Item::Function(function) => function.span.file.as_str(),

crates/rsscript/src/syntax/parser.rs

@@ -853,7 +853,15 @@ impl Parser<'_> {
         }
         self.index += 1;
         let path = self.parse_dotted_path()?;
-        Some(UseDecl { path, span })
+        // Optional `as <alias>` renames the import locally so a file can pull two
+        // same-leaf symbols from different modules without collision.
+        let alias = if self.at_ident("as") {
+            self.index += 1;
+            self.take_ident_name()
+        } else {
+            None
+        };
+        Some(UseDecl { path, alias, span })
     }
 
     /// Parse a dot-separated path like `package.contract.PackageContract`.