biomejs · ematipico · Sep 2, 2026 · Sep 2, 2026 · coderabbitai · Sep 2, 2026
diff --git a/.changeset/fix-interface-declaration-merging.md b/.changeset/fix-interface-declaration-merging.md
@@ -0,0 +1,23 @@
+---
+"@biomejs/biome": patch
+---
+
+Fixed [#6644](https://github.com/biomejs/biome/issues/6644): [`noUnusedVariables`](https://biomejs.dev/linter/rules/no-unused-variables/) now recognizes all interface declarations in a TypeScript declaration-merging group when the interface is referenced.
+
+The following snippet no longer triggers the rule.
+
+```ts
+interface Things {
+    foo: string;
+}
+
+interface Things {
+    bar: string;
+}
+
+export type Key = keyof Things;
+
+interface Things {
+    baz: string;
+}
+```
diff --git a/crates/biome_js_analyze/src/lint/correctness/no_unused_variables.rs b/crates/biome_js_analyze/src/lint/correctness/no_unused_variables.rs
@@ -475,9 +475,9 @@ fn is_implemented_overload_type_parameter(
         }
 
         signatures.iter().any(|id| {
-            model.binding_by_id(*id).is_some_and(|binding| {
-                binding.syntax().text_trimmed_range() == signature_range
-            })
+            model
+                .binding_by_id(*id)
+                .is_some_and(|binding| binding.syntax().text_trimmed_range() == signature_range)
         })
     })
 }
