refactor: forbid inconsistent indentation with new option

brettz9 · brettz9 · commit 03adf63ba11b · 2025-11-19T05:35:55.000-07:00
diff --git a/docs/rules/check-indentation.md b/docs/rules/check-indentation.md
@@ -199,6 +199,19 @@ function quux () {
  */
 // "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
 // Message: There must be no indentation.
+
+/**
+ * Some text
+ *   that is indented
+ *  but is inconsistent
+ */
+// "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
+// Message: There must be no indentation.
+
+/**  Indented on first line
+ */
+// "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
+// Message: There must be no indentation.
 ````
 
 
@@ -342,5 +355,28 @@ function MyDecorator(options: { myOptions: number }) {
  *   - bar
  */
 // "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
+
+/**
+ * Some text
+ *   that is indented
+ *   and continues at same level
+ *     and increases further
+ */
+// "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
+
+/**
+ * Description
+ * @param {string} foo Param
+ *   with continuation
+ *   at same indentation
+ */
+// "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
+
+/**
+ * Description
+ *
+ * More content
+ */
+// "jsdoc/check-indentation": ["error"|"warn", {"allowIndentedSections":true}]
 ````
 
diff --git a/src/rules/checkIndentation.js b/src/rules/checkIndentation.js
@@ -25,6 +25,17 @@ const maskCodeBlocks = (str) => {
   });
 };
 
+/**
+ * @param {string[]} lines
+ * @param {number} lineIndex
+ * @returns {number}
+ */
+const getLineNumber = (lines, lineIndex) => {
+  const precedingText = lines.slice(0, lineIndex).join('\n');
+  const lineBreaks = precedingText.match(/\n/gv) || [];
+  return lineBreaks.length + 1;
+};
+
 export default iterateJsdoc(({
   context,
   jsdocNode,
@@ -47,47 +58,64 @@ export default iterateJsdoc(({
     // and the very first line of the main description
     const lines = text.split('\n');
     let hasSeenContent = false;
+    let currentSectionIndent = null;
 
     for (const [
       lineIndex,
       line,
     ] of lines.entries()) {
       // Check for indentation (two or more spaces after *)
-      const indentMatch = line.match(/^(?:\/?\**|[\t ]*)\*([\t ]{2,})/gv);
+      const indentMatch = line.match(/^(?:\/?\**|[\t ]*)\*([\t ]{2,})/v);
 
       if (indentMatch) {
         // Check what comes after the indentation
         const afterIndent = line.slice(indentMatch[0].length);
+        const indentAmount = indentMatch[1].length;
 
         // If this is a tag line with indentation, always report
         if (/^@\w+/v.test(afterIndent)) {
-          // Count newlines before this line
-          const precedingText = lines.slice(0, lineIndex).join('\n');
-          const lineBreaks = precedingText.match(/\n/gv) || [];
           report('There must be no indentation.', null, {
-            line: lineBreaks.length + 1,
+            line: getLineNumber(lines, lineIndex),
           });
           return;
         }
 
         // If we haven't seen any content yet (main description first line) and there's content, report
         if (!hasSeenContent && afterIndent.trim().length > 0) {
-          // Count newlines before this line
-          const precedingText = lines.slice(0, lineIndex).join('\n');
-          const lineBreaks = precedingText.match(/\n/gv) || [];
           report('There must be no indentation.', null, {
-            line: lineBreaks.length + 1,
+            line: getLineNumber(lines, lineIndex),
           });
           return;
         }
 
-        // Otherwise, allow it (continuation lines)
+        // For continuation lines, check consistency
+        if (hasSeenContent && afterIndent.trim().length > 0) {
+          if (currentSectionIndent === null) {
+            // First indented line in this section, set the indent level
+            currentSectionIndent = indentAmount;
+          } else if (indentAmount < currentSectionIndent) {
+            // Indentation is less than the established level (inconsistent)
+            report('There must be no indentation.', null, {
+              line: getLineNumber(lines, lineIndex),
+            });
+            return;
+          }
+        }
+      } else if (/^\s*\*\s+\S/v.test(line)) {
+        // No indentation on this line, reset section indent tracking
+        // (unless it's just whitespace or a closing comment)
+        currentSectionIndent = null;
       }
 
       // Track if we've seen any content (non-whitespace after the *)
       if (/^\s*\*\s+\S/v.test(line)) {
         hasSeenContent = true;
       }
+
+      // Reset section indent when we encounter a tag
+      if (/@\w+/v.test(line)) {
+        currentSectionIndent = null;
+      }
     }
   } else {
     const reg = /^(?:\/?\**|[ \t]*)\*[ \t]{2}/gmv;
diff --git a/test/rules/assertions/checkIndentation.js b/test/rules/assertions/checkIndentation.js
@@ -251,6 +251,23 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**  Indented on first line
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'There must be no indentation.',
+        },
+      ],
+      options: [
+        {
+          allowIndentedSections: true,
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -463,5 +480,49 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * Some text
+         *   that is indented
+         *   and continues at same level
+         *     and increases further
+         */
+      `,
+      options: [
+        {
+          allowIndentedSections: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Description
+         * @param {string} foo Param
+         *   with continuation
+         *   at same indentation
+         */
+      `,
+      options: [
+        {
+          allowIndentedSections: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Description
+         *
+         * More content
+         */
+      `,
+      options: [
+        {
+          allowIndentedSections: true,
+        },
+      ],
+    },
   ],
 });
