refactor(module_graph): preserve same-name function overloads as a set (#10585)

Author: IxxyDev

crates/biome_js_semantic/src/events.rs

@@ -576,7 +576,7 @@ impl SemanticEventExtractor {
                         self.push_binding(hoisted_scope_id, BindingName::Value(name), info);
                     }
                     AnyJsBindingDeclaration::JsFunctionDeclaration(_) => {
-                        declaration_kind = JsDeclarationKind::HoistedValue;
+                        declaration_kind = JsDeclarationKind::Function;
                         let is_in_strict_mode = self
                             .scopes
                             .last()
@@ -588,8 +588,12 @@ impl SemanticEventExtractor {
                         };
                         self.push_binding(hoisted_scope_id, BindingName::Value(name), info);
                     }
-                    AnyJsBindingDeclaration::TsDeclareFunctionDeclaration(_)
-                    | AnyJsBindingDeclaration::TsDeclareFunctionExportDefaultDeclaration(_)
+                    AnyJsBindingDeclaration::TsDeclareFunctionDeclaration(_) => {
+                        declaration_kind = JsDeclarationKind::Function;
+                        hoisted_scope_id = self.scope_index_to_hoist_declarations(1);
+                        self.push_binding(hoisted_scope_id, BindingName::Value(name), info);
+                    }
+                    AnyJsBindingDeclaration::TsDeclareFunctionExportDefaultDeclaration(_)
                     | AnyJsBindingDeclaration::JsFunctionExportDefaultDeclaration(_) => {
                         declaration_kind = JsDeclarationKind::HoistedValue;
                         hoisted_scope_id = self.scope_index_to_hoist_declarations(1);

crates/biome_js_semantic/src/semantic_model/binding.rs

@@ -25,14 +25,19 @@ pub enum JsDeclarationKind {
     /// Declares both a type and a value.
     Enum,
 
+    /// A `function` declaration or a `declare function` overload signature.
+    ///
+    /// Declares only a value, and is hoisted to the function scope.
+    Function,
+
     /// A generic type parameter, declared in angle brackets.
     ///
     /// For example: `<T>`.
     ///
     /// Declares only a type.
     Generic,
 
-    /// A `function` or `var` declaration.
+    /// A `var` declaration.
     ///
     /// Declares only a value, and is hoisted to the function scope.
     HoistedValue,
@@ -110,6 +115,7 @@ impl JsDeclarationKind {
             self,
             Self::Class
                 | Self::Enum
+                | Self::Function
                 | Self::HoistedValue
                 | Self::Import
                 | Self::Namespace
@@ -129,14 +135,14 @@ impl JsDeclarationKind {
             if let Some(declaration) = AnyJsDeclaration::cast_ref(&ancestor) {
                 return match declaration {
                     AnyJsDeclaration::JsClassDeclaration(_) => Self::Class,
-                    AnyJsDeclaration::JsFunctionDeclaration(_) => Self::HoistedValue,
+                    AnyJsDeclaration::JsFunctionDeclaration(_) => Self::Function,
                     AnyJsDeclaration::JsVariableDeclaration(decl) => match decl.variable_kind() {
                         Ok(JsVariableKind::Const | JsVariableKind::Let) => Self::Value,
                         Ok(JsVariableKind::Using) => Self::Using,
                         Ok(JsVariableKind::Var) => Self::HoistedValue,
                         Err(_) => Self::Unknown,
                     },
-                    AnyJsDeclaration::TsDeclareFunctionDeclaration(_) => Self::HoistedValue,
+                    AnyJsDeclaration::TsDeclareFunctionDeclaration(_) => Self::Function,
                     AnyJsDeclaration::TsEnumDeclaration(_) => Self::Enum,
                     AnyJsDeclaration::TsExternalModuleDeclaration(_) => Self::Module,
                     AnyJsDeclaration::TsInterfaceDeclaration(_) => Self::Interface,
@@ -246,7 +252,8 @@ impl TsBindingReference {
         match self {
             Self::ValueType(binding_id)
             | Self::TypeAndValueType(binding_id)
-            | Self::NamespaceAndValueType(binding_id) => binding_id,
+            | Self::NamespaceAndValueType(binding_id)
+            | Self::Type(binding_id) => binding_id,
             Self::Merged {
                 ty,
                 value_ty,
@@ -255,14 +262,15 @@ impl TsBindingReference {
                 .or(namespace_ty)
                 .or(ty)
                 .expect("a merged reference must have at least two fields set to `Some`"),
-            Self::Type(binding_id) => binding_id,
         }
     }
 
     /// Creates a union from this binding reference with another.
     ///
     /// If both bindings refer to the same kind of type, the binding ID(s) from
-    /// `other` takes precedence.
+    /// `other` take precedence. Same-name function overloads are tracked
+    /// separately in the scope's overload map, so here two functions simply
+    /// merge last-wins like any other pair of values.
     pub fn union_with(self, other: Self) -> Self {
         match (self, other) {
             (Self::Type(own_binding_id), Self::ValueType(other_binding_id)) => {

crates/biome_js_semantic/src/semantic_model/builder.rs

@@ -6,6 +6,7 @@ use biome_js_syntax::{
 use biome_jsdoc_comment::JsdocComment;
 use biome_rowan::SyntaxNodePtr;
 use rustc_hash::{FxHashMap, FxHashSet};
+use std::collections::hash_map::Entry;
 
 /// Builds the [SemanticModel] consuming [SemanticEvent] and [JsSyntaxNode].
 /// For a good example on how to use it see [semantic_model].
@@ -167,6 +168,7 @@ impl SemanticModelBuilder {
                     children: vec![],
                     bindings: vec![],
                     bindings_by_name: FxHashMap::default(),
+                    overloads_by_name: FxHashMap::default(),
                     read_references: vec![],
                     write_references: vec![],
                     is_closure,
@@ -235,13 +237,39 @@ impl SemanticModelBuilder {
                                 declaration_kind,
                             );
 
-                        scope
-                            .bindings_by_name
-                            .entry(name)
-                            .and_modify(|existing| {
-                                *existing = existing.union_with(binding_reference);
-                            })
-                            .or_insert(binding_reference);
+                        // Update `bindings_by_name` (declaration merging), keeping
+                        // the previous reference so we can detect same-name
+                        // function overloads on collision.
+                        let previous = match scope.bindings_by_name.entry(name.clone()) {
+                            Entry::Occupied(mut existing) => {
+                                let previous = *existing.get();
+                                *existing.get_mut() = previous.union_with(binding_reference);
+                                Some(previous)
+                            }
+                            Entry::Vacant(slot) => {
+                                slot.insert(binding_reference);
+                                None
+                            }
+                        };
+
+                        // Record an overload set only when a function follows a
+                        // same-name function (rare). The common case of a unique
+                        // name adds nothing beyond the check above, keeping the
+                        // hot build path allocation- and rehash-free.
+                        if matches!(declaration_kind, JsDeclarationKind::Function)
+                            && let Some(previous) = previous
+                        {
+                            let previous_id = previous.value_ty_or_ty();
+                            if self.bindings[previous_id.index()].declaration_kind
+                                == JsDeclarationKind::Function
+                            {
+                                scope
+                                    .overloads_by_name
+                                    .entry(name)
+                                    .or_insert_with(|| smallvec::smallvec![previous_id])
+                                    .push(binding_id);
+                            }
+                        }
                     }
                 }
 

crates/biome_js_semantic/src/semantic_model/scope.rs

@@ -2,6 +2,7 @@ use super::*;
 use biome_js_syntax::TextRange;
 use biome_rowan::TokenText;
 use rustc_hash::FxHashMap;
+use smallvec::SmallVec;
 use std::sync::Arc;
 
 #[derive(Debug)]
@@ -17,6 +18,10 @@ pub(crate) struct SemanticModelScopeData {
     // Map pointing to the [bindings] vec of each bindings by its name,
     // tracking the Type/Value/Namespace distinction for TypeScript declaration merging
     pub(crate) bindings_by_name: FxHashMap<TokenText, TsBindingReference>,
+    // Same-name `function` / `declare function` declarations hoisted to this scope,
+    // in source order, keyed by name. Tracked separately from `bindings_by_name` so
+    // overload sets survive declaration merging with a same-name type/namespace.
+    pub(crate) overloads_by_name: FxHashMap<TokenText, SmallVec<[BindingId; 2]>>,
     // All read references of a scope
     pub(crate) read_references: Vec<ReferenceId>,
     // All write references of a scope
@@ -131,6 +136,21 @@ impl Scope {
         data.bindings_by_name.get(name).copied()
     }
 
+    /// Returns every set of same-name function overloads declared in this
+    /// scope, each in source order. Only names with two or more `function` /
+    /// `declare function` declarations are returned; a single function is not
+    /// an overload set.
+    ///
+    /// It **does not** return overloads of parent scopes.
+    pub fn overload_sets(&self) -> Vec<Vec<BindingId>> {
+        self.data.scopes[self.id.index()]
+            .overloads_by_name
+            .values()
+            .filter(|set| set.len() > 1)
+            .map(|set| set.to_vec())
+            .collect()
+    }
+
     /// Checks if the current scope is one of the ancestor of "other". Given
     /// that [Scope::ancestors] return "self" as the first scope,
     /// this function returns true for:

crates/biome_js_semantic/src/semantic_model/tests.rs

@@ -2,7 +2,7 @@
 mod test {
     use crate::{
         BindingExtensions, CanBeImportedExported, SemanticFlavor, SemanticModelOptions,
-        SemanticScopeExtensions, semantic_model,
+        SemanticScopeExtensions, TsBindingReference, semantic_model,
     };
     use biome_js_parser::JsParserOptions;
     use biome_js_syntax::{
@@ -19,6 +19,51 @@ mod test {
         }
     }
 
+    /// Regression: same-name function overloads must keep their full set even
+    /// when a same-name type/interface/namespace merges into the value's name.
+    /// Previously the overload set lived inside `TsBindingReference` and was
+    /// collapsed to the last signature the moment a type merged in.
+    #[test]
+    pub fn overload_sets_survive_declaration_merging() {
+        let r = biome_js_parser::parse(
+            "function f(a: number): number;\n\
+             function f(a: string): string;\n\
+             function f(a: number | string): number | string { return a; }\n\
+             type f = number;\n",
+            JsFileSource::ts(),
+            JsParserOptions::default(),
+        );
+        let model = semantic_model(&r.tree(), SemanticModelOptions::default());
+        let scope = model.global_scope();
+
+        // The full overload set (three signatures) is preserved.
+        let overload_sets = scope.overload_sets();
+        assert_eq!(overload_sets.len(), 1);
+        assert_eq!(overload_sets[0].len(), 3);
+
+        // Name resolution still merges the value slot with the type slot.
+        assert!(matches!(
+            scope.get_binding_reference("f"),
+            Some(TsBindingReference::Merged {
+                ty: Some(_),
+                value_ty: Some(_),
+                ..
+            })
+        ));
+    }
+
+    /// A single function is not an overload set.
+    #[test]
+    pub fn single_function_is_not_an_overload_set() {
+        let r = biome_js_parser::parse(
+            "function f(a: number): number { return a; }\n",
+            JsFileSource::ts(),
+            JsParserOptions::default(),
+        );
+        let model = semantic_model(&r.tree(), SemanticModelOptions::default());
+        assert!(model.global_scope().overload_sets().is_empty());
+    }
+
     #[test]
     pub fn ok_semantic_model() {
         let r = biome_js_parser::parse(

crates/biome_js_semantic/src/snapshots/format_js.snap

@@ -126,7 +126,7 @@ Scope {
       Scope: ScopeId(2)
       Imported: false
       Exported: true
-      Kind: HoistedValue
+      Kind: Function
       ident: add
       JsDoc Comments: Adds two numbers.
 @param x - first operand
@@ -205,7 +205,7 @@ Scope {
       Scope: ScopeId(9)
       Imported: false
       Exported: true
-      Kind: HoistedValue
+      Kind: Function
       ident: outer
     }
     Scope {

crates/biome_js_semantic/src/snapshots/format_ts.snap

@@ -138,7 +138,7 @@ Scope {
       Scope: ScopeId(5)
       Imported: false
       Exported: true
-      Kind: HoistedValue
+      Kind: Function
       ident: greet
       JsDoc Comments: Creates a greeting.
 @param cfg - the configuration

crates/biome_module_graph/src/js_module_info/collector.rs

@@ -409,6 +409,29 @@ impl JsModuleInfoCollector {
                 self.bindings[index].ty = ty;
             }
         }
+
+        // A set of same-name function overloads becomes an object with one call
+        // signature per declaration, placed on the binding that name resolution
+        // returns for the set (its last one) so a call site can select among them.
+        let carriers: Vec<(usize, Vec<TypeMember>)> = semantic_model
+            .scopes()
+            .flat_map(|scope| scope.overload_sets())
+            .map(|set| {
+                let signatures = set
+                    .iter()
+                    .map(|id| TypeMember {
+                        kind: TypeMemberKind::CallSignature,
+                        ty: self.bindings[id.index()].ty.clone(),
+                    })
+                    .collect();
+                let representative = set.last().expect("overload set has 2+ entries").index();
+                (representative, signatures)
+            })
+            .collect();
+        for (representative, signatures) in carriers {
+            let ty = self.reference_to_owned_data(TypeData::object_with_members(signatures.into()));
+            self.bindings[representative].ty = ty;
+        }
     }
 
     fn has_writable_reference(&self, semantic_model: &SemanticModel, range: TextRange) -> bool {

crates/biome_module_graph/src/js_module_info/scope.rs

@@ -154,6 +154,7 @@ impl FusedIterator for ScopeBindingsIter {}
 #[cfg(test)]
 mod tests {
     use super::*;
+    use biome_js_semantic::JsDeclarationKind;
 
     #[test]
     fn binding_reference_merging() {
@@ -213,4 +214,56 @@ mod tests {
             TsBindingReference::NamespaceAndValueType(BindingId::new(0))
         );
     }
+
+    #[test]
+    fn function_declarations_are_plain_value_references() {
+        // Functions are ordinary value references here; same-name overloads are
+        // accumulated separately in the scope's `overloads_by_name` map, so the
+        // `TsBindingReference` itself stays a small, `Copy` POD enum.
+        assert_eq!(
+            TsBindingReference::from_binding_and_declaration_kind(
+                BindingId::new(0),
+                JsDeclarationKind::Function,
+            ),
+            TsBindingReference::ValueType(BindingId::new(0))
+        );
+        assert_eq!(
+            TsBindingReference::from_binding_and_declaration_kind(
+                BindingId::new(0),
+                JsDeclarationKind::HoistedValue,
+            ),
+            TsBindingReference::ValueType(BindingId::new(0))
+        );
+        assert_eq!(
+            TsBindingReference::from_binding_and_declaration_kind(
+                BindingId::new(0),
+                JsDeclarationKind::Value,
+            ),
+            TsBindingReference::ValueType(BindingId::new(0))
+        );
+    }
+
+    #[test]
+    fn same_name_functions_merge_last_wins() {
+        // Two same-name functions collapse to the last (implementation) signature
+        // in `bindings_by_name`; the full overload set lives in `overloads_by_name`.
+        assert_eq!(
+            TsBindingReference::ValueType(BindingId::new(0))
+                .union_with(TsBindingReference::ValueType(BindingId::new(1))),
+            TsBindingReference::ValueType(BindingId::new(1))
+        );
+
+        // A function merging with a same-name type still produces a `Merged`
+        // reference, so name resolution keeps both the value and the type slot
+        // even though the overload set is tracked elsewhere.
+        assert_eq!(
+            TsBindingReference::ValueType(BindingId::new(0))
+                .union_with(TsBindingReference::Type(BindingId::new(1))),
+            TsBindingReference::Merged {
+                ty: Some(BindingId::new(1)),
+                value_ty: Some(BindingId::new(0)),
+                namespace_ty: None,
+            }
+        );
+    }
 }

crates/biome_service/src/snapshots/biome_service__workspace__tests__debug_semantic_model.snap

@@ -35,7 +35,7 @@ Scope {
       Scope: ScopeId(2)
       Imported: false
       Exported: false
-      Kind: HoistedValue
+      Kind: Function
       ident: foo
     }
     Scope {