[ty] Add ParamSpec context to missing argument diagnostics

When a ParamSpec callable is called without the required `*args` or
`**kwargs`, the error message now includes a sub-diagnostic explaining
why these arguments are required. This addresses reviewer feedback
from PR #22820 about making it clearer why these parameters are
required in some cases and not in others.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: charliermarsh

crates/ty_python_semantic/resources/mdtest/diagnostics/missing_argument_paramspec.md

@@ -0,0 +1,22 @@
+# Missing argument for ParamSpec
+
+<!-- snapshot-diagnostics -->
+
+For `ParamSpec` callables, both `*args` and `**kwargs` are required since the underlying callable's
+signature is unknown. We add a sub-diagnostic explaining why these parameters are required.
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+```py
+from typing import Callable
+
+def decorator[**P](func: Callable[P, int]) -> Callable[P, None]:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+        func()  # error: [missing-argument]
+        func(*args)  # error: [missing-argument]
+        func(**kwargs)  # error: [missing-argument]
+    return wrapper
+```

crates/ty_python_semantic/resources/mdtest/snapshots/missing_argument_par…_-_Missing_argument_for…_(b632d61c1d75f9fb).snap

@@ -0,0 +1,73 @@
+---
+source: crates/ty_test/src/lib.rs
+expression: snapshot
+---
+
+---
+mdtest name: missing_argument_paramspec.md - Missing argument for ParamSpec
+mdtest path: crates/ty_python_semantic/resources/mdtest/diagnostics/missing_argument_paramspec.md
+---
+
+# Python source files
+
+## mdtest_snippet.py
+
+```
+1 | from typing import Callable
+2 | 
+3 | def decorator[**P](func: Callable[P, int]) -> Callable[P, None]:
+4 |     def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+5 |         func()  # error: [missing-argument]
+6 |         func(*args)  # error: [missing-argument]
+7 |         func(**kwargs)  # error: [missing-argument]
+8 |     return wrapper
+```
+
+# Diagnostics
+
+```
+error[missing-argument]: No arguments provided for required parameters `*args`, `**kwargs`
+ --> src/mdtest_snippet.py:5:9
+  |
+3 | def decorator[**P](func: Callable[P, int]) -> Callable[P, None]:
+4 |     def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+5 |         func()  # error: [missing-argument]
+  |         ^^^^^^
+6 |         func(*args)  # error: [missing-argument]
+7 |         func(**kwargs)  # error: [missing-argument]
+  |
+info: These arguments are required because `ParamSpec` `P` could represent any set of parameters at runtime
+info: rule `missing-argument` is enabled by default
+
+```
+
+```
+error[missing-argument]: No argument provided for required parameter `**kwargs`
+ --> src/mdtest_snippet.py:6:9
+  |
+4 |     def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+5 |         func()  # error: [missing-argument]
+6 |         func(*args)  # error: [missing-argument]
+  |         ^^^^^^^^^^^
+7 |         func(**kwargs)  # error: [missing-argument]
+8 |     return wrapper
+  |
+info: These arguments are required because `ParamSpec` `P` could represent any set of parameters at runtime
+info: rule `missing-argument` is enabled by default
+
+```
+
+```
+error[missing-argument]: No argument provided for required parameter `*args`
+ --> src/mdtest_snippet.py:7:9
+  |
+5 |         func()  # error: [missing-argument]
+6 |         func(*args)  # error: [missing-argument]
+7 |         func(**kwargs)  # error: [missing-argument]
+  |         ^^^^^^^^^^^^^^
+8 |     return wrapper
+  |
+info: These arguments are required because `ParamSpec` `P` could represent any set of parameters at runtime
+info: rule `missing-argument` is enabled by default
+
+```

crates/ty_python_semantic/src/types/call/bind.rs

@@ -3045,6 +3045,7 @@ impl<'a, 'db> ArgumentMatcher<'a, 'db> {
         if !missing.is_empty() {
             self.errors.push(BindingError::MissingArguments {
                 parameters: ParameterContexts(missing),
+                paramspec: self.parameters.as_paramspec(),
             });
         }
 
@@ -4215,6 +4216,10 @@ pub(crate) enum BindingError<'db> {
     /// One or more required parameters (that is, with no default) is not supplied by any argument.
     MissingArguments {
         parameters: ParameterContexts,
+        /// If the missing arguments are for a `ParamSpec`, this contains the `ParamSpec` typevar.
+        /// This is used to provide more informative error messages explaining why `*args` and
+        /// `**kwargs` are required.
+        paramspec: Option<BoundTypeVarInstance<'db>>,
     },
     /// A call argument can't be matched to any parameter.
     UnknownArgument {
@@ -4554,7 +4559,10 @@ impl<'db> BindingError<'db> {
                 }
             }
 
-            Self::MissingArguments { parameters } => {
+            Self::MissingArguments {
+                parameters,
+                paramspec,
+            } => {
                 if let Some(builder) = context.report_lint(&MISSING_ARGUMENT, node) {
                     let s = if parameters.0.len() == 1 { "" } else { "s" };
                     let mut diag = builder.into_diagnostic(format_args!(
@@ -4581,6 +4589,16 @@ impl<'db> BindingError<'db> {
                             diag.sub(sub);
                         }
                     }
+                    if let Some(paramspec) = paramspec {
+                        let paramspec_name = paramspec.name(context.db());
+                        diag.sub(SubDiagnostic::new(
+                            SubDiagnosticSeverity::Info,
+                            format_args!(
+                                "These arguments are required because `ParamSpec` `{paramspec_name}` \
+                                 could represent any set of parameters at runtime"
+                            ),
+                        ));
+                    }
                 }
             }