Add custom spacing to line alignment rule

src/alignTransform.js

@@ -1,3 +1,9 @@
+/**
+ * Transform based on https://github.com/syavorsky/comment-parser/blob/master/src/transforms/align.ts
+ *
+ * It contains some customizations to align based on the tags, and some custom options.
+ */
+
 import {
   Markers,
 } from 'comment-parser/lib/primitives';
@@ -58,7 +64,12 @@ const space = (len) => {
   return ''.padStart(len, ' ');
 };
 
-const alignTransform = (tags, indent, preserveMainDescriptionPostDelimiter) => {
+const alignTransform = ({
+  customSpacings,
+  tags,
+  indent,
+  preserveMainDescriptionPostDelimiter,
+}) => {
   let intoTags = false;
   let width;
 
@@ -90,17 +101,24 @@ const alignTransform = (tags, indent, preserveMainDescriptionPostDelimiter) => {
       }
     }
 
-    tokens.postDelimiter = nothingAfter.delim ? '' : ' ';
+    const spacings = {
+      postDelimiter: customSpacings?.postDelimiter || 1,
+      postName: customSpacings?.postName || 1,
+      postTag: customSpacings?.postTag || 1,
+      postType: customSpacings?.postType || 1,
+    };
+
+    tokens.postDelimiter = nothingAfter.delim ? '' : space(spacings.postDelimiter);
 
     if (!nothingAfter.tag) {
-      tokens.postTag = space(width.tag - tokens.tag.length + 1);
+      tokens.postTag = space(width.tag - tokens.tag.length + spacings.postTag);
     }
     if (!nothingAfter.type) {
-      tokens.postType = space(width.type - tokens.type.length + 1);
+      tokens.postType = space(width.type - tokens.type.length + spacings.postType);
     }
     if (!nothingAfter.name) {
       // If post name is empty for all lines (name width 0), don't add post name spacing.
-      tokens.postName = width.name === 0 ? '' : space(width.name - tokens.name.length + 1);
+      tokens.postName = width.name === 0 ? '' : space(width.name - tokens.name.length + spacings.postName);
     }
 
     return tokens;

src/rules/checkLineAlignment.js

@@ -8,7 +8,7 @@ const {
   flow: commentFlow,
 } = transforms;
 
-const checkNotAlignedPerTag = (utils, tag) => {
+const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
   /*
   start +
   delimiter +
@@ -61,11 +61,12 @@ const checkNotAlignedPerTag = (utils, tag) => {
     const contentProp = contentProps[idx];
     const contentPropVal = tokens[contentProp];
     const spacerPropVal = tokens[spacerProp];
+    const spacing = customSpacings?.[spacerProp] || 1;
 
     // There will be extra alignment if...
 
-    // 1. There is extra whitespace within a single spacer segment OR
-    return spacerPropVal.length > 1 ||
+    // 1. The spaces doesn't match the space it should have (1 or custom spacing) OR
+    return spacerPropVal.length !== spacing && spacerPropVal.length !== 0 ||
 
       // 2. There is a (single) space, no immediate content, and yet another
       //     space is found subsequently (not separated by intervening content)
@@ -80,7 +81,8 @@ const checkNotAlignedPerTag = (utils, tag) => {
       const contentPropVal = tokens[contentProp];
 
       if (contentPropVal) {
-        tokens[spacerProp] = ' ';
+        const spacing = customSpacings?.[spacerProp] || 1;
+        tokens[spacerProp] = ''.padStart(spacing, ' ');
         followedBySpace(idx, (hasSpace, contentPrp) => {
           if (hasSpace) {
             tokens[contentPrp] = '';
@@ -97,6 +99,7 @@ const checkNotAlignedPerTag = (utils, tag) => {
 };
 
 const checkAlignment = ({
+  customSpacings,
   indent,
   jsdoc,
   jsdocNode,
@@ -105,7 +108,14 @@ const checkAlignment = ({
   tags,
   utils,
 }) => {
-  const transform = commentFlow(alignTransform(tags, indent, preserveMainDescriptionPostDelimiter));
+  const transform = commentFlow(
+    alignTransform({
+      customSpacings,
+      indent,
+      preserveMainDescriptionPostDelimiter,
+      tags,
+    }),
+  );
   const transformedJsdoc = transform(jsdoc);
 
   const comment = '/*' + jsdocNode.value + '*/';
@@ -133,6 +143,7 @@ export default iterateJsdoc(({
   const {
     tags: applicableTags = ['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return'],
     preserveMainDescriptionPostDelimiter,
+    customSpacings,
   } = context.options[1] || {};
 
   if (context.options[0] === 'always') {
@@ -142,6 +153,7 @@ export default iterateJsdoc(({
     }
 
     checkAlignment({
+      customSpacings,
       indent,
       jsdoc,
       jsdocNode,
@@ -156,7 +168,7 @@ export default iterateJsdoc(({
 
   const foundTags = utils.getPresentTags(applicableTags);
   foundTags.forEach((tag) => {
-    checkNotAlignedPerTag(utils, tag);
+    checkNotAlignedPerTag(utils, tag, customSpacings);
   });
 }, {
   iterateAllJsdocs: true,
@@ -174,6 +186,9 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          customSpacings: {
+            type: 'object',
+          },
           preserveMainDescriptionPostDelimiter: {
             default: false,
             type: 'boolean',

test/rules/assertions/checkLineAlignment.js

@@ -917,6 +917,78 @@ export default {
       const fn = ( lorem, sit ) => {}
       `,
     },
+    {
+      code: `
+      /**
+       * Function description.
+       *
+       * @param  {string} lorem Description.
+       * @param  {int}    sit   Description multi words.
+       *
+       * @return {string}       Return description.
+       */
+      const fn = ( lorem, sit ) => {}
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Expected JSDoc block lines to be aligned.',
+          type: 'Block',
+        },
+      ],
+      options: ['always', {
+        customSpacings: {
+          postDelimiter: 2,
+          postTag: 3,
+          postType: 2,
+        },
+      }],
+      output: `
+      /**
+       * Function description.
+       *
+       *  @param    {string}  lorem Description.
+       *  @param    {int}     sit   Description multi words.
+       *
+       *  @return   {string}        Return description.
+       */
+      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: {
+          postDelimiter: 2,
+          postTag: 3,
+          postType: 2,
+        },
+      }],
+      output: `
+      /**
+       * Function description.
+       *
+       *  @param   {string}  lorem Description.
+       *  @param   {int}  sit Description multi words.
+       */
+      const fn = ( lorem, sit ) => {}
+      `,
+    },
   ],
   valid: [
     {