fix(semantic): incorrect SymbolFlags of TSModuleDeclaration (#10350)

Based on TypeScript's [implementation](https://github.com/microsoft/TypeScript/blob/15392346d05045742e653eab5c87538ff2a3c863/src/compiler/binder.ts#L2384-L2393) to correct `SymbolFlags` of `TSModuleDeclaration`.

The `SymbolFlags::NamespaceModule` and `SymbolFlags::ValueModule` have a significant difference,

`NamespaceModule`: can only be referenced as a type.
`ValueModule`: can only be referenced as a value.

Let's take an example to see:

```ts
namespace NamespaceModule {
  export type A = string
}
namespace ValueModule {
  export const A = 0;
}
```

The following code is the JS output of the above example.

```js
"use strict";
var ValueModule;
(function (ValueModule) {
    ValueModule.A = 0;
})(ValueModule || (ValueModule = {}));
```

Only `ValueModule` will be preserved and transformed.

That means whether a `TSModuleDeclaration`  needs to be transformed or removed directly, we can determine by its `SymbolFlags`. We can use it to simplify the current `TSModuleDeclaration` transformation later.

Author: Dunqing

crates/oxc_ast/src/ast_impl/js.rs

@@ -1030,7 +1030,14 @@ impl<'a> Declaration<'a> {
             Declaration::TSInterfaceDeclaration(decl) => Some(&decl.id),
             Declaration::TSEnumDeclaration(decl) => Some(&decl.id),
             Declaration::TSImportEqualsDeclaration(decl) => Some(&decl.id),
-            _ => None,
+            Declaration::TSModuleDeclaration(decl) => {
+                if let TSModuleDeclarationName::Identifier(ident) = &decl.id {
+                    Some(ident)
+                } else {
+                    None
+                }
+            }
+            Declaration::VariableDeclaration(_) => None,
         }
     }
 

crates/oxc_semantic/src/binder.rs

@@ -2,9 +2,11 @@
 
 use std::ptr;
 
+use oxc_allocator::{Address, GetAddress};
 use oxc_ast::{AstKind, ast::*};
 use oxc_ecmascript::{BoundNames, IsSimpleParameterList};
 use oxc_syntax::{
+    node::NodeId,
     scope::{ScopeFlags, ScopeId},
     symbol::SymbolFlags,
 };
@@ -382,27 +384,284 @@ impl<'a> Binder<'a> for TSEnumMember<'a> {
 }
 
 impl<'a> Binder<'a> for TSModuleDeclaration<'a> {
-    fn bind(&self, builder: &mut SemanticBuilder) {
+    fn bind(&self, builder: &mut SemanticBuilder<'a>) {
         // do not bind `global` for `declare global { ... }`
         if self.kind.is_global() {
             return;
         }
         let TSModuleDeclarationName::Identifier(id) = &self.id else { return };
+        let instantiated =
+            get_module_instance_state(builder, self, builder.current_node_id).is_instantiated();
+        let (includes, excludes) = if instantiated {
+            (SymbolFlags::ValueModule, SymbolFlags::ValueModuleExcludes)
+        } else {
+            (SymbolFlags::NameSpaceModule, SymbolFlags::NamespaceModuleExcludes)
+        };
 
         // At declaration time a module has no value declaration it is only when a value declaration
         // is made inside a the scope of a module that the symbol is modified
         let ambient = if self.declare { SymbolFlags::Ambient } else { SymbolFlags::None };
-        let symbol_id = builder.declare_symbol(
-            id.span,
-            &id.name,
-            SymbolFlags::NameSpaceModule | ambient,
-            SymbolFlags::None,
-        );
+        let symbol_id = builder.declare_symbol(id.span, &id.name, includes | ambient, excludes);
 
         id.set_symbol_id(symbol_id);
     }
 }
 
