From 8b5b7f709c416ee3bc1acb75fd23b0fb055d69fa Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Sat, 12 Oct 2024 06:14:49 +0800
Subject: [PATCH] fix(`require-hyphen-before-param-description`): inject hyphen
 at proper place with multiline type

---
 ...require-hyphen-before-param-description.md |  9 +++
 .../requireHyphenBeforeParamDescription.js    | 57 ++++++++++---------
 .../requireHyphenBeforeParamDescription.js    | 26 +++++++++
 3 files changed, 64 insertions(+), 28 deletions(-)

diff --git a/docs/rules/require-hyphen-before-param-description.md b/docs/rules/require-hyphen-before-param-description.md
index 67c906116..6022aa17c 100644
--- a/docs/rules/require-hyphen-before-param-description.md
+++ b/docs/rules/require-hyphen-before-param-description.md
@@ -193,6 +193,15 @@ function quux () {
  */
 // "jsdoc/require-hyphen-before-param-description": ["error"|"warn", "always",{"tags":{"*":"never","property":"always"}}]
 // Message: There must be no hyphen before @returns description.
+
+/**
+ * @param {(
+ *  | string
+ *  | number
+ * )} input The input value
+ */
+function test(input) {}
+// Message: There must be a hyphen before @param description.
 ````
 
 
diff --git a/src/rules/requireHyphenBeforeParamDescription.js b/src/rules/requireHyphenBeforeParamDescription.js
index 791e842fa..327e88576 100644
--- a/src/rules/requireHyphenBeforeParamDescription.js
+++ b/src/rules/requireHyphenBeforeParamDescription.js
@@ -33,38 +33,39 @@ export default iterateJsdoc(({
     }
 
     const startsWithHyphen = (/^\s*-/u).test(desc);
-    if (always) {
-      if (!startsWithHyphen) {
-        report(`There must be a hyphen before @${targetTagName} description.`, (fixer) => {
-          const lineIndex = /** @type {import('../iterateJsdoc.js').Integer} */ (
-            jsdocTag.line
-          );
-          const sourceLines = sourceCode.getText(jsdocNode).split('\n');
-
-          // Get start index of description, accounting for multi-line descriptions
-          const description = desc.split('\n')[0];
-          const descriptionIndex = sourceLines[lineIndex].lastIndexOf(description);
+    let lines = 0;
+    for (const {
+      tokens,
+    } of jsdocTag.source) {
+      if (tokens.description) {
+        break;
+      }
 
-          const replacementLine = sourceLines[lineIndex]
-            .slice(0, descriptionIndex) + '- ' + description;
-          sourceLines.splice(lineIndex, 1, replacementLine);
-          const replacement = sourceLines.join('\n');
+      lines++;
+    }
 
-          return fixer.replaceText(jsdocNode, replacement);
-        }, jsdocTag);
+    if (always) {
+      if (!startsWithHyphen) {
+        utils.reportJSDoc(
+          `There must be a hyphen before @${targetTagName} description.`,
+          {
+            line: jsdocTag.source[0].number + lines,
+          },
+          () => {
+            for (const {
+              tokens,
+            } of jsdocTag.source) {
+              if (tokens.description) {
+                tokens.description = tokens.description.replace(
+                  /^(\s*)/u, '$1- ',
+                );
+                break;
+              }
+            }
+          }
+        );
       }
     } else if (startsWithHyphen) {
-      let lines = 0;
-      for (const {
-        tokens,
-      } of jsdocTag.source) {
-        if (tokens.description) {
-          break;
-        }
-
-        lines++;
-      }
-
       utils.reportJSDoc(
         `There must be no hyphen before @${targetTagName} description.`,
         {
diff --git a/test/rules/assertions/requireHyphenBeforeParamDescription.js b/test/rules/assertions/requireHyphenBeforeParamDescription.js
index 919b6b554..9b2ab23cc 100644
--- a/test/rules/assertions/requireHyphenBeforeParamDescription.js
+++ b/test/rules/assertions/requireHyphenBeforeParamDescription.js
@@ -447,6 +447,32 @@ export default {
        */
       `,
     },
+    {
+      code: `
+        /**
+         * @param {(
+         *  | string
+         *  | number
+         * )} input The input value
+         */
+        function test(input) {}
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'There must be a hyphen before @param description.',
+        },
+      ],
+      output: `
+        /**
+         * @param {(
+         *  | string
+         *  | number
+         * )} input - The input value
+         */
+        function test(input) {}
+      `,
+    },
   ],
   valid: [
     {