@@ -735,6 +735,9 @@ fn is_declaration_merged_with_used(
 ) -> Option<bool> {
     let decl = binding.declaration()?;
     match decl {
+        AnyJsBindingDeclaration::TsInterfaceDeclaration(_) => {
+            is_interface_merged_with_used(model, binding)
+        }
         AnyJsBindingDeclaration::TsModuleDeclaration(_) => {
             is_namespace_merged_with_used_value(model, binding)
         }
@@ -745,6 +748,30 @@ fn is_declaration_merged_with_used(
     }
 }
 
+fn is_interface_merged_with_used(
+    model: &SemanticModel,
+    binding: &AnyJsIdentifierBinding,
+) -> Option<bool> {
+    let name_token = binding.name_token().ok()?;
+    let name = name_token.text_trimmed();
+    let scope = model.scope_hoisted_to(binding.syntax())?;
+
+    Some(scope.bindings().any(|scope_binding| {
+        let other = scope_binding.tree();
+        let Some(other_declaration) = other.declaration() else {
+            return false;
+        };
+        matches!(
+            other_declaration,
+            AnyJsBindingDeclaration::TsInterfaceDeclaration(_)
+        ) && other
+            .name_token()
+            .is_ok_and(|other_name| other_name.text_trimmed() == name)
+            && (model.is_exported(&other)
+                || !is_unused_by_references(model, &other, other_declaration.syntax()))
+    }))
+}
+
 /// Returns `true` if `call` is a call to a simple identifier named `name`.
 fn is_call_to(call: &JsCallExpression, name: &str) -> bool {
     let Ok(AnyJsExpression::JsIdentifierExpression(ident)) = call.callee() else {
@@ -889,8 +916,7 @@ pub fn is_unused(model: &SemanticModel, binding: &AnyJsIdentifierBinding) -> boo
     let Some(declaration) = binding.declaration() else {
         return false;
     };
-    let declaration = declaration.syntax();
-    if !is_unused_by_references(model, binding, declaration) {
+    if !is_unused_by_references(model, binding, declaration.syntax()) {
         return false;
     }
     !is_declaration_merged_with_used(model, binding).unwrap_or(false)

diff --git a/...s_analyze/tests/specs/correctness/noUnusedVariables/invalidInterfaceDeclarationMerging.ts b/...s_analyze/tests/specs/correctness/noUnusedVariables/invalidInterfaceDeclarationMerging.ts
@@ -0,0 +1,26 @@
+/* should generate diagnostics */
+
+interface Unused {
+    first: string;
+}
+
+interface Unused {
+    second: string;
+}
+
+const ValueOnly = 0;
+interface ValueOnly {
+    prop: string;
+}
+console.log(ValueOnly);
+
+interface Shadowed {
+    outer: string;
+}
+export function useShadowed() {
+    interface Shadowed {
+        inner: string;
+    }
+    type Key = keyof Shadowed;
+    return null as Key;
+}
diff --git a/...lyze/tests/specs/correctness/noUnusedVariables/invalidInterfaceDeclarationMerging.ts.snap b/...lyze/tests/specs/correctness/noUnusedVariables/invalidInterfaceDeclarationMerging.ts.snap
@@ -0,0 +1,102 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: invalidInterfaceDeclarationMerging.ts
+---
+# Input
+```ts
+/* should generate diagnostics */
+
+interface Unused {
+    first: string;
+}
+
+interface Unused {
+    second: string;
+}
+
+const ValueOnly = 0;
+interface ValueOnly {
+    prop: string;
+}
+console.log(ValueOnly);
+
+interface Shadowed {
+    outer: string;
+}
+export function useShadowed() {
+    interface Shadowed {
+        inner: string;
+    }
+    type Key = keyof Shadowed;
+    return null as Key;
+}
+
+```
+
+# Diagnostics
+```
+invalidInterfaceDeclarationMerging.ts:3:11 lint/correctness/noUnusedVariables ━━━━━━━━━━━━━━━━━━━━━━
+
+  ! This interface Unused is unused.
+
+    1 │ /* should generate diagnostics */
+    2 │ 
+  > 3 │ interface Unused {
+      │           ^^^^^^
+    4 │     first: string;
+    5 │ }
+
+  i Unused variables are often the result of typos, incomplete refactors, or other sources of bugs.
+
+
+```
+
+```
+invalidInterfaceDeclarationMerging.ts:7:11 lint/correctness/noUnusedVariables ━━━━━━━━━━━━━━━━━━━━━━
+
+  ! This interface Unused is unused.
+
+    5 │ }
+    6 │ 
+  > 7 │ interface Unused {
+      │           ^^^^^^
+    8 │     second: string;
+    9 │ }
+
+  i Unused variables are often the result of typos, incomplete refactors, or other sources of bugs.
+
+
+```
+
+```
+invalidInterfaceDeclarationMerging.ts:12:11 lint/correctness/noUnusedVariables ━━━━━━━━━━━━━━━━━━━━━
+
+  ! This interface ValueOnly is unused.
+
+    11 │ const ValueOnly = 0;
+  > 12 │ interface ValueOnly {
+       │           ^^^^^^^^^
+    13 │     prop: string;
+    14 │ }
+
+  i Unused variables are often the result of typos, incomplete refactors, or other sources of bugs.
+
+
+```
+
+```
+invalidInterfaceDeclarationMerging.ts:17:11 lint/correctness/noUnusedVariables ━━━━━━━━━━━━━━━━━━━━━
+
+  ! This interface Shadowed is unused.
+
+    15 │ console.log(ValueOnly);
+    16 │ 
+  > 17 │ interface Shadowed {
+       │           ^^^^^^^^
+    18 │     outer: string;
+    19 │ }
+
+  i Unused variables are often the result of typos, incomplete refactors, or other sources of bugs.
+
+
+```
diff --git a/..._js_analyze/tests/specs/correctness/noUnusedVariables/validInterfaceDeclarationMerging.ts b/..._js_analyze/tests/specs/correctness/noUnusedVariables/validInterfaceDeclarationMerging.ts
@@ -0,0 +1,19 @@
+/* should not generate diagnostics */
+
+interface Things {
+    foo: string;
+}
+
+interface Things {
+    bar: string;
+}
+
+type Key = keyof Things;
+
+interface Things {
+    baz: string;
+}
+
+export function doStuff(key: Key) {
+    return key;
+}
diff --git a/...nalyze/tests/specs/correctness/noUnusedVariables/validInterfaceDeclarationMerging.ts.snap b/...nalyze/tests/specs/correctness/noUnusedVariables/validInterfaceDeclarationMerging.ts.snap
@@ -0,0 +1,27 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: validInterfaceDeclarationMerging.ts
+---
+# Input
+```ts
+/* should not generate diagnostics */
+
+interface Things {
+    foo: string;
+}
+
+interface Things {
+    bar: string;
+}
+
+type Key = keyof Things;
+
+interface Things {
+    baz: string;
+}
+
+export function doStuff(key: Key) {
+    return key;
+}
+
+```