feat: postHyphens option to control spacing after hyphens; fixes #972

gajus · Feb 3, 2023 · a143226 · a143226
1 parent 784e351
commit a143226
Show file tree

Hide file tree

Showing 5 changed files with 288 additions and 1 deletion.
diff --git a/.README/rules/check-line-alignment.md b/.README/rules/check-line-alignment.md
@@ -30,6 +30,7 @@ An object with any of the following keys set to an integer. Affects spacing:
 - `postTag` - after the tag (e.g., `* @param  `)
 - `postType` - after the type (e.g., `* @param {someType}   `)
 - `postName` - after the name (e.g., `* @param {someType} name   `)
+- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name -  A description`)
 
 If a spacing is not defined, it defaults to one.
 

diff --git a/README.md b/README.md
@@ -2047,6 +2047,7 @@ An object with any of the following keys set to an integer. Affects spacing:
 - `postTag` - after the tag (e.g., `* @param  `)
 - `postType` - after the type (e.g., `* @param {someType}   `)
 - `postName` - after the name (e.g., `* @param {someType} name   `)
+- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name -  A description`)
 
 If a spacing is not defined, it defaults to one.
 
@@ -2438,6 +2439,66 @@ const fn = ( lorem, sit ) => {}
 const fn = ( lorem, sit ) => {}
 // "jsdoc/check-line-alignment": ["error"|"warn", "always"]
 // Message: Expected JSDoc block lines to be aligned.
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem - Description.
+ * @param {int}    sit   -   Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "never"]
+// Message: Expected JSDoc block lines to not be aligned.
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem -  Description.
+ * @param {int}    sit   -   Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
+// Message: Expected JSDoc block lines to not be aligned.
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem - Description.
+ * @param {int} sit -  Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
+// Message: Expected JSDoc block lines to not be aligned.
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem - Description.
+ * @param {int}    sit   -  Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}]
+// Message: Expected JSDoc block lines to be aligned.
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem -  Description.
+ * @param {int}    sit   -   Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}]
+// Message: Expected JSDoc block lines to be aligned.
+
+/**
+ * Function description.
+ *
+ * @param   {string} lorem -  Description.
+ * @param {int} sit -  Description multi words.
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
+// Message: Expected JSDoc block lines to not be aligned.
 ````
 
 The following patterns are not considered problems:

diff --git a/src/alignTransform.js b/src/alignTransform.js
@@ -233,6 +233,12 @@ const alignTransform = ({
       };
     }
 
+    const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
+    const hyphenSpacing = /^\s*-\s*/u;
+    tokens.description = tokens.description.replace(
+      hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '),
+    );
+
     // Not align.
     if (!shouldAlign(tags, index, source)) {
       return {

diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js
@@ -64,6 +64,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
     });
   };
 
+  const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
+  const exactHyphenSpacing = new RegExp(`^\\s*-\\s{${postHyphenSpacing},${postHyphenSpacing}}(?!\\s)`, 'u');
+  const hasNoHyphen = !(/^\s*-/u).test(tokens.description);
+  const hasExactHyphenSpacing = exactHyphenSpacing.test(
+    tokens.description,
+  );
+
   // If checking alignment on multiple lines, need to check other `source`
   //   items
   // Go through `post*` spacing properties and exit to indicate problem if
@@ -82,7 +89,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
       // 2. There is a (single) space, no immediate content, and yet another
       //     space is found subsequently (not separated by intervening content)
       spacerPropVal && !contentPropVal && followedBySpace(idx);
-  });
+  }) && (hasNoHyphen || hasExactHyphenSpacing);
   if (ok) {
     return;
   }
@@ -108,6 +115,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
       }
     }
 
+    if (!hasExactHyphenSpacing) {
+      const hyphenSpacing = /^\s*-\s*/u;
+      tokens.description = tokens.description.replace(
+        hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '),
+      );
+    }
+
     utils.setTag(tag, tokens);
   };
 
@@ -212,6 +226,9 @@ export default iterateJsdoc(({
               postDelimiter: {
                 type: 'integer',
               },
+              postHyphen: {
+                type: 'integer',
+              },
               postName: {
                 type: 'integer',
               },

diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js
@@ -1157,6 +1157,208 @@ export default {
         const fn = ( lorem, sit ) => {}
       `,
     },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem - Description.
+         * @param {int}    sit   -   Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Expected JSDoc block lines to not be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'never',
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem - Description.
+         * @param {int} sit - Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int}    sit   -   Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Expected JSDoc block lines to not be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'never',
+        {
+          customSpacings: {
+            postHyphen: 2,
+          },
+        },
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int} sit -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem - Description.
+         * @param {int} sit -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'Expected JSDoc block lines to not be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'never',
+        {
+          customSpacings: {
+            postHyphen: 2,
+          },
+        },
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int} sit -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem - Description.
+         * @param {int}    sit   -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Expected JSDoc block lines to be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'always', {
+          customSpacings: {
+            postHyphen: 2,
+          },
+        },
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int}    sit   -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int}    sit   -   Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Expected JSDoc block lines to be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'always', {
+          customSpacings: {
+            postHyphen: 2,
+          },
+        },
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int}    sit   -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param   {string} lorem -  Description.
+         * @param {int} sit -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'Expected JSDoc block lines to not be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: [
+        'never', {
+          customSpacings: {
+            postHyphen: 2,
+          },
+        },
+      ],
+      output: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem -  Description.
+         * @param {int} sit -  Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+    },
   ],
   valid: [
     {