Add support for preserving list indentation in check-line-alignment (never mode)

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

Author: Copilot

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,
@@ -315,9 +336,45 @@ const alignTransform = ({
 
     // Not align.
     if (shouldAlign(tags, index, source)) {
+      // Save original postDelimiter before alignTokens modifies it
+      const originalPostDelimiter = tokens.postDelimiter;
+      // Remove the delimiter space
+      const originalIndent = tokens.postDelimiter.slice(1);
+
       alignTokens(tokens, typelessInfo);
+
       if (!disableWrapIndent && indentTag) {
-        tokens.postDelimiter += wrapIndent;
+        // Preserve extra indentation for list continuation lines
+        // Check if any previous line (or current) in the current tag has a list marker
+        let hasListMarker = false;
+
+        // Find the start of the current tag
+        let tagStartIndex = index;
+        while (tagStartIndex > 0 && source[tagStartIndex].tokens.tag === '') {
+          tagStartIndex--;
+        }
+
+        // Check all lines from tag start to current line for list markers
+        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;
+          }
+        }
+
+        // If we're in a list context and this line has extra indentation beyond wrapIndent,
+        // preserve the original indentation
+        const hasExtraIndent = originalIndent.length > wrapIndent.length &&
+                                originalIndent.startsWith(wrapIndent);
+
+        if (hasListMarker && hasExtraIndent) {
+          // Preserve the original indentation completely
+          tokens.postDelimiter = originalPostDelimiter;
+        } else {
+          // Normal case: add wrapIndent after the aligned delimiter
+          tokens.postDelimiter += wrapIndent;
+        }
       }
     }
 

src/rules/checkLineAlignment.js

@@ -8,6 +8,54 @@ const {
   flow: commentFlow,
 } = transforms;
 
+/**
+ * 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);
+};
+
+/**
+ * Checks if we should allow extra indentation beyond wrapIndent.
+ * This is true for list continuation lines (lines with more indent than wrapIndent
+ * that follow a list item).
+ * @param {import('comment-parser').Spec} tag - The tag being checked
+ * @param {import('../iterateJsdoc.js').Integer} idx - Current line index (0-based in tag.source.slice(1))
+ * @returns {boolean} - True if extra indentation should be allowed
+ */
+const shouldAllowExtraIndent = (tag, idx) => {
+  // Check if any previous line in this tag had a list marker
+  // idx is 0-based in the continuation lines (tag.source.slice(1))
+  // So tag.source[0] is the tag line, tag.source[idx+1] is current line
+  let hasSeenListMarker = false;
+
+  // Check all lines from the tag line onwards
+  for (let lineIdx = 0; lineIdx <= idx + 1; lineIdx++) {
+    const line = tag.source[lineIdx];
+    const isFirstLine = lineIdx === 0;
+    if (line?.tokens?.description && startsWithListMarker(line.tokens.description, isFirstLine)) {
+      hasSeenListMarker = true;
+      break;
+    }
+  }
+
+  return hasSeenListMarker;
+};
+
 /**
  * @typedef {{
  *   postDelimiter: import('../iterateJsdoc.js').Integer,
@@ -298,7 +346,17 @@ export default iterateJsdoc(({
         }
 
         // Don't include a single separating space/tab
-        if (!disableWrapIndent && tokens.postDelimiter.slice(1) !== wrapIndent) {
+        const actualIndent = tokens.postDelimiter.slice(1);
+        const hasCorrectWrapIndent = actualIndent === wrapIndent;
+
+        // Allow extra indentation if this line or previous lines contain list markers
+        // This preserves nested list structure
+        const hasExtraIndent = actualIndent.length > wrapIndent.length &&
+                                actualIndent.startsWith(wrapIndent);
+        const isInListContext = shouldAllowExtraIndent(tag, idx - 1);
+
+        if (!disableWrapIndent && !hasCorrectWrapIndent &&
+            !(hasExtraIndent && isInListContext)) {
           utils.reportJSDoc('Expected wrap indent', {
             line: tag.source[0].number + idx,
           }, () => {

test/rules/assertions/checkLineAlignment.js

@@ -2167,5 +2167,78 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    // List indentation tests - should preserve nested list structure
+    {
+      code: `
+        /**
+         * @return {Promise} A promise.
+         *   - On success, resolves.
+         *   - On error, rejects with details:
+         *     - When aborted, textStatus is "abort".
+         *     - On timeout, textStatus is "timeout".
+         */
+        function test() {}
+      `,
+      options: [
+        'never',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {string} lorem Description with list:
+         *   - First item
+         *   - Second item
+         *     - Nested item
+         *     - Another nested item
+         */
+        function test() {}
+      `,
+      options: [
+        'never',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @return {Promise} A promise.
+         *   1. First step
+         *   2. Second step with continuation
+         *      on another line
+         *   3. Third step
+         */
+        function test() {}
+      `,
+      options: [
+        'never',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {Object} options Configuration options.
+         *   * First option
+         *   * Second option with details:
+         *     * Nested detail
+         *     * Another detail
+         */
+        function test() {}
+      `,
+      options: [
+        'never',
+        {
+          wrapIndent: '  ',
+        },
+      ],
+    },
   ],
 });