feat(check-line-alignment): add disableWrapIndent` option

Author: davidmurdoch

.README/rules/check-line-alignment.md

@@ -49,12 +49,16 @@ main description. If `false` or unset, will be set to a single space.
 The indent that will be applied for tag text after the first line.
 Default to the empty string (no indent).
 
+### `disableWrapIndent`
+
+Disables `wrapIndent`; existing wrap indentation is preserved without changes.
+
 ## Context and settings
 
 |||
 |---|---|
 |Context|everywhere|
-|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`|
+|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`, `disableWrapIndent`|
 |Tags|`param`, `property`, `returns` and others added by `tags`|
 |Aliases|`arg`, `argument`, `prop`, `return`|
 |Recommended|false|

docs/rules/check-line-alignment.md

@@ -8,6 +8,7 @@
     * [`customSpacings`](#user-content-check-line-alignment-options-customspacings)
     * [`preserveMainDescriptionPostDelimiter`](#user-content-check-line-alignment-options-preservemaindescriptionpostdelimiter)
     * [`wrapIndent`](#user-content-check-line-alignment-options-wrapindent)
+    * [`disableWrapIndent`](#user-content-check-line-alignment-options-disablewrapindent)
 * [Context and settings](#user-content-check-line-alignment-context-and-settings)
 * [Failing examples](#user-content-check-line-alignment-failing-examples)
 * [Passing examples](#user-content-check-line-alignment-passing-examples)
@@ -72,14 +73,20 @@ main description. If `false` or unset, will be set to a single space.
 The indent that will be applied for tag text after the first line.
 Default to the empty string (no indent).
 
+<a name="user-content-check-line-alignment-options-disablewrapindent"></a>
+<a name="check-line-alignment-options-disablewrapindent"></a>
+### <code>disableWrapIndent</code>
+
+Disables `wrapIndent`; existing wrap indentation is preserved without changes.
+
 <a name="user-content-check-line-alignment-context-and-settings"></a>
 <a name="check-line-alignment-context-and-settings"></a>
 ## Context and settings
 
 |||
 |---|---|
 |Context|everywhere|
-|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`|
+|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`, `disableWrapIndent`|
 |Tags|`param`, `property`, `returns` and others added by `tags`|
 |Aliases|`arg`, `argument`, `prop`, `return`|
 |Recommended|false|
@@ -998,5 +1005,23 @@ function quux () {}
  * @returns {number} -1 if world transform has negative scale, 1 otherwise.
  */
 // "jsdoc/check-line-alignment": ["error"|"warn", "never"]
+
+/**
+ * @param {string} lorem Description
+ *   with multiple lines preserving existing indentation when wrapIndent is disabled.
+ */
+function quux () {
+}
+// "jsdoc/check-line-alignment": ["error"|"warn", "any",{"disableWrapIndent":true}]
+
+/**
+ * Function description with disableWrapIndent true, but wrapIndent defined.
+ * Preserves existing indentation regardless of wrapIndent value.
+ *
+ * @param {string} lorem Description
+ *   with multiple lines.
+ */
+const fn = ( lorem ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "any",{"disableWrapIndent":true,"wrapIndent":"  "}]
 ````
 

src/alignTransform.js

@@ -151,6 +151,7 @@ const space = (len) => {
  *   indent: string,
  *   preserveMainDescriptionPostDelimiter: boolean,
  *   wrapIndent: string,
+ *   disableWrapIndent: boolean,
  * }} cfg
  * @returns {(
  *   block: import('comment-parser').Block
@@ -162,6 +163,7 @@ const alignTransform = ({
   indent,
   preserveMainDescriptionPostDelimiter,
   wrapIndent,
+  disableWrapIndent,
 }) => {
   let intoTags = false;
   /** @type {Width} */
@@ -314,7 +316,7 @@ const alignTransform = ({
     // Not align.
     if (shouldAlign(tags, index, source)) {
       alignTokens(tokens, typelessInfo);
-      if (indentTag) {
+      if (!disableWrapIndent && indentTag) {
         tokens.postDelimiter += wrapIndent;
       }
     }
@@ -340,10 +342,10 @@ const alignTransform = ({
     return rewireSource({
       ...fields,
       source: source.map((line, index) => {
-        const indentTag = tagIndentMode && !line.tokens.tag && line.tokens.description;
+        const indentTag = !disableWrapIndent && tagIndentMode && !line.tokens.tag && line.tokens.description;
         const ret = update(line, index, source, typelessInfo, indentTag);
 
-        if (line.tokens.tag) {
+        if (!disableWrapIndent && line.tokens.tag) {
           tagIndentMode = true;
         }
 

src/rules/checkLineAlignment.js

@@ -169,6 +169,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
  * @param {string[]} cfg.tags
  * @param {import('../iterateJsdoc.js').Utils} cfg.utils
  * @param {string} cfg.wrapIndent
+ * @param {boolean} cfg.disableWrapIndent
  * @returns {void}
  */
 const checkAlignment = ({
@@ -181,6 +182,7 @@ const checkAlignment = ({
   tags,
   utils,
   wrapIndent,
+  disableWrapIndent,
 }) => {
   const transform = commentFlow(
     alignTransform({
@@ -189,6 +191,7 @@ const checkAlignment = ({
       preserveMainDescriptionPostDelimiter,
       tags,
       wrapIndent,
+      disableWrapIndent,
     }),
   );
   const transformedJsdoc = transform(jsdoc);
@@ -228,6 +231,7 @@ export default iterateJsdoc(({
     preserveMainDescriptionPostDelimiter,
     customSpacings,
     wrapIndent = '',
+    disableWrapIndent = false,
   } = context.options[1] || {};
 
   if (context.options[0] === 'always') {
@@ -253,6 +257,7 @@ export default iterateJsdoc(({
       tags: applicableTags,
       utils,
       wrapIndent,
+      disableWrapIndent,
     });
 
     return;
@@ -293,7 +298,7 @@ export default iterateJsdoc(({
         }
 
         // Don't include a single separating space/tab
-        if (tokens.postDelimiter.slice(1) !== wrapIndent) {
+        if (!disableWrapIndent && tokens.postDelimiter.slice(1) !== wrapIndent) {
           utils.reportJSDoc('Expected wrap indent', {
             line: tag.source[0].number + idx,
           }, () => {
@@ -355,6 +360,9 @@ export default iterateJsdoc(({
           wrapIndent: {
             type: 'string',
           },
+          disableWrapIndent: {
+            type: 'boolean',
+          },
         },
         type: 'object',
       },

test/rules/assertions/checkLineAlignment.js

@@ -2182,5 +2182,40 @@ export default {
         'never',
       ],
     },
+    {
+      code: `
+        /**
+         * @param {string} lorem Description
+         *   with multiple lines preserving existing indentation when wrapIndent is disabled.
+         */
+        function quux () {
+        }
+      `,
+      options: [
+        'any',
+        {
+          disableWrapIndent: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Function description with disableWrapIndent true, but wrapIndent defined.
+         * Preserves existing indentation regardless of wrapIndent value.
+         *
+         * @param {string} lorem Description
+         *   with multiple lines.
+         */
+        const fn = ( lorem ) => {}
+      `,
+      options: [
+        'any',
+        {
+          disableWrapIndent: true,
+          wrapIndent: '  ',
+        },
+      ],
+    },
   ],
 };