feat(linter/jsdoc): Add missing options to require-param-type rule (#23418)

Closes #23371

### AI usage disclosure

I used Claude Code to generate this PR description.

### Summary

Adds configuration support and a fixer to the `jsdoc/require-param-type`
rule, matching `eslint-plugin-jsdoc`.

**New options:**
- `setDefaultDestructuredRootType` (default `false`). When `true`,
auto-fixes a missing type on a destructured root `@param`.
- `defaultDestructuredRootType` (default `"object"`). The type string
used by that fix.

---------

Co-authored-by: Kapobajza <kapobajza@gmail.com>
Co-authored-by: Cameron Clark <cameron.clark@hey.com>

Author: 3 people

apps/oxlint/src-js/package/config.generated.ts

@@ -965,7 +965,7 @@ export interface DummyRuleMap {
   "jsdoc/require-param"?: DummyRule;
   "jsdoc/require-param-description"?: RuleNoConfig;
   "jsdoc/require-param-name"?: RuleNoConfig;
-  "jsdoc/require-param-type"?: RuleNoConfig;
+  "jsdoc/require-param-type"?: RuleNoConfig | [AllowWarnDeny, RequireParamTypeConfig];
   "jsdoc/require-property"?: RuleNoConfig;
   "jsdoc/require-property-description"?: RuleNoConfig;
   "jsdoc/require-property-name"?: RuleNoConfig;
@@ -2375,6 +2375,16 @@ export interface NoDefaultsConfig {
    */
   noOptionalParamNames?: boolean;
 }
+export interface RequireParamTypeConfig {
+  /**
+   * The type string to set by default for destructured roots. Defaults to "object".
+   */
+  defaultDestructuredRootType?: string;
+  /**
+   * Whether to set a default destructured root type. For example, you may wish to avoid manually having to set the type for a `@param` corresponding to a destructured root object as it is always going to be an object. Uses `defaultDestructuredRootType` for the type string. Defaults to `false`.
+   */
+  setDefaultDestructuredRootType?: boolean;
+}
 export interface RequireReturnsConfig {
   /**
    * Whether to check constructor methods.

crates/oxc_linter/src/rules/jsdoc/require_param_type.rs

@@ -1,12 +1,16 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+
 use oxc_ast::AstKind;
 use oxc_diagnostics::OxcDiagnostic;
 use oxc_macros::declare_oxc_lint;
 use oxc_span::Span;
+use oxc_str::CompactStr;
 
 use crate::{
     AstNode,
     context::LintContext,
-    rule::Rule,
+    rule::{DefaultRuleConfig, Rule},
     utils::{
         ParamKind, collect_params, get_function_nearest_jsdoc_node, should_ignore_as_internal,
         should_ignore_as_private,
@@ -19,8 +23,32 @@ fn missing_type_diagnostic(span: Span) -> OxcDiagnostic {
         .with_label(span)
 }
 
+fn missing_root_type_diagnostic(span: Span, default_type: &CompactStr) -> OxcDiagnostic {
+    OxcDiagnostic::warn("Missing root type for @param.")
+        .with_help(format!("Add {{{default_type}}} to `@param` tag."))
+        .with_label(span)
+}
+
+#[derive(Debug, Clone, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
+pub struct RequireParamTypeConfig {
+    /// The type string to set by default for destructured roots. Defaults to "object".
+    default_destructured_root_type: CompactStr,
+    /// Whether to set a default destructured root type. For example, you may wish to avoid manually having to set the type for a `@param` corresponding to a destructured root object as it is always going to be an object. Uses `defaultDestructuredRootType` for the type string. Defaults to `false`.
+    set_default_destructured_root_type: bool,
+}
+
+impl Default for RequireParamTypeConfig {
+    fn default() -> Self {
+        Self {
+            default_destructured_root_type: CompactStr::from("object"),
+            set_default_destructured_root_type: false,
+        }
+    }
+}
+
 #[derive(Debug, Default, Clone)]
-pub struct RequireParamType;
+pub struct RequireParamType(Box<RequireParamTypeConfig>);
 
 declare_oxc_lint!(
     /// ### What it does
@@ -48,11 +76,17 @@ declare_oxc_lint!(
     jsdoc,
     pedantic,
     pending,
+    config = RequireParamTypeConfig,
     version = "0.4.4",
     short_description = "Requires that each `@param` tag has a type value (within curly brackets).",
 );
 
 impl Rule for RequireParamType {
+    fn from_configuration(value: serde_json::Value) -> Result<Self, serde_json::error::Error> {
+        serde_json::from_value::<DefaultRuleConfig<RequireParamTypeConfig>>(value)
+            .map(|config| Self(Box::new(config.into_inner())))
+    }
+
     fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
         // Collected targets from `FormalParameters`
         let params_to_check = match node.kind() {
@@ -100,7 +134,20 @@ impl Rule for RequireParamType {
                     continue;
                 }
 
-                ctx.diagnostic(missing_type_diagnostic(tag.kind.span));
+                let is_destructured_root =
+                    matches!(params_to_check.get(root_count - 1), Some(ParamKind::Nested(_)));
+
+                if self.0.set_default_destructured_root_type
+                    && is_destructured_root
+                    && name_part.is_some()
+                {
+                    ctx.diagnostic(missing_root_type_diagnostic(
+                        tag.kind.span,
+                        &self.0.default_destructured_root_type,
+                    ));
+                } else {
+                    ctx.diagnostic(missing_type_diagnostic(tag.kind.span));
+                }
             }
         }
     }
@@ -238,9 +285,7 @@ fn test() {
 
 			          }
 			      ",
-            // TODO: support configurations for this rule
-            // Some(serde_json::json!([ { "setDefaultDestructuredRootType": true } ])),
-            None,
+            Some(serde_json::json!([ { "setDefaultDestructuredRootType": true } ])),
             None,
         ),
         (
@@ -254,9 +299,7 @@ fn test() {
 
 			          }
 			      ",
-            // TODO: support configurations for this rule
-            // Some(serde_json::json!([ { "setDefaultDestructuredRootType": false } ])),
-            None,
+            Some(serde_json::json!([ { "setDefaultDestructuredRootType": false } ])),
             None,
         ),
     ];

crates/oxc_linter/src/snapshots/jsdoc_require_param_type.snap

@@ -29,14 +29,14 @@ source: crates/oxc_linter/src/tester.rs
    ╰────
   help: Add {type} to `@param` tag.
 
-  ⚠ jsdoc(require-param-type): Missing JSDoc `@param` type.
+  ⚠ jsdoc(require-param-type): Missing root type for @param.
    ╭─[require_param_type.tsx:4:17]
  3 │                        * @param {number} foo
  4 │                        * @param root
    ·                          ──────
  5 │                        * @param {boolean} baz
    ╰────
-  help: Add {type} to `@param` tag.
+  help: Add {object} to `@param` tag.
 
   ⚠ jsdoc(require-param-type): Missing JSDoc `@param` type.
    ╭─[require_param_type.tsx:4:17]

npm/oxlint/configuration_schema.json

@@ -3500,7 +3500,24 @@
           "$ref": "#/definitions/RuleNoConfig"
         },
         "jsdoc/require-param-type": {
-          "$ref": "#/definitions/RuleNoConfig"
+          "anyOf": [
+            {
+              "$ref": "#/definitions/RuleNoConfig"
+            },
+            {
+              "type": "array",
+              "items": [
+                {
+                  "$ref": "#/definitions/AllowWarnDeny"
+                },
+                {
+                  "$ref": "#/definitions/RequireParamTypeConfig"
+                }
+              ],
+              "maxItems": 2,
+              "minItems": 2
+            }
+          ]
         },
         "jsdoc/require-property": {
           "$ref": "#/definitions/RuleNoConfig"
@@ -16919,6 +16936,24 @@
       },
       "additionalProperties": false
     },
+    "RequireParamTypeConfig": {
+      "type": "object",
+      "properties": {
+        "defaultDestructuredRootType": {
+          "description": "The type string to set by default for destructured roots. Defaults to \"object\".",
+          "default": "object",
+          "type": "string",
+          "markdownDescription": "The type string to set by default for destructured roots. Defaults to \"object\"."
+        },
+        "setDefaultDestructuredRootType": {
+          "description": "Whether to set a default destructured root type. For example, you may wish to avoid manually having to set the type for a `@param` corresponding to a destructured root object as it is always going to be an object. Uses `defaultDestructuredRootType` for the type string. Defaults to `false`.",
+          "default": false,
+          "type": "boolean",
+          "markdownDescription": "Whether to set a default destructured root type. For example, you may wish to avoid manually having to set the type for a `@param` corresponding to a destructured root object as it is always going to be an object. Uses `defaultDestructuredRootType` for the type string. Defaults to `false`."
+        }
+      },
+      "additionalProperties": false
+    },
     "RequireReturnsConfig": {
       "type": "object",
       "properties": {