fix(inference): argument and type parameters inference (#10992)

Author: ematipico

.changeset/rude-bats-fall.md

@@ -0,0 +1,14 @@
+---
+"@biomejs/biome": patch
+---
+
+Fixed [`noMisusedPromises`](https://biomejs.dev/linter/rules/no-misused-promises/): The rule now reports Promise-returning callbacks where a synchronous callback is expected when calls use tuple spreads or tuple rest parameters, including generic and deeply nested tuples, and when constructor signatures come from interface or object types. Recursive or excessively nested tuple spreads use a conservative fallback so analysis terminates.
+
+For example, the following callback is now reported.
+
+```ts
+declare function consume(...args: [number, () => void]): void;
+const prefix: [number] = [1];
+
+consume(...prefix, async () => {});
+```

.claude/skills/README.md

@@ -46,6 +46,7 @@ This applies to all agents, all skills, and all contributions. Keep code and doc
 | **[biome-developer](./biome-developer/SKILL.md)** | General development best practices, common gotchas, Biome-specific patterns | Any agent |
 | **[testing-codegen](./testing-codegen/SKILL.md)** | Run tests, manage snapshots, generate code | Any agent |
 | **[changeset](./changeset/SKILL.md)** | Create and write proper changesets for the CHANGELOG | Any agent |
+| **[doc-comments](./doc-comments/SKILL.md)** | Write comments and rustdoc addressed to developers, not end users | Any agent |
 | **[pull-request](./pull-request/SKILL.md)** | Create PRs with proper titles, descriptions, and branch targeting | Any agent |
 | **[type-inference](./type-inference/SKILL.md)** | Work with module graph and type inference system | `biome-lint-engineer` |
 | **[diagnostics-development](./diagnostics-development/SKILL.md)** | Create user-friendly error messages and diagnostics | Any agent |

.claude/skills/doc-comments/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: doc-comments
+description: How to write inline comments, rustdoc, and module documentation in the Biome codebase. The audience is Biome developers reading the source, not end users. Use whenever writing or editing `//` comments, `///` item docs, or `//!` module docs — including comments added incidentally while fixing bugs or implementing features.
+compatibility: Designed for coding agents working on the Biome codebase (github.com/biomejs/biome).
+---
+
+## Purpose
+
+Comments and doc comments in this repository are read by contributors, months
+or years after they were written, with none of the context you have right now.
+This skill defines who that reader is, what each kind of comment is for, and
+which patterns are banned.
+
+**Scope boundary:** rustdoc inside `declare_lint_rule!` / `declare_assist_rule!`
+blocks is end-user documentation — it is generated into the website. This skill
+does not apply there; see [lint-rule-development](../lint-rule-development/SKILL.md).
+
+## The Reader
+
+Write for a Biome contributor who is competent in Rust but has **no access to
+your current context**: not this conversation, not the pull request, not the
+issue, not the diff. They see only the repository at HEAD.
+
+Two consequences follow directly:
+
+1. **Never narrate change history.** Words like "now", "previously",
+   "no longer", "the new approach" are meaningless at HEAD, where only one
+   approach exists. State how the code works, not how it came to be.
+2. **Never address the reviewer.** A comment that argues your change is
+   correct ("this properly handles X") belongs in the PR description, not in
+   the source. The comment must justify the code as it stands, permanently.
+
+## Three Kinds of Documentation, Three Different Jobs
+
+| Kind | Job | Contains |
+| ---- | --- | -------- |
+| `//!` module docs | Explanation | Why the module exists, core concepts and terminology, how the pieces relate, design rationale |
+| `///` item docs | Reference | The contract: behavior, inputs and outputs, invariants, panics, errors. Neutral and factual |
+| `//` inline comments | Rationale | Only what the code cannot say: constraints, workarounds (with issue links), non-obvious coupling, why the obvious alternative is wrong |
+
+Do not mix the jobs. Implementation details do not belong in `///` docs — put
+them as `//` comments inside the body. The contract does not belong scattered
+across inline comments — put it on the item.
+
+## The Deletion Test
+
+Before writing any comment, ask: **does this state something the reader cannot
+recover from the code itself?**
+
+- If the information is already carried by names, types, or structure, do not
+  write the comment. If the name fails to carry it, improve the name.
+- Information that legitimately needs a comment: an invariant, a rationale, a
+  coupling to code elsewhere, a workaround with a link, surprising behavior of
+  a dependency, a term of art the module defines.
+
+When editing later, the same test applies in reverse: a comment that no longer
+passes it should be deleted, not left to rot.
+
+## Banned Patterns
+
+**Narrating the next line.** Delete these on sight:
+
+```rust
+// Increment the generation counter
+generation += 1;
+```
+
+**Change-history narration.** Rewrite as present-tense rationale:
+
+```rust
+// BAD: We now intern types instead of cloning them.
+// GOOD: Interning avoids cloning these types on every lookup.
+```
+
+**Reviewer-addressed justification.** Move the argument to the PR:
+
+```rust
+// BAD: This correctly handles the overload case from the bug report.
+// GOOD: Overloads are matched by arity before parameter types, so a
+//       partial-arity call cannot select the wrong candidate.
+```
+
+**Restated rustdoc.** A `///` doc that rewords the item name says nothing:
+
+```rust
+// BAD:
+/// Handles the type inference.
+fn infer_types(...)
+
+// GOOD:
+/// Infers the type of `expr` in the scope of `module`, returning
+/// `TypeData::Unknown` when the expression references an unresolved import.
+fn infer_types(...)
+```
+
+**Vague hedging.** "Some cases", "various reasons", "handles edge cases",
+"etc." — either name them or drop the sentence.
+
+**Emojis.** Banned everywhere in this repository, comments included.
+
+**Ad-hoc section banners** (`// ----- helpers -----`, `// ==== TYPES ====`).
+For grouping in long files, use the region comment pattern below instead.
+
+## Region Comments
+
+Long files group related items with paired region markers:
+
+```rust
+// #region FILE-LEVEL METHODS
+...
+// #endregion
+```
+
+This is an established convention across the codebase (`biome_service`,
+`biome_module_graph`, `biome_rowan`, the parsers). The `Workspace` trait in
+[`crates/biome_service/src/workspace.rs`](../../../crates/biome_service/src/workspace.rs)
+uses it to group its methods (`PROJECT-LEVEL METHODS`, `FILE-LEVEL METHODS`,
+`SEARCH-RELATED METHODS`). Editors fold on these markers, which is the point:
+they exist for navigation, not documentation.
+
+Rules:
+
+- Every `// #region` has a matching `// #endregion`. An unpaired marker breaks
+  editor folding silently.
+- The name states what the group contains. It can be a plain label
+  (`Shared helpers`) or anchored to a function (`#region parse_thematic_break_parts`)
+  when the region holds one entry point and its private support code.
+- Use regions only where they earn their keep: files or `impl`/`trait` blocks
+  long enough that folding helps. A file that fits on two screens does not
+  need them.
+- A region name is organization, not documentation. It never substitutes for
+  rustdoc on the items inside it.
+
+## Editing Existing Code
+
+- Preserve existing doc comments. If your change alters behavior, extend or
+  correct the specific prose — never replace it with generic text. Deleting
+  hard-won context is worse than leaving a comment slightly stale.
+- Match the surrounding density. A heavily documented module deserves the same
+  level on new items; do not blanket a sparse module with comments.
+
+## Exemplar
+
+The `//!` module docs at the top of
+[`crates/biome_service/src/workspace.rs`](../../../crates/biome_service/src/workspace.rs)
+show the target register. They define a term the rest of the module depends on
+("open documents") and give its meaning in both the LSP and CLI contexts; they
+explain a design decision the signatures alone would make confusing (the
+workspace is stateful, yet every method takes `&self`, because the trait must
+be thread-safe and caching happens internally); and they state the error
+philosophy once, at the top, instead of repeating it on every method.
+Everything is present tense; nothing mentions how the design evolved or
+defends a change.
+
+## Self-Check Before Finishing
+
+After completing any task that touched comments, re-read **only the comments
+in your diff**, in isolation from the code changes:
+
+1. Does each one pass the deletion test?
+2. Does any reference the conversation, the change itself, or the reviewer?
+3. Would a reader without access to the diff understand each one?
+
+Fix or delete what fails. Deletion is the default; a missing comment is
+cheaper than a misleading one.
+
+## References
+
+- [Diátaxis](https://diataxis.fr/) — the framework behind the
+  explanation / reference / rationale split above.
+- [lint-rule-development](../lint-rule-development/SKILL.md) — for rule
+  rustdoc, which is end-user documentation.

.claude/skills/type-inference/SKILL.md

@@ -104,7 +104,7 @@ TypeData::TypeofExpression(TypeofExpression::Addition {
 3. Converts to `TypeReference::Resolved` if found locally
 4. Converts to `TypeReference::Import` if from import statement
 5. Falls back to globals (like `Array`, `Promise`)
-6. Uses `TypeReference::Unknown` if nothing found
+6. Uses `TypeReference::unknown()` if nothing is found
 
 **Where**: Implemented in `js_module_info/collector.rs`
 
@@ -119,9 +119,13 @@ TypeData::TypeofExpression(TypeofExpression::Addition {
 2. Resolves `TypeReference::Import` by following imports
 3. Converts to `TypeReference::Resolved` after following imports
 
-**Where**: Implemented in `js_module_info/module_resolver.rs`
+**Where**: The Salsa-backed implementation starts at
+`db/queries/type_inference.rs::infer_module_types` and uses helpers under
+`db/type_inference/`. `js_module_info/module_resolver.rs` contains the legacy
+`TypeResolver`-based path.
 
-**Limitation**: Results cannot be cached (would become stale on file changes)
+**Caching**: `infer_module_types` is tracked by Salsa. Imported module results
+are dependencies, so Salsa invalidates affected importers after a change.
 
 ## Working with Type Resolvers
 
@@ -287,7 +291,7 @@ let raw_data: &TypeData = resolved_data.as_raw_data();
 - **Resolver context**: Keep `ResolvedTypeData` when possible, don't extract raw `TypeData` early
 - **Performance**: Type vectors are fast - iterate directly instead of recursive traversal
 - **IDE focus**: All design decisions prioritize instant IDE updates over CLI performance
-- **No caching**: Full inference results can't be cached (would become stale)
+- **Caching**: Salsa memoizes full-inference query results and invalidates them through tracked module dependencies
 - **Globals**: Currently hardcoded, eventually should use TypeScript's `.d.ts` files
 
 ## Common Patterns

AGENTS.md

@@ -218,6 +218,17 @@ cargo test
 
 Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.
 
+### 7. Comments and Doc Comments
+
+These rules apply to **every** comment you write, including ones added incidentally while fixing a bug. Full guidance with examples: [`.claude/skills/doc-comments/SKILL.md`](./.claude/skills/doc-comments/SKILL.md).
+
+- Write for a contributor reading the code at HEAD, months later, with no access to this conversation, the PR, or the diff.
+- Never narrate change history ("now", "previously", "no longer") and never address the reviewer ("this correctly handles..."). State how the code works, not how it came to be or why the change is right.
+- Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.
+- `///` docs state the contract (behavior, invariants, panics); `//!` docs explain why the module exists and its terminology; `//` comments carry rationale only.
+- When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.
+- Exception: rustdoc inside `declare_lint_rule!` is end-user documentation for the website; these rules don't apply there.
+
 ## Available Resources
 
 ### Skills (Procedural Knowledge)
@@ -226,6 +237,7 @@ Located in `.claude/skills/`, these provide step-by-step workflows:
 
 - **biome-developer** - General development best practices and common gotchas
 - **changeset** - Creating and writing proper changesets
+- **doc-comments** - Writing comments and rustdoc addressed to developers
 - **eslint-migrate-options** - Implementing ESLint-to-Biome rule option migrators
 - **lint-rule-development** - Creating and testing lint rules
 - **formatter-development** - Implementing formatters

crates/biome_js_analyze/tests/specs/nursery/noMisusedPromises/invalidComplexCallbacks.ts

@@ -0,0 +1,27 @@
+/* should generate diagnostics */
+
+type Prefix<T> = [T];
+
+declare function consumeTuple(
+  ...args: [...Prefix<number>, () => void]
+): void;
+const tuplePrefix: Prefix<number> = [1];
+consumeTuple(...tuplePrefix, async () => {});
+
+type Recursive<T> = [...Recursive<T>];
+
+declare function consumeRecursive(
+  ...args: [...Recursive<number>, () => void]
+): void;
+consumeRecursive(async () => {});
+
+interface InterfaceConstructor {
+  new (callback: () => void): object;
+}
+declare const InterfaceConsumer: InterfaceConstructor;
+new InterfaceConsumer(async () => {});
+
+declare const ObjectConsumer: {
+  new (callback: () => void): object;
+};
+new ObjectConsumer(async () => {});

crates/biome_js_analyze/tests/specs/nursery/noMisusedPromises/invalidComplexCallbacks.ts.snap

@@ -0,0 +1,111 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: invalidComplexCallbacks.ts
+---
+# Input
+```ts
+/* should generate diagnostics */
+
+type Prefix<T> = [T];
+
+declare function consumeTuple(
+  ...args: [...Prefix<number>, () => void]
+): void;
+const tuplePrefix: Prefix<number> = [1];
+consumeTuple(...tuplePrefix, async () => {});
+
+type Recursive<T> = [...Recursive<T>];
+
+declare function consumeRecursive(
+  ...args: [...Recursive<number>, () => void]
+): void;
+consumeRecursive(async () => {});
+
+interface InterfaceConstructor {
+  new (callback: () => void): object;
+}
+declare const InterfaceConsumer: InterfaceConstructor;
+new InterfaceConsumer(async () => {});
+
+declare const ObjectConsumer: {
+  new (callback: () => void): object;
+};
+new ObjectConsumer(async () => {});
+
+```
+
+# Diagnostics
+```
+invalidComplexCallbacks.ts:9:30 lint/nursery/noMisusedPromises ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This function returns a Promise, but no return value was expected.
+  
+     7 │ ): void;
+     8 │ const tuplePrefix: Prefix<number> = [1];
+   > 9 │ consumeTuple(...tuplePrefix, async () => {});
+       │                              ^^^^^^^^^^^^^^
+    10 │ 
+    11 │ type Recursive<T> = [...Recursive<T>];
+  
+  i This may not have the desired result if you expect the Promise to be `await`-ed.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
+
+```
+invalidComplexCallbacks.ts:16:18 lint/nursery/noMisusedPromises ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This function returns a Promise, but no return value was expected.
+  
+    14 │   ...args: [...Recursive<number>, () => void]
+    15 │ ): void;
+  > 16 │ consumeRecursive(async () => {});
+       │                  ^^^^^^^^^^^^^^
+    17 │ 
+    18 │ interface InterfaceConstructor {
+  
+  i This may not have the desired result if you expect the Promise to be `await`-ed.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
+
+```
+invalidComplexCallbacks.ts:22:23 lint/nursery/noMisusedPromises ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This function returns a Promise, but no return value was expected.
+  
+    20 │ }
+    21 │ declare const InterfaceConsumer: InterfaceConstructor;
+  > 22 │ new InterfaceConsumer(async () => {});
+       │                       ^^^^^^^^^^^^^^
+    23 │ 
+    24 │ declare const ObjectConsumer: {
+  
+  i This may not have the desired result if you expect the Promise to be `await`-ed.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
+
+```
+invalidComplexCallbacks.ts:27:20 lint/nursery/noMisusedPromises ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This function returns a Promise, but no return value was expected.
+  
+    25 │   new (callback: () => void): object;
+    26 │ };
+  > 27 │ new ObjectConsumer(async () => {});
+       │                    ^^^^^^^^^^^^^^
+    28 │ 
+  
+  i This may not have the desired result if you expect the Promise to be `await`-ed.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```