+#[derive(PartialEq, Eq, Debug, Clone, Copy)]
+pub enum ModuleInstanceState {
+    NonInstantiated,
+    Instantiated,
+    ConstEnumOnly,
+}
+
+impl ModuleInstanceState {
+    fn is_instantiated(self) -> bool {
+        self != ModuleInstanceState::NonInstantiated
+    }
+}
+
+/// Determines if a module is instantiated or not.
+///
+/// Based on `https://github.com/microsoft/TypeScript/blob/15392346d05045742e653eab5c87538ff2a3c863/src/compiler/binder.ts#L342-L474`
+fn get_module_instance_state<'a>(
+    builder: &mut SemanticBuilder<'a>,
+    decl: &TSModuleDeclaration<'a>,
+    current_node_id: NodeId,
+) -> ModuleInstanceState {
+    get_module_instance_state_impl(builder, decl, current_node_id, &mut Vec::new())
+}
+
+fn get_module_instance_state_impl<'a, 'b>(
+    builder: &mut SemanticBuilder<'a>,
+    decl: &'b TSModuleDeclaration<'a>,
+    current_node_id: NodeId,
+    module_declaration_stmts: &mut Vec<&'b Statement<'a>>,
+) -> ModuleInstanceState {
+    let address = Address::from_ptr(decl);
+
+    if let Some(state) = builder.module_instance_state_cache.get(&address) {
+        return *state;
+    }
+
+    let Some(body) = &decl.body else {
+        // For modules without a block, we consider them instantiated
+        return ModuleInstanceState::Instantiated;
+    };
+
+    // A module is uninstantiated if it contains only specific declarations
+    let state = match body {
+        TSModuleDeclarationBody::TSModuleBlock(block) => {
+            let mut child_state = ModuleInstanceState::NonInstantiated;
+            for stmt in &block.body {
+                module_declaration_stmts.extend(block.body.iter());
+                child_state = get_module_instance_state_for_statement(
+                    builder,
+                    stmt,
+                    current_node_id,
+                    module_declaration_stmts,
+                );
+                if child_state.is_instantiated() {
+                    break;
+                }
+            }
+            child_state
+        }
+        TSModuleDeclarationBody::TSModuleDeclaration(module) => {
+            get_module_instance_state(builder, module, current_node_id)
+        }
+    };
+
+    builder.module_instance_state_cache.insert(address, state);
+    state
+}
+
+fn get_module_instance_state_for_statement<'a, 'b>(
+    builder: &mut SemanticBuilder<'a>,
+    stmt: &'b Statement<'a>,
+    current_node_id: NodeId,
+    module_declaration_stmts: &mut Vec<&'b Statement<'a>>,
+) -> ModuleInstanceState {
+    let address = stmt.address();
+    if let Some(state) = builder.module_instance_state_cache.get(&address) {
+        return *state;
+    }
+
+    let state = match stmt {
+            // 1. interface declarations, type alias declarations
+            Statement::TSInterfaceDeclaration(_)
+            | Statement::TSTypeAliasDeclaration(_)
+            // 3. non-exported import declarations
+            | Statement::TSImportEqualsDeclaration(_) => {
+                ModuleInstanceState::NonInstantiated
+            }
+            // 2. const enum declarations
+            Statement::TSEnumDeclaration(enum_decl) => {
+                if enum_decl.r#const {
+                    ModuleInstanceState::ConstEnumOnly
+                } else {
+                    ModuleInstanceState::Instantiated
+                }
+            }
+            Statement::ExportDefaultDeclaration(export_decl)  => {
+                if matches!(export_decl.declaration, ExportDefaultDeclarationKind::TSInterfaceDeclaration(_)) {
+                    ModuleInstanceState::NonInstantiated
+                } else {
+                    ModuleInstanceState::Instantiated
+                }
+            }
+            Statement::ExportNamedDeclaration(export_decl) if export_decl.declaration.is_some() => {
+                match export_decl.declaration.as_ref().unwrap() {
+                    Declaration::TSModuleDeclaration(module_decl) => {
+                        get_module_instance_state_impl(builder, module_decl, current_node_id, module_declaration_stmts)
+                    }
+                    decl => if decl.is_type() {
+                        ModuleInstanceState::NonInstantiated
+                    } else {
+                        ModuleInstanceState::Instantiated
+                    }
+                }
+            }
+            // 4. Export alias declarations pointing at uninstantiated modules
+            Statement::ExportNamedDeclaration(export_decl) => {
+                if export_decl.source.is_none() {
+                    let mut export_state = ModuleInstanceState::NonInstantiated;
+                    for specifier in &export_decl.specifiers {
+                        export_state = get_module_instance_state_for_alias_target(builder, specifier, current_node_id, module_declaration_stmts.as_slice());
+                        if export_state.is_instantiated() {
+                            break;
+                        }
+                    }
+                    export_state
+                } else {
+                    ModuleInstanceState::Instantiated
+                }
+            }
+            // 5. other module declarations
+            Statement::TSModuleDeclaration(module_decl) => {
+                get_module_instance_state_impl(builder, module_decl, current_node_id, module_declaration_stmts)
+            }
+            // Any other type of statement means the module is instantiated
+            _ => ModuleInstanceState::Instantiated,
+        };
+
+    builder.module_instance_state_cache.insert(address, state);
+    state
+}
+
+// `module_declaration_stmts` is stored statements that are collected from the all ModuleBlocks.
+// The reason we need to collect and pass in this method is that we need to check export specifiers
+// whether they refer to a declaration that declared in the module block or not. And we can't use
+// `self.nodes.node(node_id)` to get the nested module block's statements since the child ModuleBlock
+// AstNode hasn't created yet.
+fn get_module_instance_state_for_alias_target<'a>(
+    builder: &mut SemanticBuilder<'a>,
+    specifier: &ExportSpecifier<'a>,
+    mut current_node_id: NodeId,
+    module_declaration_stmts: &[&Statement<'a>],
+) -> ModuleInstanceState {
+    let ModuleExportName::IdentifierReference(local) = &specifier.local else {
+        return ModuleInstanceState::Instantiated;
+    };
+
+    let name = local.name;
+    let mut current_block_stmts = module_declaration_stmts.to_vec();
+    loop {
+        let mut found = false;
+        for stmt in &current_block_stmts {
+            match stmt {
+                Statement::VariableDeclaration(decl) => {
+                    decl.bound_names(&mut |id| {
+                        if id.name == name {
+                            found = true;
+                        }
+                    });
+                }
+                match_declaration!(Statement) => {
+                    if stmt.to_declaration().id().is_some_and(|id| id.name == name) {
+                        found = true;
+                    }
+                }
+                Statement::ExportNamedDeclaration(decl) => match decl.declaration.as_ref() {
+                    Some(Declaration::VariableDeclaration(decl)) => {
+                        decl.bound_names(&mut |id| {
+                            if id.name == name {
+                                found = true;
+                            }
+                        });
+                    }
+                    Some(decl) => {
+                        if decl.id().is_some_and(|id| id.name == name) {
+                            found = true;
+                        }
+                    }
+                    None => {
+                        continue;
+                    }
+                },
+                Statement::ExportDefaultDeclaration(decl) => match &decl.declaration {
+                    ExportDefaultDeclarationKind::FunctionDeclaration(decl) => {
+                        if decl.id.as_ref().is_some_and(|id| id.name == name) {
+                            found = true;
+                        }
+                    }
+                    ExportDefaultDeclarationKind::ClassDeclaration(decl) => {
+                        if decl.id.as_ref().is_some_and(|id| id.name == name) {
+                            found = true;
+                        }
+                    }
+                    ExportDefaultDeclarationKind::TSInterfaceDeclaration(decl) => {
+                        if decl.id.name == name {
+                            found = true;
+                        }
+                    }
+                    _ => {}
+                },
+                _ => {}
+            }
+
+            if found {
+                if matches!(stmt, Statement::TSImportEqualsDeclaration(_)) {
+                    // Treat re-exports of import aliases as instantiated,
+                    // since they're ambiguous. This is consistent with
+                    // `export import x = mod.x` being treated as instantiated:
+                    //   import x = mod.x;
+                    //   export { x };
+                    return ModuleInstanceState::Instantiated;
+                }
+                return get_module_instance_state_for_statement(
+                    builder,
+                    stmt,
+                    current_node_id,
+                    &mut Vec::default(), // No need to check export specifier
+                );
+            }
+        }
+
+        let Some(node) = builder.nodes.ancestors(current_node_id).skip(1).find(|node| {
+            matches!(
+                node.kind(),
+                AstKind::Program(_) | AstKind::TSModuleBlock(_) | AstKind::BlockStatement(_)
+            )
+        }) else {
+            break;
+        };
+
+        current_node_id = node.id();
+        current_block_stmts.clear();
+        // Didn't find the declaration whose name matches export specifier
+        // in the current block, so we need to check the parent block.
+        current_block_stmts.extend(match node.kind() {
+            AstKind::Program(program) => program.body.iter(),
+            AstKind::TSModuleBlock(block) => block.body.iter(),
+            AstKind::BlockStatement(block) => block.body.iter(),
+            _ => unreachable!(),
+        });
+    }
+
+    // Not found in any of the statements
+    ModuleInstanceState::Instantiated
+}
+
 impl<'a> Binder<'a> for TSTypeParameter<'a> {
     fn bind(&self, builder: &mut SemanticBuilder) {
         let scope_id = if matches!(