@tony.ganchev/eslint-plugin-header 3.2.5 → 3.3.0

package/lib/rules/header.js

@@ -33,8 +33,9 @@ const { description, recommended } = require("./header.docs");
 const { lineEndingOptions, commentTypeOptions, schema } = require("./header.schema");
 
 /**
- * @import { Linter, Rule } from "eslint"
- * @import { Comment, SourceLocation, Program } from "estree"
+ * @import { JSSyntaxElement, Linter, Rule, SourceCode } from "eslint"
+ * @import { Comment, SourceLocation } from "estree"
+ * @import { ViolationReport } from "@eslint/core";
  * @typedef {Rule.NodeListener} NodeListener
  * @typedef {Rule.ReportFixer} ReportFixer
  * @typedef {Rule.RuleFixer} RuleFixer
@@ -88,6 +89,14 @@ const { lineEndingOptions, commentTypeOptions, schema } = require("./header.sche
  * lines together.
  */
 
+/**
+ * @typedef {object} LeadingComments A set of comments that can appear before
+ * the header.
+ * @property {(FileBasedConfig | InlineConfig)[]} comments The set of comments
+ * that are allowed. If none of the matching rules matches the first comment the
+ * rule assumes the first comment *is* the header.
+ */
+
 /**
  * @typedef {object} TrailingEmptyLines Rule configuration on the handling of
  * empty lines after the header comment.
@@ -99,6 +108,9 @@ const { lineEndingOptions, commentTypeOptions, schema } = require("./header.sche
  * @typedef {object} HeaderOptionsWithoutSettings
  * @property {FileBasedConfig | InlineConfig} header The text matching rules
  * for the header.
+ * @property {LeadingComments} [leadingComments] The set of allowed comments to
+ * precede the header. Useful to allow position-sensitive pragma comments for
+ * certain tools.
  * @property {TrailingEmptyLines} [trailingEmptyLines] Rules about empty lines
  * after the header comment.
  */
@@ -167,67 +179,66 @@ function match(actual, expected) {
 }
 
 /**
- * Remove Unix she-bangs from the list of comments.
- * @param {(Comment | { type: "Shebang" })[]} comments The list of comment
- * lines.
- * @returns {Comment[]} The list of comments with containing all incoming
- * comments from `comments` with the shebang comments omitted.
+ * Returns an array of comment groups before the actual code.
+ * Block comments form single-element groups.
+ * Line comments without empty lines between them form grouped elements.
+ * @param {SourceCode} sourceCode AST.
+ * @returns {Comment[][]} Array of groups of leading comments.
  */
