Implement "always" mode support for list indentation preservation

Co-authored-by: brettz9 <[email protected]>

Author: Copilot

docs/rules/check-line-alignment.md

@@ -1093,5 +1093,35 @@ function test() {}
  */
 function test() {}
 // "jsdoc/check-line-alignment": ["error"|"warn", "never",{"wrapIndent":"  "}]
+
+/**
+ * @param {string} param Description with list:
+ *                         - Item 1
+ *                           - Nested item
+ */
+function test(param) {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"wrapIndent":"  "}]
+
+/**
+ * Function description.
+ *
+ * @param {string} lorem Description.
+ * @param {int}    sit   Description with list:
+ *                         - First item
+ *                         - Second item
+ *                           - Nested item
+ */
+const fn = ( lorem, sit ) => {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"wrapIndent":"  "}]
+
+/**
+ * @return {Promise} A promise.
+ *                     - On success, resolves.
+ *                     - On error, rejects with details:
+ *                       - When aborted, status is "abort".
+ *                       - On timeout, status is "timeout".
+ */
+function test() {}
+// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"wrapIndent":"  "}]
 ````
 

src/alignTransform.js

@@ -9,6 +9,27 @@ import {
   util,
 } from 'comment-parser';
 
+/**
+ * Detects if a line starts with a markdown list marker
+ * Supports: -, *, numbered lists (1., 2., etc.)
+ * This explicitly excludes hyphens that are part of JSDoc tag syntax
+ * @param {string} text - The text to check
+ * @param {boolean} isFirstLineOfTag - True if this is the first line (tag line)
+ * @returns {boolean} - True if the text starts with a list marker
+ */
+const startsWithListMarker = (text, isFirstLineOfTag = false) => {
+  // On the first line of a tag, the hyphen is typically the JSDoc separator,
+  // not a list marker
+  if (isFirstLineOfTag) {
+    return false;
+  }
+
+  // Match lines that start with optional whitespace, then a list marker
+  // - or * followed by a space
+  // or a number followed by . or ) and a space
+  return /^\s*(?:[\-*]|\d+(?:\.|\)))\s+/v.test(text);
+};
+
 /**
  * @typedef {{
  *   hasNoTypes: boolean,
@@ -144,6 +165,59 @@ const space = (len) => {
   return ''.padStart(len, ' ');
 };
 
+/**
+ * Check if a tag or any of its lines contain list markers
+ * @param {import('./iterateJsdoc.js').Integer} index - Current line index
+ * @param {import('comment-parser').Line[]} source - All source lines
+ * @returns {{hasListMarker: boolean, tagStartIndex: import('./iterateJsdoc.js').Integer}}
+ */
+const checkForListMarkers = (index, source) => {
+  let hasListMarker = false;
+  let tagStartIndex = index;
+  while (tagStartIndex > 0 && source[tagStartIndex].tokens.tag === '') {
+    tagStartIndex--;
+  }
+
+  for (let idx = tagStartIndex; idx <= index; idx++) {
+    const isFirstLine = (idx === tagStartIndex);
+    if (source[idx]?.tokens?.description && startsWithListMarker(source[idx].tokens.description, isFirstLine)) {
+      hasListMarker = true;
+      break;
+    }
+  }
+
+  return {
+    hasListMarker,
+    tagStartIndex,
+  };
+};
+
+/**
+ * Calculate extra indentation for list items relative to the first continuation line
+ * @param {import('./iterateJsdoc.js').Integer} index - Current line index
+ * @param {import('./iterateJsdoc.js').Integer} tagStartIndex - Index of the tag line
+ * @param {import('comment-parser').Line[]} source - All source lines
+ * @returns {string} - Extra indentation spaces
+ */
+const calculateListExtraIndent = (index, tagStartIndex, source) => {
+  // Find the first continuation line to use as baseline
+  let firstContinuationIndent = null;
+  for (let idx = tagStartIndex + 1; idx < source.length; idx++) {
+    if (source[idx].tokens.description && !source[idx].tokens.tag) {
+      firstContinuationIndent = source[idx].tokens.postDelimiter.length;
+      break;
+    }
+  }
+
+  // Calculate the extra indentation of current line relative to the first continuation line
+  const currentOriginalIndent = source[index].tokens.postDelimiter.length;
+  const extraIndent = firstContinuationIndent !== null && currentOriginalIndent > firstContinuationIndent ?
+    ' '.repeat(currentOriginalIndent - firstContinuationIndent) :
+    '';
+
+  return extraIndent;
+};
+
 /**
  * @param {{
  *   customSpacings: import('../src/rules/checkLineAlignment.js').CustomSpacings,
@@ -316,8 +390,20 @@ const alignTransform = ({
     // Not align.
     if (shouldAlign(tags, index, source)) {
       alignTokens(tokens, typelessInfo);
+
       if (!disableWrapIndent && indentTag) {
-        tokens.postDelimiter += wrapIndent;
+        const {
+          hasListMarker,
+          tagStartIndex,
+        } = checkForListMarkers(index, source);
+
+        if (hasListMarker && index > tagStartIndex) {
+          const extraIndent = calculateListExtraIndent(index, tagStartIndex, source);
+          tokens.postDelimiter += wrapIndent + extraIndent;
+        } else {
+          // Normal case: add wrapIndent after the aligned delimiter
+          tokens.postDelimiter += wrapIndent;
+        }
       }
     }
 

test/rules/assertions/checkLineAlignment.js

@@ -2240,5 +2240,60 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    // Test cases for "always" mode with list indentation
+    {
+      code: `
+        /**
+         * @param {string} param Description with list:
+         *                         - Item 1
+         *                           - Nested item
+         */
+        function test(param) {}
+      `,
+      options: [
+        'always',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Function description.
+         *
+         * @param {string} lorem Description.
+         * @param {int}    sit   Description with list:
+         *                         - First item
+         *                         - Second item
+         *                           - Nested item
+         */
+        const fn = ( lorem, sit ) => {}
+      `,
+      options: [
+        'always',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @return {Promise} A promise.
+         *                     - On success, resolves.
+         *                     - On error, rejects with details:
+         *                       - When aborted, status is "abort".
+         *                       - On timeout, status is "timeout".
+         */
+        function test() {}
+      `,
+      options: [
+        'always',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
   ],
 });