fix Feat: Expand **kwargs with field names on hover when **kwargs is typed with Unpack (i.e. **kwargs: Unpack[T]) #758 (#1514)

Summary:
fix #758

Hover output now expands **kwargs typed with typing.Unpack[TypedDict] into their constituent keyword-only parameters so people hovering a call see the real argument names.

Implemented the expansion by letting HoverValue accept a pre-computed display string, formatting callables via transaction.ad_hoc_solve, and inserting typed-dict fields as synthetic Param::KwOnly entries before the original **kwargs.

Pull Request resolved: #1514

Reviewed By: kinto0

Differential Revision: D86638374

Pulled By: yangdanny97

fbshipit-source-id: a41c8debf417727fd3f297671ec789ff3ae2af0a

Author: asukaminato0721

crates/pyrefly_types/src/types.rs

@@ -1162,6 +1162,44 @@ impl Type {
         }
     }
 
+    /// Apply `f` to this type if it is a callable. Note that we do *not* recurse into the type to
+    /// find nested callable types.
+    pub fn visit_toplevel_callable_mut<'a>(&'a mut self, mut f: impl FnMut(&'a mut Callable)) {
+        match self {
+            Type::Callable(callable) => f(callable),
+            Type::Forall(box Forall {
+                body: Forallable::Callable(callable),
+                ..
+            }) => f(callable),
+            Type::Function(box func)
+            | Type::Forall(box Forall {
+                body: Forallable::Function(func),
+                ..
+            })
+            | Type::BoundMethod(box BoundMethod {
+                func: BoundMethodType::Function(func),
+                ..
+            })
+            | Type::BoundMethod(box BoundMethod {
+                func: BoundMethodType::Forall(Forall { body: func, .. }),
+                ..
+            }) => f(&mut func.signature),
+            Type::Overload(overload)
+            | Type::BoundMethod(box BoundMethod {
+                func: BoundMethodType::Overload(overload),
+                ..
+            }) => {
+                for x in overload.signatures.iter_mut() {
+                    match x {
+                        OverloadType::Function(function) => f(&mut function.signature),
+                        OverloadType::Forall(forall) => f(&mut forall.body.signature),
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
     fn is_toplevel_callable(&self) -> bool {
         let mut is_callable = false;
         self.visit_toplevel_callable(&mut |_| is_callable = true);

pyrefly/lib/lsp/wasm/hover.rs

@@ -15,15 +15,23 @@ use pyrefly_python::docstring::Docstring;
 use pyrefly_python::ignore::Ignore;
 use pyrefly_python::ignore::find_comment_start_in_line;
 use pyrefly_python::symbol_kind::SymbolKind;
+use pyrefly_types::callable::Callable;
+use pyrefly_types::callable::Param;
+use pyrefly_types::callable::ParamList;
+use pyrefly_types::callable::Params;
+use pyrefly_types::callable::Required;
 use pyrefly_types::types::Type;
 use pyrefly_util::lined_buffer::LineNumber;
+use ruff_python_ast::name::Name;
 use ruff_text_size::TextSize;
 
+use crate::alt::answers_solver::AnswersSolver;
 use crate::error::error::Error;
 use crate::lsp::module_helpers::collect_symbol_def_paths;
 use crate::state::lsp::FindDefinitionItemWithDocstring;
 use crate::state::lsp::FindPreference;
 use crate::state::state::Transaction;
+use crate::state::state::TransactionHandle;
 
 /// Gets all suppressed errors that overlap with the given line.
 ///
@@ -95,6 +103,7 @@ pub struct HoverValue {
     pub name: Option<String>,
     pub type_: Type,
     pub docstring: Option<Docstring>,
+    pub display: Option<String>,
 }
 
 impl HoverValue {
@@ -158,6 +167,10 @@ impl HoverValue {
             .map_or("".to_owned(), |s| format!("{s}: "));
         let symbol_def_formatted =
             HoverValue::format_symbol_def_locations(&self.type_).unwrap_or("".to_owned());
+        let type_display = self
+            .display
+            .clone()
+            .unwrap_or_else(|| self.type_.as_hover_string());
 
         Hover {
             contents: HoverContents::Markup(MarkupContent {
@@ -166,7 +179,7 @@ impl HoverValue {
                     "```python\n{}{}{}\n```{}{}",
                     kind_formatted,
                     name_formatted,
-                    self.type_.as_hover_string(),
+                    type_display,
                     docstring_formatted,
                     symbol_def_formatted
                 ),
@@ -176,6 +189,49 @@ impl HoverValue {
     }
 }
 
+fn collect_typed_dict_fields_for_hover<'a>(
+    solver: &AnswersSolver<TransactionHandle<'a>>,
+    ty: &Type,
+) -> Option<Vec<(Name, Type, Required)>> {
+    match ty {
+        Type::Unpack(inner) => match inner.as_ref() {
+            Type::TypedDict(typed_dict) => {
+                let fields = solver.type_order().typed_dict_kw_param_info(typed_dict);
+                if fields.is_empty() {
+                    None
+                } else {
+                    Some(fields)
+                }
+            }
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
+fn expand_callable_kwargs_for_hover<'a>(
+    solver: &AnswersSolver<TransactionHandle<'a>>,
+    callable: &mut Callable,
+) {
+    if let Params::List(param_list) = &mut callable.params {
+        let mut expanded = Vec::with_capacity(param_list.len());
+        let mut changed = false;
+        for param in param_list.items() {
+            if let Param::Kwargs(_, ty) = param
+                && let Some(fields) = collect_typed_dict_fields_for_hover(solver, ty)
+            {
+                changed = true;
+                for (field_name, field_type, required) in fields {
+                    expanded.push(Param::KwOnly(field_name, field_type, required));
+                }
+            }
+            expanded.push(param.clone());
+        }
+        if changed {
+            *param_list = ParamList::new(expanded);
+        }
+    }
+}
 pub fn get_hover(
     transaction: &Transaction<'_>,
     handle: &Handle,
@@ -213,6 +269,15 @@ pub fn get_hover(
 
     // Otherwise, fall through to the existing type hover logic
     let type_ = transaction.get_type_at(handle, position)?;
+    let type_display = transaction.ad_hoc_solve(handle, {
+        let mut cloned = type_.clone();
+        move |solver| {
+            // If the type is a callable, rewrite the signature to expand TypedDict-based
+            // `**kwargs` entries, ensuring hover text shows the actual keyword names users can pass.
+            cloned.visit_toplevel_callable_mut(|c| expand_callable_kwargs_for_hover(&solver, c));
+            cloned.as_hover_string()
+        }
+    });
     let (kind, name, docstring_range, module) = if let Some(FindDefinitionItemWithDocstring {
         metadata,
         definition_range: definition_location,
@@ -253,6 +318,7 @@ pub fn get_hover(
             name,
             type_,
             docstring,
+            display: type_display,
         }
         .format(),
     )

pyrefly/lib/test/lsp/hover.rs

@@ -88,6 +88,43 @@ from lib import foo_renamed
     );
 }
 
+#[test]
+fn hover_shows_unpacked_kwargs_fields() {
+    let code = r#"
+from typing import TypedDict, Unpack
+
+class Payload(TypedDict):
+    foo: int
+    bar: str
+    baz: bool | None
+
+def takes(**kwargs: Unpack[Payload]) -> None:
+    ...
+
+takes(foo=1, bar="x", baz=None)
+#^
+"#;
+    let report = get_batched_lsp_operations_report(&[("main", code)], get_test_report);
+    assert_eq!(
+        r#"
+# main.py
+12 | takes(foo=1, bar="x", baz=None)
+      ^
+```python
+(function) takes: def takes(
+    *,
+    foo: int,
+    bar: str,
+    baz: bool | None,
+    **kwargs: Unpack[TypedDict[Payload]]
+) -> None: ...
+```
+"#
+        .trim(),
+        report.trim(),
+    );
+}
+
 #[test]
 fn hover_over_inline_ignore_comment() {
     let code = r#"