-function excludeShebangs(comments) {
+function getLeadingComments(sourceCode) {
+    const all = sourceCode.getAllComments();
+    if (all.length === 0) {
+        return [];
+    }
+    // Determine where the actual code starts. If no code, use end of file.
+    const firstToken = sourceCode.getFirstToken(sourceCode.ast);
+    const codeStart = firstToken ? firstToken.range[0] : sourceCode.text.length;
+    // Filter comments that appear before the actual code starts.
+    const commentsBeforeCode = all.filter((c) => /** @type {[number, number]} */(c.range)[1] <= codeStart);
+    if (commentsBeforeCode.length === 0) {
+        return [];
+    }
+    /** @type {Comment[][]} */
+    const groups = [];
     /** @type {Comment[]} */
-    return comments.filter(function(comment) {
-        return comment.type !== "Shebang";
-    });
-}
-
-/**
- * TypeScript helper to confirm defined type.
- * @template T Target type to validate for definiteness.
- * @param {T | undefined} val The value to validate.
- * @returns {asserts val is T} Validates defined type.
- */
-function assertDefined(val) {
-    assert.strict.notEqual(typeof val, "undefined");
-}
+    let currentGroup = [];
+    for (let i = 0; i < commentsBeforeCode.length; ++i) {
+        const comment = commentsBeforeCode[i];
 
-/**
- * TypeScript helper to confirm non-null type.
- * @template T Target type to validate is non-null.
- * @param {T | null} val The value to validate.
- * @returns {asserts val is T} Validates non-null type.
- */
-function assertNotNull(val) {
-    assert.strict.notEqual(val, null);
-}
+        if (comment.type === "Block") {
+            // Push any existing current group first
+            if (currentGroup.length > 0) {
+                groups.push(currentGroup);
+                currentGroup = [];
+            }
+            groups.push([comment]);
+        } else {
+            if (currentGroup.length === 0) {
+                currentGroup.push(comment);
+            } else {
+                const previous = currentGroup[currentGroup.length - 1];
+                const previousRange = /** @type {[number, number]} */ (previous.range);
+                const currentRange = /** @type {[number, number]} */ (comment.range);
+                const txt = sourceCode.text.slice(previousRange[1], currentRange[0]);
 
-/**
- * Returns either the first block comment or the first set of line comments that
- * are ONLY separated by a single newline. Note that this does not actually
- * check if they are at the start of the file since that is already checked by
- * `hasHeader()`.
- * @param {RuleContext} context ESLint execution environment.
- * @returns {Comment[]} Lines That constitute the leading comment.
- */
-function getLeadingComments(context) {
-    const sourceCode = contextSourceCode(context);
-    const all = excludeShebangs(sourceCode.getAllComments());
-    assert.ok(all);
-    assert.ok(all.length);
-    if (all[0].type.toLowerCase() === commentTypeOptions.block) {
-        return [all[0]];
-    }
-    let i = 1;
-    for (; i < all.length; ++i) {
-        const previousRange = all[i - 1].range;
-        assertDefined(previousRange);
-        const currentRange = all[i].range;
-        assertDefined(currentRange);
-        const txt = sourceCode.text.slice(previousRange[1], currentRange[0]);
-        if (!txt.match(/^(\r\n|\r|\n)$/)) {
-            break;
+                // If there is more than 1 newline, there is an empty line
+                // between comments.
+                const newlineCount = /** @type {RegExpMatchArray} */ (txt.match(/\r?\n/g)).length;
+                if (newlineCount <= 1) {
+                    currentGroup.push(comment);
+                } else {
+                    groups.push(currentGroup);
+                    currentGroup = [comment];
+                }
+            }
         }
     }
-    return all.slice(0, i);
+
+    if (currentGroup.length > 0) {
+        groups.push(currentGroup);
+    }
+
+    return groups;
 }
 
 /**
@@ -257,14 +268,10 @@ function genCommentBody(commentType, textArray, eol) {
 function genCommentsRange(comments) {
     assert.ok(comments.length);
     const firstComment = comments[0];
-    assertDefined(firstComment);
-    const firstCommentRange = firstComment.range;
-    assertDefined(firstCommentRange);
+    const firstCommentRange = /** @type {[number, number]} */ (firstComment.range);
     const start = firstCommentRange[0];
     const lastComment = comments.slice(-1)[0];
-    assertDefined(lastComment);
-    const lastCommentRange = lastComment.range;
-    assertDefined(lastCommentRange);
+    const lastCommentRange = /** @type {[number, number]} */ (lastComment.range);
     const end = lastCommentRange[1];
     return [start, end];
 }
@@ -292,17 +299,16 @@ function leadingEmptyLines(src) {
 /**
  * Factory for fixer that adds a missing header.
  * @param {CommentType} commentType Type of comment to use.
- * @param {RuleContext} context ESLint execution runtime.
+ * @param {SourceCode} sourceCode AST.
  * @param {string[]} headerLines Lines of the header comment.
  * @param {LineEnding} eol End-of-line characters.
  * @param {number} numNewlines Number of trailing lines after the comment.
  * @returns {ReportFixer} The fix to apply.
  */
-function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
-    return function(fixer) {
+function genPrependFixer(commentType, sourceCode, headerLines, eol, numNewlines) {
+    return function (fixer) {
         let insertPos = 0;
         let newHeader = genCommentBody(commentType, headerLines, eol);
-        const sourceCode = contextSourceCode(context);
         if (sourceCode.text.startsWith("#!")) {
             const firstNewLinePos = sourceCode.text.indexOf("\n");
             insertPos = firstNewLinePos === -1 ? sourceCode.text.length : firstNewLinePos + 1;
@@ -323,17 +329,17 @@ function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
 /**
  * Factory for fixer that replaces an incorrect header.
  * @param {CommentType} commentType Type of comment to use.
- * @param {RuleContext} context ESLint execution context.
+ * @param {SourceCode} sourceCode AST.
  * @param {Comment[]} leadingComments Comment elements to replace.
  * @param {string[]} headerLines Lines of the header comment.
  * @param {LineEnding} eol End-of-line characters.
  * @param {number} numNewlines Number of trailing lines after the comment.
  * @returns {ReportFixer} The fix to apply.
  */
-function genReplaceFixer(commentType, context, leadingComments, headerLines, eol, numNewlines) {
-    return function(fixer) {
+function genReplaceFixer(commentType, sourceCode, leadingComments, headerLines, eol, numNewlines) {
+    return function (fixer) {
         const commentRange = genCommentsRange(leadingComments);
-        const emptyLines = leadingEmptyLines(contextSourceCode(context).text.substring(commentRange[1]));
+        const emptyLines = leadingEmptyLines(sourceCode.text.substring(commentRange[1]));
         const missingNewlines = Math.max(0, numNewlines - emptyLines);
         const eols = eol.repeat(missingNewlines);
         return fixer.replaceTextRange(
@@ -352,7 +358,7 @@ function genReplaceFixer(commentType, context, leadingComments, headerLines, eol
  * @returns {ReportFixer} The fix to apply.
  */
 function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
-    return function(fixer) {
+    return function (fixer) {
         return fixer.insertTextAfterRange(
             genCommentsRange(leadingComments),
             eol.repeat(missingEmptyLinesCount)
@@ -380,17 +386,6 @@ function getEol(style) {
     }
 }
 
-/**
- * Tests if the first line in the source code (after a Unix she-bang) is a
- * comment. Does not tolerate empty lines before the first match.
- * @param {string} src Source code to test.
- * @returns {boolean} `true` if there is a comment or `false` otherwise.
- */
-function hasHeader(src) {
-    const srcWithoutShebang = src.replace(/^#![^\n]*\r?\n/, "");
-    return srcWithoutShebang.startsWith("/*") || srcWithoutShebang.startsWith("//");
-}
-
 /**
  * Asserts on an expression and adds template texts to the failure message.
  * Helper to write cleaner code.
@@ -462,14 +457,14 @@ function transformLegacyOptions(originalOptions) {
             transformedOptions.trailingEmptyLines = { minimum: originalOptions[2] };
             if (originalOptions.length === 4) {
                 schemaAssert(typeof originalOptions[3] === "object",
-                    "Fourth header option after severity should be either number of required trailing empty lines or " +
-                    "a settings object");
+                    "Fourth header option after severity should be either number of required trailing empty lines or "
+                    + "a settings object");
                 Object.assign(transformedOptions, originalOptions[3]);
             }
         } else {
             schemaAssert(typeof originalOptions[2] === "object",
-                "Third header option after severity should be either number of required trailing empty lines or a " +
-                "settings object");
+                "Third header option after severity should be either number of required trailing empty lines or a "
+                + "settings object");
             Object.assign(transformedOptions, originalOptions[2]);
         }
     }
@@ -483,35 +478,23 @@ function transformLegacyOptions(originalOptions) {
  * else `false`.
  */
 function isFileBasedHeaderConfig(config) {
-    return Object.prototype.hasOwnProperty.call(config, "file");
+    return "file" in config;
 }
 
 /**
- * Type guard for `InlineConfig`.
- * @param {FileBasedConfig | InlineConfig} config The header configuration.
- * @returns {asserts config is InlineConfig} Asserts `config` is
- * `LineBasedConfig`.
+ * Transforms file template-based matching rules to inline rules for further
+ * use.
+ * @param {FileBasedConfig | InlineConfig} matcher The matching rule.
+ * @returns {InlineConfig} The resulting normalized configuration.
  */
-function assertLineBasedHeaderConfig(config) {
-    assert.ok(Object.prototype.hasOwnProperty.call(config, "lines"));
-}
-
-/**
- * Transforms a set of new-style options adding defaults and standardizing on
- * one of multiple config styles.
- * @param {HeaderOptions} originalOptions New-style options to normalize.
- * @returns {HeaderOptions} Normalized options.
- */
-function normalizeOptions(originalOptions) {
-    const options = structuredClone(originalOptions);
-
-    if (isFileBasedHeaderConfig(originalOptions.header)) {
-        const text = fs.readFileSync(originalOptions.header.file, originalOptions.header.encoding || "utf8");
+function normalizeMatchingRules(matcher) {
+    if (isFileBasedHeaderConfig(matcher)) {
+        const text = fs.readFileSync(matcher.file, matcher.encoding || "utf8");
         const [commentType, lines] = commentParser(text);
-        options.header = { commentType, lines };
+        return { commentType, lines };
     }
-    assertLineBasedHeaderConfig(options.header);
-    options.header.lines = options.header.lines.flatMap(
+    const commentType = matcher.commentType;
+    const lines = matcher.lines.flatMap(
         (line) => {
             if (typeof line === "string") {
                 return /** @type {HeaderLine[]} */(line.split(/\r?\n/));
@@ -529,11 +512,31 @@ function normalizeOptions(originalOptions) {
             }
             return [{ pattern }];
         });
+    return { commentType, lines };
+}
+
+/**
+ * Transforms a set of new-style options adding defaults and standardizing on
+ * one of multiple config styles.
+ * @param {HeaderOptions} originalOptions New-style options to normalize.
+ * @returns {HeaderOptions} Normalized options.
+ */
+function normalizeOptions(originalOptions) {
+    const options = structuredClone(originalOptions);
+
+    options.header = normalizeMatchingRules(originalOptions.header);
 
     if (!options.lineEndings) {
         options.lineEndings = "os";
     }
 
+    if (originalOptions.leadingComments) {
+        options.leadingComments = {
+            comments: originalOptions.leadingComments.comments.map((c) => normalizeMatchingRules(c))
+        };
+    } else {
+        options.leadingComments = { comments: [] };
+    }
     if (!options.trailingEmptyLines) {
         options.trailingEmptyLines = {};
     }
@@ -558,9 +561,7 @@ function normalizeOptions(originalOptions) {
  */
 function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
     assert.ok(leadingComments);
-    const loc = leadingComments[leadingComments.length - 1].loc;
-    assertDefined(loc);
-    assertNotNull(loc);
+    const loc = /** @type {SourceLocation} */ (leadingComments[leadingComments.length - 1].loc);
     const lastCommentLineLocEnd = loc.end;
     return {
         start: lastCommentLineLocEnd,
@@ -571,6 +572,322 @@ function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
     };
 }
 
+/**
+ * Matches comments against of header content-matching rules. An object performs
+ * a number of expensive operations only once and thus can be used multiple
+ * times to test different comments.
+ */
+class CommentMatcher {
+    /**
+     * Initializes the matcher for a specific comment-matching rules.
+     * @param {InlineConfig} headerConfig Content-matching rules.
+     * @param {string} eol The EOL characters used.
+     * @param {number} numLines The requirred minimum number of trailing empty
+     * lines.
+     */
+    constructor(headerConfig, eol, numLines) {
+        this.commentType = headerConfig.commentType;
+        this.headerLines = headerConfig.lines.map((line) => isPattern(line) ? line.pattern : line);
+        this.eol = eol;
+        this.numLines = numLines;
+    }
+
+    /**
+     * @typedef {ViolationReport<JSSyntaxElement, string>} ViolationReportBad
+     * @typedef {ViolationReportBad & { messageId: string }} ViolationReportEx
+     */
+
+    /**
+     * Performs a validation of a comment against a header matching
+     * configuration.
+     * @param {Comment[]} leadingComments The block comment or sequence of line
+     * comments to test.
+     * @param {SourceCode} sourceCode The source code AST.
+     * @returns {ViolationReportEx | null} If set a
+     * violation report to pass back to ESLint or interpret as necessary.
+     */
+    validate(leadingComments, sourceCode) {
+
+        const firstLeadingCommentLoc = /** @type {SourceLocation} */ (leadingComments[0].loc);
+        const firstLeadingCommentRange = /** @type {[number, number]} */ (leadingComments[0].range);
+
+        const lastLeadingCommentLoc = /** @type {SourceLocation} */ (leadingComments[leadingComments.length - 1].loc);
+
+        if (leadingComments[0].type.toLowerCase() !== this.commentType) {
+            return {
+                loc: {
+                    start: firstLeadingCommentLoc.start,
+                    end: lastLeadingCommentLoc.end
+                },
+                messageId: "incorrectCommentType",
+                data: {
+                    commentType: this.commentType
+                },
+            };
+        }
+        if (this.commentType === commentTypeOptions.line) {
+            if (this.headerLines.length === 1) {
+                const leadingCommentValues = leadingComments.map((c) => c.value);
+                if (
+                    !match(leadingCommentValues.join("\n"), this.headerLines[0])
+                    && !match(leadingCommentValues.join("\r\n"), this.headerLines[0])
+                ) {
+                    return {
+                        loc: {
+                            start: firstLeadingCommentLoc.start,
+                            end: lastLeadingCommentLoc.end
+                        },
+                        messageId: "incorrectHeader",
+                        data: {
+                            pattern: this.headerLines[0].toString()
+                        }
+                    };
+                }
+            } else {
+                for (let i = 0; i < this.headerLines.length; i++) {
+                    if (leadingComments.length - 1 < i) {
+                        return {
+                            loc: {
+                                start: lastLeadingCommentLoc.end,
+                                end: lastLeadingCommentLoc.end
+                            },
+                            messageId: "headerTooShort",
+                            data: {
+                                remainder: this.headerLines.slice(i).join(this.eol)
+                            },
+                        };
+                    }
+                    const headerLine = this.headerLines[i];
+                    const comment = leadingComments[i];
+                    const commentLoc = /** @type {SourceLocation} */ (comment.loc);
+                    if (typeof headerLine === "string") {
+                        const leadingCommentLength = comment.value.length;
+                        const headerLineLength = headerLine.length;
+                        for (let j = 0; j < Math.min(leadingCommentLength, headerLineLength); j++) {
+                            if (comment.value[j] !== headerLine[j]) {
+                                return {
+                                    loc: {
+                                        start: {
+                                            column: "//".length + j,
+                                            line: commentLoc.start.line
+                                        },
+                                        end: commentLoc.end
+                                    },
+                                    messageId: "headerLineMismatchAtPos",
+                                    data: {
+                                        expected: headerLine.substring(j)
+                                    },
+                                };
+                            }
+                        }
+                        if (leadingCommentLength < headerLineLength) {
+                            return {
+                                loc: {
+                                    start: commentLoc.end,
+                                    end: commentLoc.end,
+                                },
+                                messageId: "headerLineTooShort",
+                                data: {
+                                    remainder: headerLine.substring(leadingCommentLength)
+                                },
+                            };
+                        }
+                        if (leadingCommentLength > headerLineLength) {
+                            return {
+                                loc: {
+                                    start: {
+                                        column: "//".length + headerLineLength,
+                                        line: commentLoc.start.line
+                                    },
+                                    end: commentLoc.end,
+                                },
+                                messageId: "headerLineTooLong",
+                            };
+                        }
+                    } else {
+                        if (!match(comment.value, headerLine)) {
+                            return {
+                                loc: {
+                                    start: {
+                                        column: "//".length,
+                                        line: commentLoc.start.line,
+                                    },
+                                    end: commentLoc.end,
+                                },
+                                messageId: "incorrectHeaderLine",
+                                data: {
+                                    pattern: headerLine.toString()
+                                },
+                            };
+                        }
+                    }
+                }
+            }
+
+            const commentRange = /** @type {[number, number]} */ (leadingComments[this.headerLines.length - 1].range);
+            const actualLeadingEmptyLines = leadingEmptyLines(sourceCode.text.substring(commentRange[1]));
+            const missingEmptyLines = this.numLines - actualLeadingEmptyLines;
+            if (missingEmptyLines > 0) {
+                return {
+                    loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
+                    messageId: "noNewlineAfterHeader",
+                    data: {
+                        expected: this.numLines,
+                        actual: actualLeadingEmptyLines
+                    },
+                };
+            }
+
+            return null;
+        }
+        // if block comment pattern has more than 1 line, we also split the
+        // comment
+        let leadingLines = [leadingComments[0].value];
+        if (this.headerLines.length > 1) {
+            leadingLines = leadingComments[0].value.split(/\r?\n/);
+        }
+
+        /** @type {null | string} */
+        let errorMessageId = null;
+        /** @type {undefined | Record<string, string>} */
+        let errorMessageData;
+        /** @type {null | SourceLocation} */
+        let errorMessageLoc = null;
+        for (let i = 0; i < this.headerLines.length; i++) {
+            if (leadingLines.length - 1 < i) {
+                return {
+                    loc: {
+                        start: lastLeadingCommentLoc.end,
+                        end: lastLeadingCommentLoc.end
+                    },
+                    messageId: "headerTooShort",
+                    data: {
+                        remainder: this.headerLines.slice(i).join(this.eol)
+                    },
+                };
+            }
+            const leadingLine = leadingLines[i];
+            const headerLine = this.headerLines[i];
+            if (typeof headerLine === "string") {
+                for (let j = 0; j < Math.min(leadingLine.length, headerLine.length); j++) {
+                    if (leadingLine[j] !== headerLine[j]) {
+                        errorMessageId = "headerLineMismatchAtPos";
+                        const columnOffset = i === 0 ? "/*".length : 0;
+                        const line = firstLeadingCommentLoc.start.line + i;
+                        errorMessageLoc = {
+                            start: {
+                                column: columnOffset + j,
+                                line
+                            },
+                            end: {
+                                column: columnOffset + leadingLine.length,
+                                line
+                            }
+                        };
+                        errorMessageData = {
+                            expected: headerLine.substring(j)
+                        };
+                        break;
+                    }
+                }
+                if (errorMessageId) {
+                    break;
+                }
+                if (leadingLine.length < headerLine.length) {
+                    errorMessageId = "headerLineTooShort";
+                    const startColumn = (i === 0 ? "/*".length : 0) + leadingLine.length;
+                    errorMessageLoc = {
+                        start: {
+                            column: startColumn,
+                            line: firstLeadingCommentLoc.start.line + i
+                        },
+                        end: {
+                            column: startColumn + 1,
+                            line: firstLeadingCommentLoc.start.line + i
+                        }
+                    };
+                    errorMessageData = {
+                        remainder: headerLine.substring(leadingLine.length)
+                    };
+                    break;
+                }
+                if (leadingLine.length > headerLine.length) {
+                    errorMessageId = "headerLineTooLong";
+                    errorMessageLoc = {
+                        start: {
+                            column: (i === 0 ? "/*".length : 0) + headerLine.length,
+                            line: firstLeadingCommentLoc.start.line + i
+                        },
+                        end: {
+                            column: (i === 0 ? "/*".length : 0) + leadingLine.length,
+                            line: firstLeadingCommentLoc.start.line + i
+                        }
+                    };
+                    break;
+                }
+            } else {
+                if (!match(leadingLine, headerLine)) {
+                    errorMessageId = "incorrectHeaderLine";
+                    errorMessageData = {
+                        pattern: headerLine.toString()
+                    };
+                    const columnOffset = i === 0 ? "/*".length : 0;
+                    errorMessageLoc = {
+                        start: {
+                            column: columnOffset + 0,
+                            line: firstLeadingCommentLoc.start.line + i
+                        },
+                        end: {
+                            column: columnOffset + leadingLine.length,
+                            line: firstLeadingCommentLoc.start.line + i
+                        }
+                    };
+                    break;
+                }
+            }
+        }
+
+        if (!errorMessageId && leadingLines.length > this.headerLines.length) {
+            errorMessageId = "headerTooLong";
+            errorMessageLoc = {
+                start: {
+                    column: (this.headerLines.length === 0 ? "/*".length : 0) + 0,
+                    line: firstLeadingCommentLoc.start.line + this.headerLines.length
+                },
+                end: {
+                    column: lastLeadingCommentLoc.end.column - "*/".length,
+                    line: lastLeadingCommentLoc.end.line
+                }
+            };
+        }
+
+        if (errorMessageId) {
+            return {
+                loc: /** @type {SourceLocation} */ (errorMessageLoc),
+                messageId: errorMessageId,
+                data: errorMessageData,
+            };
+        }
+
+        const actualLeadingEmptyLines =
+            leadingEmptyLines(sourceCode.text.substring(firstLeadingCommentRange[1]));
+        const missingEmptyLines = this.numLines - actualLeadingEmptyLines;
+        if (missingEmptyLines > 0) {
+            return {
+                loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
+                messageId: "noNewlineAfterHeader",
+                data: {
+                    expected: this.numLines,
+                    actual: actualLeadingEmptyLines
+                },
+            };
+        }
+
+        return null;
+    }
+}
+
+
 /** @type {Rule.RuleModule} */
 const headerRule = {
     meta: {
@@ -591,14 +908,33 @@ const headerRule = {
             }
         ],
         messages: {
-            headerLineMismatchAtPos: "header line does not match expected after this position; expected: {{expected}}",
+            // messages customized for header validation.
+            headerLineMismatchAtPos:
+                "header line does not match expected after this position; expected: '{{expected}}'",
             headerLineTooLong: "header line longer than expected",
-            headerLineTooShort: "header line shorter than expected; missing: {{remainder}}",
-            headerTooShort: "header too short: missing lines: {{remainder}}",
+            headerLineTooShort: "header line shorter than expected; missing: '{{remainder}}'",
+            headerTooShort: "header too short; missing lines: '{{remainder}}'",
             headerTooLong: "header too long",
             incorrectCommentType: "header should be a {{commentType}} comment",
-            incorrectHeader: "incorrect header",
-            incorrectHeaderLine: "header line does not match pattern: {{pattern}}",
+            incorrectHeader: "header does not match pattern: '{{pattern}}'",
+            incorrectHeaderLine: "header line does not match pattern: '{{pattern}}'",
+            // messages customized for leading comments validation.
+            "leadingComment-headerLineMismatchAtPos":
+                "leading comment validation failed: line does not match expected after this position; "
+                + "expected: '{{expected}}'",
+            "leadingComment-headerLineTooLong": "leading comment validation failed: line longer than expected",
+            "leadingComment-headerLineTooShort":
+                "leading comment validation failed: line shorter than expected; missing: '{{remainder}}'",
+            "leadingComment-headerTooShort":
+                "leading comment validation failed: comment too short; missing lines: '{{remainder}}'",
+            "leadingComment-headerTooLong": "leading comment validation failed: comment too long",
+            "leadingComment-incorrectCommentType":
+                "leading comment validation failed: should be a {{commentType}} comment",
+            "leadingComment-incorrectHeader":
+                "leading comment validation failed: comment does not match pattern: '{{pattern}}'",
+            "leadingComment-incorrectHeaderLine":
+                "leading comment validation failed: comment line does not match pattern: '{{pattern}}'",
+            // messages only applicable to header validation.
             missingHeader: "missing header",
             noNewlineAfterHeader: "not enough newlines after header: expected: {{expected}}, actual: {{actual}}"
         }
@@ -609,42 +945,24 @@ const headerRule = {
      * @param {RuleContext} context ESLint rule execution context.
      * @returns {NodeListener} The rule definition.
      */
-    create: function(context) {
+    create: function (context) {
 
-        const newStyleOptions = transformLegacyOptions(/** @type {AllHeaderOptions} */ (context.options));
+        const newStyleOptions = transformLegacyOptions(/** @type {AllHeaderOptions} */(context.options));
         const options = normalizeOptions(newStyleOptions);
-
-        assertLineBasedHeaderConfig(options.header);
-        const commentType = /** @type {CommentType} */ (options.header.commentType);
-
-        const eol = getEol(
-            /** @type {LineEndingOption} */ (options.lineEndings)
-        );
-
-        /** @type {string[]} */
-        let fixLines = [];
-        // If any of the lines are regular expressions, then we can't
-        // automatically fix them. We set this to true below once we
-        // ensure none of the lines are of type RegExp
-        let canFix = true;
-        const headerLines = options.header.lines.map(function(line) {
-            // Can only fix regex option if a template is also provided
+        const eol = getEol(/** @type {LineEndingOption} */(options.lineEndings));
+        const header = /** @type {InlineConfig} */ (options.header);
+        const canFix = !header.lines.some((line) => isPattern(line) && !("template" in line));
+        const fixLines = header.lines.map((line) => {
             if (isPattern(line)) {
-                if (Object.prototype.hasOwnProperty.call(line, "template")) {
-                    fixLines.push(/** @type {string} */ (line.template));
-                } else {
-                    canFix = false;
-                    fixLines.push("");
-                }
-                return line.pattern;
-            } else {
-                fixLines.push(/** @type {string} */ (line));
-                return line;
+                return ("template" in line) ? /** @type {string} */(line.template) : "";
             }
+            return /** @type {string} */(line);
         });
-
-
         const numLines = /** @type {number} */ (options.trailingEmptyLines?.minimum);
+        const headerMatcher = new CommentMatcher(header, eol, numLines);
+        const allowedLeadingComments = /** @type {LeadingComments} */ (options.leadingComments).comments;
+        const allowedCommentsMatchers =
+            allowedLeadingComments.map((c) => new CommentMatcher(/** @type {InlineConfig} */(c), eol, 0));
 
         return {
             /**
@@ -652,58 +970,36 @@ const headerRule = {
              * header validation.
              * @returns {void}
              */
-            Program: function() {
+            Program: function () {
                 const sourceCode = contextSourceCode(context);
-                if (!hasHeader(sourceCode.text)) {
-                    const hasShebang = sourceCode.text.startsWith("#!");
-                    const line = hasShebang ? 2 : 1;
+                const leadingComments = getLeadingComments(sourceCode);
+                const hasShebang = leadingComments.length > 0
+                    && /** @type {string} */ (leadingComments[0][0].type) === "Shebang";
+                let startingHeaderLine = 1;
+                if (hasShebang) {
+                    leadingComments.splice(0, 1);
+                    startingHeaderLine = 2;
+                }
+
+                if (leadingComments.length === 0
+                    || /** @type {SourceLocation} */ (leadingComments[0][0].loc).start.line > startingHeaderLine) {
+
                     context.report({
                         loc: {
                             start: {
-                                column: 1,
-                                line
+                                column: 0,
+                                line: startingHeaderLine
                             },
                             end: {
-                                column: 1,
-                                line
+                                column: 0,
+                                line: startingHeaderLine
                             }
                         },
                         messageId: "missingHeader",
-                        fix: genPrependFixer(
-                            commentType,
-                            context,
-                            fixLines,
-                            eol,
-                            numLines)
-                    });
-                    return;
-                }
-                const leadingComments = getLeadingComments(context);
-                const firstLeadingCommentLoc = leadingComments[0].loc;
-                const firstLeadingCommentRange = leadingComments[0].range;
-                assertDefined(firstLeadingCommentRange);
-
-                const lastLeadingCommentLoc = leadingComments[leadingComments.length - 1].loc;
-
-                if (leadingComments[0].type.toLowerCase() !== commentType) {
-                    assertDefined(firstLeadingCommentLoc);
-                    assertNotNull(firstLeadingCommentLoc);
-                    assertDefined(lastLeadingCommentLoc);
-                    assertNotNull(lastLeadingCommentLoc);
-                    context.report({
-                        loc: {
-                            start: firstLeadingCommentLoc.start,
-                            end: lastLeadingCommentLoc.end
-                        },
-                        messageId: "incorrectCommentType",
-                        data: {
-                            commentType: commentType
-                        },
                         fix: canFix
-                            ? genReplaceFixer(
-                                commentType,
-                                context,
-                                leadingComments,
+                            ? genPrependFixer(
+                                headerMatcher.commentType,
+                                sourceCode,
                                 fixLines,
                                 eol,
                                 numLines)
@@ -711,366 +1007,69 @@ const headerRule = {
                     });
                     return;
                 }
-                if (commentType === commentTypeOptions.line) {
-                    if (headerLines.length === 1) {
-                        const leadingCommentValues = leadingComments.map((c) => c.value);
-                        if (
-                            !match(leadingCommentValues.join("\n"), headerLines[0])
-                            && !match(leadingCommentValues.join("\r\n"), headerLines[0])
-                        ) {
-                            assertDefined(firstLeadingCommentLoc);
-                            assertNotNull(firstLeadingCommentLoc);
-                            assertDefined(lastLeadingCommentLoc);
-                            assertNotNull(lastLeadingCommentLoc);
-                            context.report({
-                                loc: {
-                                    start: firstLeadingCommentLoc.start,
-                                    end: lastLeadingCommentLoc.end
-                                },
-                                messageId: "incorrectHeader",
-                                fix: canFix
-                                    ? genReplaceFixer(
-                                        commentType,
-                                        context,
-                                        leadingComments,
-                                        fixLines,
-                                        eol,
-                                        numLines)
-                                    : null
-                            });
-                            return;
-                        }
-                    } else {
-                        for (let i = 0; i < headerLines.length; i++) {
-                            if (leadingComments.length - 1 < i) {
-                                assertDefined(lastLeadingCommentLoc);
-                                assertNotNull(lastLeadingCommentLoc);
-                                context.report({
-                                    loc: {
-                                        start: lastLeadingCommentLoc.end,
-                                        end: lastLeadingCommentLoc.end
-                                    },
-                                    messageId: "headerTooShort",
-                                    data: {
-                                        remainder: headerLines.slice(i).join(eol)
-                                    },
-                                    fix: canFix
-                                        ? genReplaceFixer(
-                                            commentType,
-                                            context,
-                                            leadingComments,
-                                            fixLines,
-                                            eol,
-                                            numLines)
-                                        : null
-                                });
-                                return;
-                            }
-                            const headerLine = headerLines[i];
-                            const comment = leadingComments[i];
-                            const commentLoc = comment.loc;
-                            assertDefined(commentLoc);
-                            assertNotNull(commentLoc);
-                            if (typeof headerLine === "string") {
-                                const leadingCommentLength = comment.value.length;
-                                const headerLineLength = headerLine.length;
-                                for (let j = 0; j < Math.min(leadingCommentLength, headerLineLength); j++) {
-                                    if (comment.value[j] !== headerLine[j]) {
-                                        context.report({
-                                            loc: {
-                                                start: {
-                                                    column: "//".length + j,
-                                                    line: commentLoc.start.line
-                                                },
-                                                end: commentLoc.end
-                                            },
-                                            messageId: "headerLineMismatchAtPos",
-                                            data: {
-                                                expected: headerLine.substring(j)
-                                            },
-                                            fix: genReplaceFixer(
-                                                commentType,
-                                                context,
-                                                leadingComments,
-                                                fixLines,
-                                                eol,
-                                                numLines)
-                                        });
-                                        return;
-                                    }
-                                }
-                                if (leadingCommentLength < headerLineLength) {
-                                    context.report({
-                                        loc: {
-                                            start: commentLoc.end,
-                                            end: commentLoc.end,
-                                        },
-                                        messageId: "headerLineTooShort",
-                                        data: {
-                                            remainder: headerLine.substring(leadingCommentLength)
-                                        },
-                                        fix: canFix
-                                            ? genReplaceFixer(
-                                                commentType,
-                                                context,
-                                                leadingComments,
-                                                fixLines,
-                                                eol,
-                                                numLines)
-                                            : null
-                                    });
-                                    return;
-                                }
-                                if (leadingCommentLength > headerLineLength) {
-                                    context.report({
-                                        loc: {
-                                            start: {
-                                                column: "//".length + headerLineLength,
-                                                line: commentLoc.start.line
-                                            },
-                                            end: commentLoc.end,
-                                        },
-                                        messageId: "headerLineTooLong",
-                                        fix: canFix
-                                            ? genReplaceFixer(
-                                                commentType,
-                                                context,
-                                                leadingComments,
-                                                fixLines,
-                                                eol,
-                                                numLines)
-                                            : null
-                                    });
-                                    return;
-                                }
-                            } else {
-                                if (!match(comment.value, headerLine)) {
-                                    context.report({
-                                        loc: {
-                                            start: {
-                                                column: "//".length,
-                                                line: commentLoc.start.line,
-                                            },
-                                            end: commentLoc.end,
-                                        },
-                                        messageId: "incorrectHeaderLine",
-                                        data: {
-                                            pattern: headerLine.toString()
-                                        },
-                                        fix: canFix
-                                            ? genReplaceFixer(
-                                                commentType,
-                                                context,
-                                                leadingComments,
-                                                fixLines,
-                                                eol,
-                                                numLines)
-                                            : null
-                                    });
-                                    return;
-                                }
-                            }
-                        }
-                    }
 
-                    const commentRange = leadingComments[headerLines.length - 1].range;
-                    assertDefined(commentRange);
-                    const actualLeadingEmptyLines = leadingEmptyLines(sourceCode.text.substring(commentRange[1]));
-                    const missingEmptyLines = numLines - actualLeadingEmptyLines;
-                    if (missingEmptyLines > 0) {
-                        context.report({
-                            loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
-                            messageId: "noNewlineAfterHeader",
-                            data: {
-                                expected: numLines,
-                                actual: actualLeadingEmptyLines
-                            },
-                            fix: genEmptyLinesFixer(leadingComments, eol, missingEmptyLines)
-                        });
-                    }
-                    return;
-                }
-                // if block comment pattern has more than 1 line, we also split
-                // the comment
-                let leadingLines = [leadingComments[0].value];
-                if (headerLines.length > 1) {
-                    leadingLines = leadingComments[0].value.split(/\r?\n/);
-                }
+                for (const leadingComment of leadingComments) {
 
-                /** @type {null | string} */
-                let errorMessageId = null;
-                /** @type {undefined | Record<string, string>} */
-                let errorMessageData;
-                /** @type {null | SourceLocation} */
-                let errorMessageLoc = null;
-                for (let i = 0; i < headerLines.length; i++) {
-                    if (leadingLines.length - 1 < i) {
-                        assertDefined(lastLeadingCommentLoc);
-                        assertNotNull(lastLeadingCommentLoc);
-                        context.report({
-                            loc: {
-                                start: lastLeadingCommentLoc.end,
-                                end: lastLeadingCommentLoc.end
-                            },
-                            messageId: "headerTooShort",
-                            data: {
-                                remainder: headerLines.slice(i).join(eol)
-                            },
-                            fix: canFix
-                                ? genReplaceFixer(
-                                    commentType,
-                                    context,
-                                    leadingComments,
-                                    fixLines,
-                                    eol,
-                                    numLines)
-                                : null
-                        });
+                    const headerReport = headerMatcher.validate(leadingComment, sourceCode);
+                    if (headerReport === null) {
                         return;
                     }
-                    const leadingLine = leadingLines[i];
-                    const headerLine = headerLines[i];
-                    if (typeof headerLine === "string") {
-                        for (let j = 0; j < Math.min(leadingLine.length, headerLine.length); j++) {
-                            if (leadingLine[j] !== headerLine[j]) {
-                                errorMessageId = "headerLineMismatchAtPos";
-                                const columnOffset = i === 0 ? "/*".length : 0;
-                                assertDefined(firstLeadingCommentLoc);
-                                assertNotNull(firstLeadingCommentLoc);
-                                const line = firstLeadingCommentLoc.start.line + i;
-                                errorMessageLoc = {
-                                    start: {
-                                        column: columnOffset + j,
-                                        line
-                                    },
-                                    end: {
-                                        column: columnOffset + leadingLine.length,
-                                        line
-                                    }
-                                };
-                                errorMessageData = {
-                                    expected: headerLine.substring(j)
-                                };
-                                break;
-                            }
-                        }
-                        if (errorMessageId) {
-                            break;
-                        }
-                        if (leadingLine.length < headerLine.length) {
-                            errorMessageId = "headerLineTooShort";
-                            const startColumn = (i === 0 ? "/*".length : 0) + leadingLine.length;
-                            assertDefined(firstLeadingCommentLoc);
-                            assertNotNull(firstLeadingCommentLoc);
-                            errorMessageLoc = {
-                                start: {
-                                    column: startColumn,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                },
-                                end: {
-                                    column: startColumn + 1,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                }
-                            };
-                            errorMessageData = {
-                                remainder: headerLine.substring(leadingLine.length)
-                            };
-                            break;
-                        }
-                        if (leadingLine.length > headerLine.length) {
-                            assertDefined(firstLeadingCommentLoc);
-                            assertNotNull(firstLeadingCommentLoc);
-                            errorMessageId = "headerLineTooLong";
-                            errorMessageLoc = {
-                                start: {
-                                    column: (i === 0 ? "/*".length : 0) + headerLine.length,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                },
-                                end: {
-                                    column: (i === 0 ? "/*".length : 0) + leadingLine.length,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                }
-                            };
-                            break;
+                    const leadingCommentReports =
+                        allowedCommentsMatchers.map((m) => m.validate(leadingComment, sourceCode));
+                    const commentMatched = leadingCommentReports.some((report) => report === null);
+
+                    if (!commentMatched) {
+                        if ("messageId" in headerReport && headerReport.messageId === "noNewlineAfterHeader") {
+                            const { expected, actual } =
+                                /** @type {{ expected: number, actual: number }} */ (headerReport.data);
+                            headerReport.fix = genEmptyLinesFixer(leadingComment, eol, expected - actual);
+                        } else if (canFix) {
+                            headerReport.fix = genReplaceFixer(
+                                headerMatcher.commentType,
+                                sourceCode,
+                                leadingComment,
+                                fixLines,
+                                eol,
+                                numLines);
                         }
-                    } else {
-                        if (!match(leadingLine, headerLine)) {
-                            errorMessageId = "incorrectHeaderLine";
-                            errorMessageData = {
-                                pattern: headerLine.toString()
-                            };
-                            const columnOffset = i === 0 ? "/*".length : 0;
-                            assertDefined(firstLeadingCommentLoc);
-                            assertNotNull(firstLeadingCommentLoc);
-                            errorMessageLoc = {
-                                start: {
-                                    column: columnOffset + 0,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                },
-                                end: {
-                                    column: columnOffset + leadingLine.length,
-                                    line: firstLeadingCommentLoc.start.line + i
-                                }
-                            };
-                            break;
+
+                        context.report(headerReport);
+                        for (const commentReport of leadingCommentReports) {
+                            if (commentReport !== null) {
+                                /** @type {{ messageId: string }} */ (commentReport).messageId =
+                                    "leadingComment-" + /** @type {{ messageId: string }} */ (commentReport).messageId;
+                                context.report(commentReport);
+                            }
                         }
+                        return;
                     }
                 }
 
-                if (!errorMessageId && leadingLines.length > headerLines.length) {
-                    errorMessageId = "headerTooLong";
-                    assertDefined(firstLeadingCommentLoc);
-                    assertNotNull(firstLeadingCommentLoc);
-                    assertDefined(lastLeadingCommentLoc);
-                    assertNotNull(lastLeadingCommentLoc);
-                    errorMessageLoc = {
+                const lastComment = leadingComments[leadingComments.length - 1];
+                const lastCommentLine = lastComment[lastComment.length - 1];
+                const lineIndex = /** @type {number} */ (lastCommentLine.loc?.end.line) + 1;
+
+                context.report({
+                    loc: {
                         start: {
-                            column: (headerLines.length === 0 ? "/*".length : 0) + 0,
-                            line: firstLeadingCommentLoc.start.line + headerLines.length
+                            column: 0,
+                            line: lineIndex
                         },
                         end: {
-                            column: lastLeadingCommentLoc.end.column - "*/".length,
-                            line: lastLeadingCommentLoc.end.line
+                            column: 0,
+                            line: lineIndex
                         }
-                    };
-                }
-
-                if (errorMessageId) {
-                    if (canFix && headerLines.length > 1) {
-                        fixLines = [fixLines.join(eol)];
-                    }
-                    assertNotNull(errorMessageLoc);
-                    context.report({
-                        loc: errorMessageLoc,
-                        messageId: errorMessageId,
-                        data: errorMessageData,
-                        fix: canFix
-                            ? genReplaceFixer(
-                                commentType,
-                                context,
-                                leadingComments,
-                                fixLines,
-                                eol,
-                                numLines)
-                            : null
-                    });
-                    return;
-                }
-
-                const actualLeadingEmptyLines =
-                    leadingEmptyLines(sourceCode.text.substring(firstLeadingCommentRange[1]));
-                const missingEmptyLines = numLines - actualLeadingEmptyLines;
-                if (missingEmptyLines > 0) {
-                    context.report({
-                        loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
-                        messageId: "noNewlineAfterHeader",
-                        data: {
-                            expected: numLines,
-                            actual: actualLeadingEmptyLines
-                        },
-                        fix: genEmptyLinesFixer(leadingComments, eol, missingEmptyLines)
-                    });
-                }
+                    },
+                    messageId: "missingHeader",
+                    fix: canFix
+                        ? genPrependFixer(
+                            headerMatcher.commentType,
+                            sourceCode,
+                            fixLines,
+                            eol,
+                            numLines)
+                        : null
+                });
             }
         };
     }