eslint-markdown 0.9.1 → 0.11.0

package/README.md

@@ -7,6 +7,7 @@
 
 [![npm package eslint-markdown latest version](https://img.shields.io/npm/v/eslint-markdown?label=eslint-markdown@latest&color=6358d4&labelColor=333333&logo=npm)](https://www.npmjs.com/package/eslint-markdown)
 [![npm package eslint-markdown next version](https://img.shields.io/npm/v/eslint-markdown/next?label=eslint-markdown@next&color=6358d4&labelColor=333333&logo=npm)](https://www.npmjs.com/package/eslint-markdown)
+[![npm package eslint-markdown downloads per month](https://img.shields.io/npm/dm/eslint-markdown?label=downloads&color=6358d4&labelColor=333333&logo=npm)](https://www.npmjs.com/package/eslint-markdown)
 
 > [!IMPORTANT]
 >

package/build/configs/all.d.ts

@@ -24,6 +24,7 @@ export default function all(plugin: ESLint.Plugin): {
         readonly 'md/consistent-strong-style': "error";
         readonly 'md/consistent-thematic-break-style': "error";
         readonly 'md/consistent-unordered-list-style': "error";
+        readonly 'md/no-consecutive-blank-line': "error";
         readonly 'md/no-control-character': "error";
         readonly 'md/no-curly-quote': "error";
         readonly 'md/no-double-punctuation': "error";
@@ -34,6 +35,7 @@ export default function all(plugin: ESLint.Plugin): {
         readonly 'md/no-irregular-whitespace': "error";
         readonly 'md/no-tab': "error";
         readonly 'md/no-url-trailing-slash': "error";
+        readonly 'md/require-heading-id': "error";
         readonly 'md/require-image-title': "error";
         readonly 'md/require-link-title': "error";
     };

package/build/configs/stylistic.d.ts

@@ -21,6 +21,7 @@ export default function stylistic(plugin: ESLint.Plugin): {
         readonly 'md/consistent-strong-style': "error";
         readonly 'md/consistent-thematic-break-style': "error";
         readonly 'md/consistent-unordered-list-style': "error";
+        readonly 'md/no-consecutive-blank-line': "error";
         readonly 'md/no-tab': "error";
     };
 };

package/build/core/ast/escape-string-regexp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Utility to escape `RegExp` special characters.
+ * @see https://github.com/sindresorhus/escape-string-regexp/tree/v5.0.0
+ */
+/**
+ * Escape `RegExp` special characters.
+ *
+ * You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.
+ *
+ * @param {string} string A string to escape.
+ * @returns {string} An escaped string.
+ * @example
+ * ```js
+ * import escapeStringRegexp from 'path/to/escape-string-regexp.js';
+ *
+ * const escapedString = escapeStringRegexp('How much $ for a 🦄?');
+ * //=> 'How much \\$ for a 🦄\\?'
+ *
+ * new RegExp(escapedString);
+ * ```
+ */
+export default function escapeStringRegexp(string: string): string;

package/build/core/ast/index.d.ts

@@ -1,4 +1,5 @@
+import escapeStringRegexp from './escape-string-regexp.js';
 import getElementsByTagName from './html.js';
 import isBlankLine from './is-blank-line.js';
 import SkipRanges from './skip-ranges.js';
-export { getElementsByTagName, isBlankLine, SkipRanges };
+export { escapeStringRegexp, getElementsByTagName, isBlankLine, SkipRanges };

package/build/rules/index.d.ts

@@ -9,7 +9,8 @@ declare const _default: {
     'consistent-strong-style': import("../core/types.js").RuleModule<import("./consistent-strong-style.js").RuleOptions, "style">;
     'consistent-thematic-break-style': import("../core/types.js").RuleModule<import("./consistent-thematic-break-style.js").RuleOptions, "style">;
     'consistent-unordered-list-style': import("../core/types.js").RuleModule<import("./consistent-unordered-list-style.js").RuleOptions, "style">;
-    'no-control-character': import("../core/types.js").RuleModule<import("./no-control-character.js").RuleOptions, "noControlCharacter">;
+    'no-consecutive-blank-line': import("../core/types.js").RuleModule<import("./no-consecutive-blank-line.js").RuleOptions, "noConsecutiveBlankLine">;
+    'no-control-character': import("../core/types.js").RuleModule<import("./no-control-character.js").RuleOptions, import("./no-control-character.js").MessageIds>;
     'no-curly-quote': import("../core/types.js").RuleModule<import("./no-curly-quote.js").RuleOptions, "noCurlyQuote">;
     'no-double-punctuation': import("../core/types.js").RuleModule<import("./no-double-punctuation.js").RuleOptions, import("./no-double-punctuation.js").MessageIds>;
     'no-double-space': import("../core/types.js").RuleModule<import("./no-double-space.js").RuleOptions, import("./no-double-space.js").MessageIds>;
@@ -19,6 +20,7 @@ declare const _default: {
     'no-irregular-whitespace': import("../core/types.js").RuleModule<import("./no-irregular-whitespace.js").RuleOptions, "noIrregularWhitespace">;
     'no-tab': import("../core/types.js").RuleModule<import("./no-tab.js").RuleOptions, "noTab">;
     'no-url-trailing-slash': import("../core/types.js").RuleModule<[], "noUrlTrailingSlash">;
+    'require-heading-id': import("../core/types.js").RuleModule<import("./require-heading-id.js").RuleOptions, import("./require-heading-id.js").MessageIds>;
     'require-image-title': import("../core/types.js").RuleModule<import("./require-image-title.js").RuleOptions, "requireImageTitle">;
     'require-link-title': import("../core/types.js").RuleModule<import("./require-link-title.js").RuleOptions, "requireLinkTitle">;
 };

package/build/rules/no-consecutive-blank-line.d.ts

@@ -0,0 +1,60 @@
+declare const _default: {
+    meta: {
+        type: "layout";
+        docs: {
+            description: string;
+            url: string;
+            recommended: boolean;
+            stylistic: true;
+        };
+        fixable: "whitespace";
+        schema: {
+            type: "object";
+            properties: {
+                max: {
+                    type: "integer";
+                    minimum: number;
+                };
+                skipCode: {
+                    oneOf: ({
+                        type: "boolean";
+                        items?: never;
+                        uniqueItems?: never;
+                    } | {
+                        type: "array";
+                        items: {
+                            type: "string";
+                        };
+                        uniqueItems: true;
+                    })[];
+                };
+            };
+            additionalProperties: false;
+        }[];
+        defaultOptions: [{
+            max: number;
+            skipCode: true;
+        }];
+        messages: {
+            noConsecutiveBlankLine: string;
+        };
+        language: string;
+        dialects: string[];
+    };
+    create(context: import("@eslint/core").RuleContext<{
+        LangOptions: import("@eslint/markdown").MarkdownLanguageOptions;
+        Code: import("@eslint/markdown").MarkdownSourceCode;
+        RuleOptions: RuleOptions;
+        Node: import("mdast").Node;
+        MessageIds: "noConsecutiveBlankLine";
+    }>): {
+        code(node: import("mdast").Code): void;
+        'root:exit'(): void;
+    };
+};
+export default _default;
+export type RuleOptions = [{
+    max: number;
+    skipCode: boolean | string[];
+}];
+export type MessageIds = "noConsecutiveBlankLine";

package/build/rules/no-control-character.d.ts

@@ -7,6 +7,7 @@ declare const _default: {
             recommended: boolean;
             stylistic: false;
         };
+        hasSuggestions: true;
         schema: {
             type: "object";
             properties: {
@@ -43,6 +44,7 @@ declare const _default: {
         }];
         messages: {
             noControlCharacter: string;
+            suggestRemove: string;
         };
         language: string;
         dialects: string[];
@@ -52,7 +54,7 @@ declare const _default: {
         Code: import("@eslint/markdown").MarkdownSourceCode;
         RuleOptions: RuleOptions;
         Node: import("mdast").Node;
-        MessageIds: "noControlCharacter";
+        MessageIds: MessageIds;
     }>): {
         code(node: import("mdast").Code): void;
         inlineCode(node: import("mdast").InlineCode): void;
@@ -65,4 +67,4 @@ export type RuleOptions = [{
     skipCode: boolean | string[];
     skipInlineCode: boolean;
 }];
-export type MessageIds = "noControlCharacter";
+export type MessageIds = "noControlCharacter" | "suggestRemove";

package/build/rules/{heading-id.d.ts → require-heading-id.d.ts}

@@ -22,7 +22,7 @@ declare const _default: {
                 rightDelimiter: {
                     type: "string";
                 };
-                ignoreDepth: {
+                allowDepths: {
                     type: "array";
                     items: {
                         enum: number[];
@@ -36,7 +36,7 @@ declare const _default: {
         defaultOptions: ["always", {
             leftDelimiter: string;
             rightDelimiter: string;
-            ignoreDepth: never[];
+            allowDepths: never[];
         }];
         messages: {
             headingIdAlways: string;
@@ -59,7 +59,7 @@ export default _default;
 export type RuleOptions = ["always" | "never", {
     leftDelimiter: string;
     rightDelimiter: string;
-    ignoreDepth: Heading["depth"][];
+    allowDepths: Heading["depth"][];
 }];
 export type MessageIds = "headingIdAlways" | "headingIdNever";
 import type { Heading } from 'mdast';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-markdown",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "type": "module",
   "sideEffects": false,
   "description": "Lint your Markdown with ESLint. Additional rules for use with `@eslint/markdown`.🛠️",

package/src/configs/all.js

@@ -48,6 +48,7 @@ export default function all(plugin) {
       'md/consistent-strong-style': 'error',
       'md/consistent-thematic-break-style': 'error',
       'md/consistent-unordered-list-style': 'error',
+      'md/no-consecutive-blank-line': 'error',
       'md/no-control-character': 'error',
       'md/no-curly-quote': 'error',
       'md/no-double-punctuation': 'error',
@@ -58,6 +59,7 @@ export default function all(plugin) {
       'md/no-irregular-whitespace': 'error',
       'md/no-tab': 'error',
       'md/no-url-trailing-slash': 'error',
+      'md/require-heading-id': 'error',
       'md/require-image-title': 'error',
       'md/require-link-title': 'error',
     },

package/src/configs/stylistic.js

@@ -45,6 +45,7 @@ export default function stylistic(plugin) {
       'md/consistent-strong-style': 'error',
       'md/consistent-thematic-break-style': 'error',
       'md/consistent-unordered-list-style': 'error',
+      'md/no-consecutive-blank-line': 'error',
       'md/no-tab': 'error',
     },
   });

package/src/core/ast/escape-string-regexp.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Utility to escape `RegExp` special characters.
+ * @see https://github.com/sindresorhus/escape-string-regexp/tree/v5.0.0
+ */
+
+/*
+ * MIT License
+ *
+ * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+// --------------------------------------------------------------------------------
+// Export
+// --------------------------------------------------------------------------------
+
+/**
+ * Escape `RegExp` special characters.
+ *
+ * You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.
+ *
+ * @param {string} string A string to escape.
+ * @returns {string} An escaped string.
+ * @example
+ * ```js
+ * import escapeStringRegexp from 'path/to/escape-string-regexp.js';
+ *
+ * const escapedString = escapeStringRegexp('How much $ for a 🦄?');
+ * //=> 'How much \\$ for a 🦄\\?'
+ *
+ * new RegExp(escapedString);
+ * ```
+ */
+export default function escapeStringRegexp(string) {
+  // Escape characters with special meaning either inside or outside character sets.
+  // Use a simple backslash escape when it's always valid, and a `\xnn` escape
+  // when the simpler form would be disallowed by Unicode patterns' stricter grammar.
+  return string.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&').replace(/-/g, '\\x2d');
+}

package/src/core/ast/index.js

@@ -1,5 +1,6 @@
+import escapeStringRegexp from './escape-string-regexp.js';
 import getElementsByTagName from './html.js';
 import isBlankLine from './is-blank-line.js';
 import SkipRanges from './skip-ranges.js';
 
-export { getElementsByTagName, isBlankLine, SkipRanges };
+export { escapeStringRegexp, getElementsByTagName, isBlankLine, SkipRanges };

package/src/rules/index.js

@@ -14,8 +14,8 @@ import consistentStrongStyle from './consistent-strong-style.js';
 import consistentThematicBreakStyle from './consistent-thematic-break-style.js';
 import consistentUnorderedListStyle from './consistent-unordered-list-style.js';
 // import enCapitalization from './en-capitalization.js';
-// import headingId from './heading-id.js';
 // import noBoldParagraph from './no-bold-paragraph.js';
+import noConsecutiveBlankLine from './no-consecutive-blank-line.js';
 import noControlCharacter from './no-control-character.js';
 import noCurlyQuote from './no-curly-quote.js';
 import noDoublePunctuation from './no-double-punctuation.js';
@@ -26,6 +26,7 @@ import noIrregularDash from './no-irregular-dash.js';
 import noIrregularWhitespace from './no-irregular-whitespace.js';
 import noTab from './no-tab.js';
 import noUrlTrailingSlash from './no-url-trailing-slash.js';
+import requireHeadingId from './require-heading-id.js';
 import requireImageTitle from './require-image-title.js';
 import requireLinkTitle from './require-link-title.js';
 
@@ -42,8 +43,8 @@ export default {
   'consistent-thematic-break-style': consistentThematicBreakStyle,
   'consistent-unordered-list-style': consistentUnorderedListStyle,
   // 'en-capitalization': enCapitalization,
-  // 'heading-id': headingId,
   // 'no-bold-paragraph': noBoldParagraph,
+  'no-consecutive-blank-line': noConsecutiveBlankLine,
   'no-control-character': noControlCharacter,
   'no-curly-quote': noCurlyQuote,
   'no-double-punctuation': noDoublePunctuation,
@@ -54,6 +55,7 @@ export default {
   'no-irregular-whitespace': noIrregularWhitespace,
   'no-tab': noTab,
   'no-url-trailing-slash': noUrlTrailingSlash,
+  'require-heading-id': requireHeadingId,
   'require-image-title': requireImageTitle,
   'require-link-title': requireLinkTitle,
 };

package/src/rules/no-consecutive-blank-line.js

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Rule to disallow consecutive blank lines.
+ * @author lumir(lumirlumir)
+ * @see https://github.com/DavidAnson/markdownlint/blob/main/lib/md012.mjs
+ */
+
+// --------------------------------------------------------------------------------
+// Import
+// --------------------------------------------------------------------------------
+
+import { isBlankLine, SkipRanges } from '../core/ast/index.js';
+import { URL_RULE_DOCS } from '../core/constants.js';
+
+// --------------------------------------------------------------------------------
+// Typedef
+// --------------------------------------------------------------------------------
+
+/**
+ * @import { RuleModule } from '../core/types.js';
+ * @typedef {[{ max: number, skipCode: boolean | string[] }]} RuleOptions
+ * @typedef {'noConsecutiveBlankLine'} MessageIds
+ */
+
+// --------------------------------------------------------------------------------
+// Rule Definition
+// --------------------------------------------------------------------------------
+
+/** @type {RuleModule<RuleOptions, MessageIds>} */
+export default {
+  meta: {
+    type: 'layout',
+
+    docs: {
+      description: 'Disallow consecutive blank lines',
+      url: URL_RULE_DOCS('no-consecutive-blank-line'),
+      recommended: false,
+      stylistic: true,
+    },
+
+    fixable: 'whitespace',
+
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          max: {
+            type: 'integer',
+            minimum: 1,
+          },
+          skipCode: {
+            oneOf: [
+              {
+                type: 'boolean',
+              },
+              {
+                type: 'array',
+                items: {
+                  type: 'string',
+                },
+                uniqueItems: true,
+              },
+            ],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+
+    defaultOptions: [
+      {
+        max: 1,
+        skipCode: true,
+      },
+    ],
+
+    messages: {
+      noConsecutiveBlankLine:
+        'More than {{ max }} consecutive blank line(s) are not allowed.',
+    },
+
+    language: 'markdown',
+
+    dialects: ['commonmark', 'gfm'],
+  },
+
+  create(context) {
+    const { options, sourceCode } = context;
+    const [{ max, skipCode }] = options;
+    const { lines, text } = sourceCode;
+
+    const skipRanges = new SkipRanges();
+
+    return {
+      code(node) {
+        if (
+          Array.isArray(skipCode) ? node.lang && skipCode.includes(node.lang) : skipCode
+        )
+          skipRanges.push(sourceCode.getRange(node)); // Store range information of `Code`.
+      },
+
+      'root:exit'() {
+        let consecutiveBlankLineCount = 0;
+
+        for (let currentLineIdx = 0; currentLineIdx < lines.length; currentLineIdx++) {
+          const startLoc = /** @type {const} */ ({
+            line: currentLineIdx + 1,
+            column: 1,
+          });
+          const endLoc = /** @type {const} */ ({
+            line: currentLineIdx + 2,
+            column: 1,
+          });
+
+          if (
+            skipRanges.includes(sourceCode.getIndexFromLoc(startLoc)) ||
+            !isBlankLine(lines[currentLineIdx])
+          ) {
+            consecutiveBlankLineCount = 0;
+          } else {
+            consecutiveBlankLineCount++;
+          }
+
+          if (max < consecutiveBlankLineCount) {
+            const lastAllowedBlankLineIdx =
+              currentLineIdx - consecutiveBlankLineCount + max;
+
+            context.report({
+              loc: {
+                start: startLoc,
+                end: endLoc,
+              },
+
+              data: {
+                max,
+              },
+
+              messageId: 'noConsecutiveBlankLine',
+
+              fix(fixer) {
+                /*
+                 * When the consecutive blank-line run reaches EOF, the fixer must remove the
+                 * whole excess tail at once instead of removing only the current line.
+                 *
+                 * `currentLineIdx + 1 === lines.length` means the current line is the final
+                 * logical line in `sourceCode.lines`. In a case like `foo\n\n\n  ` with
+                 * `max: 1`, the final line is still a blank line, but it may contain spaces.
+                 * If we only remove from the current line start, those trailing spaces can
+                 * survive and produce `foo\n  ` instead of the intended `foo\n`.
+                 *
+                 * The start of the removal range is calculated from the last blank line that
+                 * is still allowed by `max`:
+                 *
+                 *   currentLineIdx - consecutiveBlankLineCount
+                 *     -> zero-based index of the first line in the current blank-line run
+                 *
+                 *   + max
+                 *     -> zero-based index of the last blank line we want to keep
+                 *
+                 *   + 1
+                 *     -> convert the zero-based line index to ESLint's one-based loc line
+                 *
+                 * The column is `lines[lastAllowedBlankLineIdx].length + 1`, which points to the
+                 * end of that allowed blank line. The range then ends at `text.length`, so
+                 * everything after the allowed blank line is removed, including remaining blank
+                 * lines, line endings, and any spaces on the final blank line.
+                 *
+                 * Example with `foo\n\n\n  ` and `max: 1`:
+                 *
+                 *   lines = ['foo', '', '', '  ']
+                 *   currentLineIdx = 3
+                 *   consecutiveBlankLineCount = 3
+                 *   max = 1
+                 *
+                 *   lastAllowedBlankLineIdx = 3 - 3 + 1 = 1
+                 *
+                 * So the fixer removes from the end of line 2 to EOF, producing `foo\n`.
+                 */
+                if (currentLineIdx + 1 === lines.length) {
+                  return fixer.removeRange([
+                    sourceCode.getIndexFromLoc({
+                      line: lastAllowedBlankLineIdx + 1,
+                      column: lines[lastAllowedBlankLineIdx].length + 1,
+                    }),
+                    text.length,
+                  ]);
+                } else {
+                  return fixer.removeRange([
+                    sourceCode.getIndexFromLoc(startLoc),
+                    sourceCode.getIndexFromLoc(endLoc),
+                  ]);
+                }
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/no-control-character.js

@@ -17,7 +17,7 @@ import { URL_RULE_DOCS } from '../core/constants.js';
 /**
  * @import { RuleModule } from '../core/types.js';
  * @typedef {[{ allow: string[], skipCode: boolean | string[], skipInlineCode: boolean }]} RuleOptions
- * @typedef {'noControlCharacter'} MessageIds
+ * @typedef {'noControlCharacter' | 'suggestRemove'} MessageIds
  */
 
 // --------------------------------------------------------------------------------
@@ -43,6 +43,8 @@ export default {
       stylistic: false,
     },
 
+    hasSuggestions: true,
+
     schema: [
       {
         type: 'object',
@@ -86,6 +88,7 @@ export default {
 
     messages: {
       noControlCharacter: 'Control character `{{ controlCharacter }}` is not allowed.',
+      suggestRemove: 'Remove control character `{{ controlCharacter }}`.',
     },
 
     language: 'markdown',
@@ -124,6 +127,8 @@ export default {
 
           if (skipRanges.includes(startOffset)) continue;
 
+          const controlCharacterCode = `U+${controlCharacter.codePointAt(0)?.toString(16).toUpperCase().padStart(4, '0')}`;
+
           context.report({
             loc: {
               start: sourceCode.getLocFromIndex(startOffset),
@@ -131,10 +136,24 @@ export default {
             },
 
             data: {
-              controlCharacter: `U+${controlCharacter.codePointAt(0)?.toString(16).toUpperCase().padStart(4, '0')}`,
+              controlCharacter: controlCharacterCode,
             },
 
             messageId: 'noControlCharacter',
+
+            suggest: [
+              {
+                messageId: 'suggestRemove',
+
+                data: {
+                  controlCharacter: controlCharacterCode,
+                },
+
+                fix(fixer) {
+                  return fixer.removeRange([startOffset, endOffset]);
+                },
+              },
+            ],
           });
         }
       },

package/src/rules/require-heading-id.js

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Rule to enforce the use of heading IDs.
+ * @author lumir(lumirlumir)
+ */
+
+// --------------------------------------------------------------------------------
+// Import
+// --------------------------------------------------------------------------------
+
+import { escapeStringRegexp } from '../core/ast/index.js';
+import { URL_RULE_DOCS } from '../core/constants.js';
+
+// --------------------------------------------------------------------------------
+// Typedef
+// --------------------------------------------------------------------------------
+
+/**
+ * @import { Heading } from 'mdast';
+ * @import { RuleModule } from '../core/types.js';
+ * @typedef {['always' | 'never', { leftDelimiter: string, rightDelimiter: string, allowDepths: Heading['depth'][] }]} RuleOptions
+ * @typedef {'headingIdAlways' | 'headingIdNever'} MessageIds
+ */
+
+// --------------------------------------------------------------------------------
+// Rule Definition
+// --------------------------------------------------------------------------------
+
+/** @type {RuleModule<RuleOptions, MessageIds>} */
+export default {
+  meta: {
+    type: 'problem',
+
+    docs: {
+      description: 'Enforce the use of heading IDs',
+      url: URL_RULE_DOCS('require-heading-id'),
+      recommended: false,
+      stylistic: false,
+    },
+
+    fixable: 'code',
+
+    schema: [
+      {
+        enum: ['always', 'never'],
+      },
+      {
+        type: 'object',
+        properties: {
+          leftDelimiter: {
+            type: 'string',
+          },
+          rightDelimiter: {
+            type: 'string',
+          },
+          allowDepths: {
+            type: 'array',
+            items: {
+              enum: [1, 2, 3, 4, 5, 6],
+            },
+            uniqueItems: true,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+
+    defaultOptions: [
+      'always',
+      {
+        leftDelimiter: '{',
+        rightDelimiter: '}',
+        allowDepths: [],
+      },
+    ],
+
+    messages: {
+      headingIdAlways: 'Headings should have an ID attribute.',
+      headingIdNever:
+        'Headings should not have an ID attribute. Remove the `{{ headingId }}`.',
+    },
+
+    language: 'markdown',
+
+    dialects: ['commonmark', 'gfm'],
+  },
+
+  create(context) {
+    const { sourceCode } = context;
+    const [mode, { leftDelimiter, rightDelimiter, allowDepths }] = context.options;
+
+    const escapedLeftDelimiter = escapeStringRegexp(leftDelimiter);
+    const escapedRightDelimiter = escapeStringRegexp(rightDelimiter);
+
+    /**
+     * We don't use the `[ \t]*$` pattern at the end of the regex because trailing
+     * whitespace is already removed from a `heading` node's child `text` node.
+     */
+    const headingIdRegex = new RegExp(
+      `(?<leadingSpaces>[ \t]+)(?<headingId>${escapedLeftDelimiter}#[^${escapedRightDelimiter}]+${escapedRightDelimiter})$`,
+    );
+
+    return {
+      heading(node) {
+        // If the heading's depth is included in `allowDepths`, skip it.
+        if (allowDepths.includes(node.depth)) {
+          return;
+        }
+
+        /*
+         * Instead of using deep recursive traversal to find the final `text` node,
+         * we simply access the node's last child directly with shallow traversal.
+         *
+         * This is because in the "Not OK" case, the `text` node is located
+         * in the last position while DFS(Depth First Search) traversal,
+         * but is located under `emphasis` or `strong` nodes.
+         *
+         * This is the situation we don't want to support.
+         * There must be pure ` #{custom-id}` text at the end of the heading
+         * without being wrapped by other nodes.
+         *
+         * OK:
+         *
+         * ```md
+         * # heading {#custom-id}
+         * ```
+         *
+         * Not OK:
+         *
+         * ```md
+         * # heading *{#custom-id}*
+         *           ^            ^
+         *
+         * # heading **{#custom-id}**
+         *           ^^            ^^
+         * ```
+         */
+        const lastChildNode = node.children.at(-1);
+
+        /*
+         * ATX headings and closed ATX headings that contain no content have no child nodes.
+         *
+         * ATX Headings:
+         *
+         * ```md
+         * #
+         *
+         * ##
+         *
+         * ###
+         * ```
+         *
+         * ATX Closed Headings:
+         *
+         * ```md
+         * # #
+         *
+         * ## ##
+         *
+         * ### ###
+         * ```
+         */
+        if (!lastChildNode) {
+          // If there are no child nodes, intentionally skip it.
+          // This is not the part we want to report.
+          return;
+        }
+
+        /*
+         * Missing heading IDs are reported on the last character of the last child
+         * node rather than as a zero-width location (i.e. `column === endColumn`)
+         * at the end of that node, because some editors such as VSCode render
+         * zero-width diagnostics incorrectly.
+         */
+        const [lastChildNodeStartOffset, lastChildNodeEndOffset] =
+          sourceCode.getRange(lastChildNode);
+
+        // If the last child node is not a `text` node, report an error.
+        if (lastChildNode.type !== 'text') {
+          if (mode === 'always') {
+            context.report({
+              loc: {
+                start: sourceCode.getLocFromIndex(lastChildNodeEndOffset - 1),
+                end: sourceCode.getLocFromIndex(lastChildNodeEndOffset),
+              },
+
+              messageId: 'headingIdAlways',
+            });
+          }
+
+          return;
+        }
+
+        const match = headingIdRegex.exec(sourceCode.getText(lastChildNode));
+
+        if (!match || !match.groups) {
+          if (mode === 'always') {
+            context.report({
+              loc: {
+                start: sourceCode.getLocFromIndex(lastChildNodeEndOffset - 1),
+                end: sourceCode.getLocFromIndex(lastChildNodeEndOffset),
+              },
+
+              messageId: 'headingIdAlways',
+            });
+          }
+
+          return;
+        }
+
+        if (mode === 'never') {
+          const { leadingSpaces, headingId } = match.groups;
+          const leadingSpacesStartOffset = lastChildNodeStartOffset + match.index;
+          const headingIdStartOffset = leadingSpacesStartOffset + leadingSpaces.length;
+          const headingIdEndOffset = headingIdStartOffset + headingId.length;
+
+          context.report({
+            loc: {
+              start: sourceCode.getLocFromIndex(headingIdStartOffset),
+              end: sourceCode.getLocFromIndex(headingIdEndOffset),
+            },
+
+            data: {
+              headingId,
+            },
+
+            messageId: 'headingIdNever',
+
+            fix(fixer) {
+              return fixer.replaceTextRange(
+                [leadingSpacesStartOffset, headingIdEndOffset],
+                '',
+              );
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/src/rules/heading-id.js

@@ -1,153 +0,0 @@
-/**
- * @fileoverview Rule to enforce the use of heading IDs.
- * @author lumir(lumirlumir)
- */
-
-// @ts-nocheck -- TODO
-
-// --------------------------------------------------------------------------------
-// Import
-// --------------------------------------------------------------------------------
-
-import { URL_RULE_DOCS } from '../core/constants.js';
-
-// --------------------------------------------------------------------------------
-// Typedefs
-// --------------------------------------------------------------------------------
-
-/**
- * @import { Heading } from 'mdast';
- * @import { RuleModule } from '../core/types.js';
- * @typedef {['always' | 'never', { leftDelimiter: string, rightDelimiter: string, ignoreDepth: Heading['depth'][] }]} RuleOptions
- * @typedef {'headingIdAlways' | 'headingIdNever'} MessageIds
- */
-
-// --------------------------------------------------------------------------------
-// Rule Definition
-// --------------------------------------------------------------------------------
-
-/** @type {RuleModule<RuleOptions, MessageIds>} */
-export default {
-  meta: {
-    type: 'problem',
-
-    docs: {
-      description: 'Enforce the use of heading IDs',
-      url: URL_RULE_DOCS('heading-id'),
-      recommended: false,
-      stylistic: false,
-    },
-
-    fixable: 'code',
-
-    schema: [
-      {
-        enum: ['always', 'never'],
-      },
-      {
-        type: 'object',
-        properties: {
-          leftDelimiter: {
-            type: 'string',
-          },
-          rightDelimiter: {
-            type: 'string',
-          },
-          ignoreDepth: {
-            type: 'array',
-            items: {
-              enum: [1, 2, 3, 4, 5, 6],
-            },
-            uniqueItems: true,
-          },
-        },
-        additionalProperties: false,
-      },
-    ],
-
-    defaultOptions: [
-      'always',
-      {
-        leftDelimiter: '{',
-        rightDelimiter: '}',
-        ignoreDepth: [],
-      },
-    ],
-
-    messages: {
-      headingIdAlways: 'Headings should have an ID attribute.',
-      headingIdNever:
-        'Headings should not have an ID attribute. Remove the `{{ headingId }}`.',
-    },
-
-    language: 'markdown',
-
-    dialects: ['commonmark', 'gfm'],
-  },
-
-  create(context) {
-    return {
-      heading(node) {
-        const [mode, { leftDelimiter, rightDelimiter, ignoreDepth }] = context.options;
-
-        if (ignoreDepth.includes(node.depth)) return;
-
-        const regex = new RegExp(
-          `${leftDelimiter}#[^${rightDelimiter}]+${rightDelimiter}[ \t]*$`,
-        );
-        const match = context.sourceCode.getText(node).match(regex);
-
-        if (mode === 'always' && match === null) {
-          context.report({
-            loc: {
-              start: {
-                line: node.position.start.line,
-                column: node.position.end.column,
-              },
-              end: {
-                line: node.position.start.line,
-                column: node.position.end.column,
-              },
-            },
-
-            messageId: 'headingIdAlways',
-          });
-        } else if (mode === 'never' && match !== null) {
-          const headingIdLength = match[0].length;
-
-          const matchIndexStart = match.index;
-          const matchIndexEnd = matchIndexStart + headingIdLength;
-
-          context.report({
-            loc: {
-              start: {
-                line: node.position.start.line,
-                column: node.position.start.column + matchIndexStart,
-              },
-              end: {
-                line: node.position.start.line,
-                column: node.position.start.column + matchIndexEnd,
-              },
-            },
-
-            data: {
-              headingId: match[0],
-            },
-
-            messageId: 'headingIdNever',
-
-            fix(fixer) {
-              return fixer.replaceTextRange(
-                [
-                  node.position.start.offset + matchIndexStart,
-                  node.position.start.offset + matchIndexEnd,
-                ],
-                '',
-              );
-            },
-          });
-        }
-      },
-    };
-  },
-};