From 41af30f2dd1977e287b7634d29fd8bba7ddaca23 Mon Sep 17 00:00:00 2001
From: Yuji Sugiura <y.sugiura.0316@gmail.com>
Date: Wed, 29 May 2024 10:05:32 +0900
Subject: [PATCH] feat(linter/jsdoc): Implement require-returns-type rule

---
 crates/oxc_linter/src/rules.rs                |   2 +
 .../src/rules/jsdoc/require_returns_type.rs   | 160 ++++++++++++++++++
 .../src/snapshots/require_returns_type.snap   |  30 ++++
 3 files changed, 192 insertions(+)
 create mode 100644 crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs
 create mode 100644 crates/oxc_linter/src/snapshots/require_returns_type.snap

diff --git a/crates/oxc_linter/src/rules.rs b/crates/oxc_linter/src/rules.rs
index 862765aa3a9b2..349abbe52a4ec 100644
--- a/crates/oxc_linter/src/rules.rs
+++ b/crates/oxc_linter/src/rules.rs
@@ -394,6 +394,7 @@ mod jsdoc {
     pub mod require_property_type;
     pub mod require_returns;
     pub mod require_returns_description;
+    pub mod require_returns_type;
     pub mod require_yields;
 }
 
@@ -758,6 +759,7 @@ oxc_macros::declare_all_lint_rules! {
     jsdoc::require_property_description,
     jsdoc::require_returns,
     jsdoc::require_returns_description,
+    jsdoc::require_returns_type,
     jsdoc::require_yields,
     tree_shaking::no_side_effects_in_initialization,
 }
diff --git a/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs b/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs
new file mode 100644
index 0000000000000..c82f2f78dee73
--- /dev/null
+++ b/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs
@@ -0,0 +1,160 @@
+use oxc_diagnostics::OxcDiagnostic;
+use oxc_macros::declare_oxc_lint;
+use oxc_span::Span;
+
+use crate::{
+    ast_util::is_function_node,
+    context::LintContext,
+    rule::Rule,
+    utils::{get_function_nearest_jsdoc_node, should_ignore_as_internal, should_ignore_as_private},
+    AstNode,
+};
+
+fn missing_type_diagnostic(span0: Span) -> OxcDiagnostic {
+    OxcDiagnostic::warn("eslint-plugin-jsdoc(require-returns-type): Missing JSDoc `@returns` type.")
+        .with_help("Add {type} to `@returns` tag.")
+        .with_labels([span0.into()])
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct RequireReturnsType;
+
+declare_oxc_lint!(
+    /// ### What it does
+    /// Requires that `@returns` tag has a type value (in curly brackets).
+    ///
+    /// ### Why is this bad?
+    /// A `@returns` tag should have a type value.
+    ///
+    /// ### Example
+    /// ```javascript
+    /// // Passing
+    /// /** @returns {string} */
+    /// function quux (foo) {}
+    ///
+    /// // Failing
+    /// /** @returns */
+    /// function quux (foo) {}
+    /// ```
+    RequireReturnsType,
+    pedantic,
+);
+
+impl Rule for RequireReturnsType {
+    fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
+        if !is_function_node(node) {
+            return;
+        }
+
+        // If no JSDoc is found, skip
+        let Some(jsdocs) = get_function_nearest_jsdoc_node(node, ctx)
+            .and_then(|node| ctx.jsdoc().get_all_by_node(node))
+        else {
+            return;
+        };
+
+        let settings = &ctx.settings().jsdoc;
+        let resolved_returns_tag_name = settings.resolve_tag_name("returns");
+        for jsdoc in jsdocs
+            .iter()
+            .filter(|jsdoc| !should_ignore_as_internal(jsdoc, settings))
+            .filter(|jsdoc| !should_ignore_as_private(jsdoc, settings))
+        {
+            for tag in jsdoc.tags() {
+                if tag.kind.parsed() != resolved_returns_tag_name {
+                    continue;
+                }
+
+                // If type exists, skip
+                if let (Some(_), _) = tag.type_comment() {
+                    continue;
+                };
+
+                ctx.diagnostic(missing_type_diagnostic(tag.kind.span));
+            }
+        }
+    }
+}
+
+#[test]
+fn test() {
+    use crate::tester::Tester;
+
+    let pass = vec![
+        (
+            "
+			          /**
+			           * @returns {number}
+			           */
+			          function quux () {
+			
+			          }
+			      ",
+            None,
+            None,
+        ),
+        (
+            "
+			          /**
+			           * @function
+			           * @returns Foo.
+			           */
+			      ",
+            None,
+            None,
+        ),
+        (
+            "
+			          /**
+			           * @callback
+			           * @returns Foo.
+			           */
+			      ",
+            None,
+            None,
+        ),
+    ];
+
+    let fail = vec![
+        (
+            "
+			          /**
+			           * @returns
+			           */
+			          function quux () {
+			
+			          }
+			      ",
+            None,
+            None,
+        ),
+        (
+            "
+			          /**
+			           * @returns Foo.
+			           */
+			          function quux () {
+			
+			          }
+			      ",
+            None,
+            None,
+        ),
+        (
+            "
+			          /**
+			           * @return Foo.
+			           */
+			          function quux () {
+			
+			          }
+			      ",
+            None,
+            Some(serde_json::json!({ "settings": { "jsdoc": {
+                    "tagNamePreference": { "returns": "return", },
+                }, } })),
+        ),
+    ];
+
+    Tester::new(RequireReturnsType::NAME, pass, fail).test_and_snapshot();
+}
diff --git a/crates/oxc_linter/src/snapshots/require_returns_type.snap b/crates/oxc_linter/src/snapshots/require_returns_type.snap
new file mode 100644
index 0000000000000..ff3deaf4bef77
--- /dev/null
+++ b/crates/oxc_linter/src/snapshots/require_returns_type.snap
@@ -0,0 +1,30 @@
+---
+source: crates/oxc_linter/src/tester.rs
+expression: require_returns_type
+---
+  ⚠ eslint-plugin-jsdoc(require-returns-type): Missing JSDoc `@returns` type.
+   ╭─[require_returns_type.tsx:3:17]
+ 2 │                       /**
+ 3 │                        * @returns
+   ·                          ────────
+ 4 │                        */
+   ╰────
+  help: Add {type} to `@returns` tag.
+
+  ⚠ eslint-plugin-jsdoc(require-returns-type): Missing JSDoc `@returns` type.
+   ╭─[require_returns_type.tsx:3:17]
+ 2 │                       /**
+ 3 │                        * @returns Foo.
+   ·                          ────────
+ 4 │                        */
+   ╰────
+  help: Add {type} to `@returns` tag.
+
+  ⚠ eslint-plugin-jsdoc(require-returns-type): Missing JSDoc `@returns` type.
+   ╭─[require_returns_type.tsx:3:17]
+ 2 │                       /**
+ 3 │                        * @return Foo.
+   ·                          ───────
+ 4 │                        */
+   ╰────
+  help: Add {type} to `@returns` tag.