Add preserveMainDescriptionPostDelimiter option (gajus#731)

feat(`check-line-alignment`): add `preserveMainDescriptionPostDelimiter` option to preserve left-hand side spacings in the main description when using the `always` option.

Co-authored-by: Renatho De Carli Rosa <[email protected]>

Author: renatho

src/alignTransform.js

@@ -58,7 +58,7 @@ const space = (len) => {
   return ''.padStart(len, ' ');
 };
 
-const alignTransform = (tags, indent) => {
+const alignTransform = (tags, indent, preserveMainDescriptionPostDelimiter) => {
   let intoTags = false;
   let width;
 
@@ -145,7 +145,11 @@ const alignTransform = (tags, indent) => {
     /* eslint-enable */
 
     if (!intoTags) {
-      tokens.postDelimiter = tokens.description === '' ? '' : ' ';
+      if (tokens.description === '') {
+        tokens.postDelimiter = '';
+      } else if (!preserveMainDescriptionPostDelimiter) {
+        tokens.postDelimiter = ' ';
+      }
 
       return {
         ...line,

src/rules/checkLineAlignment.js

@@ -100,11 +100,12 @@ const checkAlignment = ({
   indent,
   jsdoc,
   jsdocNode,
+  preserveMainDescriptionPostDelimiter,
   report,
   tags,
   utils,
 }) => {
-  const transform = commentFlow(alignTransform(tags, indent));
+  const transform = commentFlow(alignTransform(tags, indent, preserveMainDescriptionPostDelimiter));
   const transformedJsdoc = transform(jsdoc);
 
   const comment = '/*' + jsdocNode.value + '*/';
@@ -131,6 +132,7 @@ export default iterateJsdoc(({
 }) => {
   const {
     tags: applicableTags = ['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return'],
+    preserveMainDescriptionPostDelimiter,
   } = context.options[1] || {};
 
   if (context.options[0] === 'always') {
@@ -143,6 +145,7 @@ export default iterateJsdoc(({
       indent,
       jsdoc,
       jsdocNode,
+      preserveMainDescriptionPostDelimiter,
       report,
       tags: applicableTags,
       utils,
@@ -171,6 +174,10 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          preserveMainDescriptionPostDelimiter: {
+            default: false,
+            type: 'boolean',
+          },
           tags: {
             items: {
               type: 'string',

test/rules/assertions/checkLineAlignment.js

@@ -860,6 +860,35 @@ export default {
       function quux () {}
       `,
     },
+    {
+      code: `
+      /**
+       * Function description
+       *           description with post delimiter.
+       *
+       * @param {string} lorem Description.
+       * @param {int}    sit   Description multi words.
+       */
+      const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          message: 'Expected JSDoc block lines to be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: ['always'],
+      output: `
+      /**
+       * Function description
+       * description with post delimiter.
+       *
+       * @param {string} lorem Description.
+       * @param {int}    sit   Description multi words.
+       */
+      const fn = ( lorem, sit ) => {}
+      `,
+    },
   ],
   valid: [
     {
@@ -1183,5 +1212,20 @@ export default {
       }
       `,
     },
+    {
+      code: `
+        /**
+         * Function description
+         *           description with post delimiter.
+         *
+         * @param {string} lorem Description.
+         * @param {int}    sit   Description multi words.
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      options: ['always', {
+        preserveMainDescriptionPostDelimiter: true,
+      }],
+    },
   ],
 };