@tony.ganchev/eslint-plugin-header 3.1.9 → 3.1.11

package/LICENSE.md

@@ -1,4 +1,6 @@
-Copyright (c) 2015-present Stuart Knightley, Tony Ganchev and contributors
+# MIT License
+
+Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
 
 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
@@ -15,4 +17,4 @@ 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.
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -112,7 +112,6 @@ Suppose we want our header to look like this:
  * Copyright (c) 2015
  * My Company
  */
-...
 ```
 
 All of the following configurations will match the header:
@@ -211,7 +210,6 @@ perfectly valid, such as:
  * Copyright 2020
  * My company
  */
-...
 ```
 
 Moreover, suppose your legal department expects that the year of first and last
@@ -223,7 +221,6 @@ support:
  * Copyright 2017-2022
  * My company
  */
-...
 ```
 
 We can use a regular expression to support all of these cases for your header:

package/index.js

@@ -1,7 +1,7 @@
 /*
  * MIT License
  *
- * Copyright (c) 2015-present Stuart Knightley and contributors
+ * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the “Software”), to deal
@@ -10,8 +10,8 @@
  * 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 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,

package/lib/comment-parser.js

@@ -1,7 +1,7 @@
 /*
  * MIT License
  *
- * Copyright (c) 2015-present Stuart Knightley and contributors
+ * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the “Software”), to deal
@@ -10,8 +10,8 @@
  * 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 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,
@@ -24,30 +24,32 @@
 
 "use strict";
 
+const assert = require("assert");
+
 /**
- * Parses a line or block comment and returns the type of comment and an array of content lines.
+ * Parses a line or block comment and returns the type of comment and an array
+ * of content lines.
  *
  * This is a really simple and dumb parser, that looks just for a
  * single kind of comment. It won't detect multiple block comments.
  * @param {string} commentText comment text.
- * @returns {['block' | 'line', string[]]} comment type and comment content broken into lines.
+ * @returns {['block' | 'line', string | string[]]} comment type and comment
+ *                                                  content broken into lines.
  */
 module.exports = function commentParser(commentText) {
+    assert.strictEqual(typeof commentText, "string");
     const text = commentText.trim();
 
-    if (text.substr(0, 2) === "//") {
+    if (text.startsWith("//")) {
         return [
             "line",
-            text.split(/\r?\n/).map(function(line) {
-                return line.substr(2);
-            })
+            text.split(/\r?\n/).map((line) => line.substring(2))
         ];
-    } else if (
-        text.substr(0, 2) === "/*" &&
-        text.substr(-2) === "*/"
-    ) {
+    } else if (text.startsWith("/*") && text.endsWith("*/")) {
         return ["block", text.substring(2, text.length - 2)];
     } else {
-        throw new Error("Could not parse comment file: the file must contain either just line comments (//) or a single block comment (/* ... */)");
+        throw new Error(
+            "Could not parse comment file: the file must contain either just line comments (//) or a single block " +
+                "comment (/* ... */)");
     }
 };

package/lib/rules/header.docs.js

@@ -0,0 +1,40 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025-present Tony Ganchev and contributors
+ *
+ * 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.
+ */
+
+
+"use strict";
+
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageJsonContent = fs.readFileSync(path.resolve(__dirname, "../../package.json"));
+const packageJson = JSON.parse(packageJsonContent);
+assert.equal(Object.prototype.hasOwnProperty.call(packageJson, "version"), true,
+    "The plugin's package.json should be available two directories above the rule.");
+const pluginVersion = packageJsonContent.version;
+
+exports.description = "";
+exports.recommended = true;
+exports.url = "https://www.npmjs.com/package/@tony.ganchev/eslint-plugin-header/v/" + pluginVersion;

package/lib/rules/header.js

@@ -1,7 +1,7 @@
 /*
  * MIT License
  *
- * Copyright (c) 2015-present Stuart Knightley and contributors
+ * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the “Software”), to deal
@@ -10,8 +10,8 @@
  * 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 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,
@@ -24,10 +24,15 @@
 
 "use strict";
 
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const commentParser = require("../comment-parser");
+const { description, recommended, url } = require("./header.docs");
+const { commentTypeOptions, lineEndingOptions, schema } = require("./header.schema");
+
 /**
  * Import type definitions.
- * @typedef {import('estree').Comment} Comment
- * @typedef {import('estree').Program} Program
  * @typedef {import('eslint').Rule.Fix} Fix
  * @typedef {import('eslint').Rule.NodeListener} NodeListener
  * @typedef {import('eslint').Rule.ReportFixer} ReportFixer
@@ -35,50 +40,44 @@
  * @typedef {import('eslint').Rule.RuleTextEdit} RuleTextEdit
  * @typedef {import('eslint').Rule.RuleTextEditor} RuleTextEditor
  * @typedef {import('eslint').Rule.RuleContext} RuleContext
+ * @typedef {import('estree').Comment} Comment
+ * @typedef {import('estree').Program} Program
+ * @typedef {import("estree").SourceLocation} SourceLocation
  */
 
-/**
- * @enum {string}
- */
-const lineEndingOptions = Object.freeze({
-    unix: "unix", // \n
-    windows: "windows", // \n
-});
-
-/**
- * @enum {string}
- */
-const commentTypeOptions = Object.freeze({
-    block: "block",
-    line: "line"
-});
-
 /**
  * Local type defintions.
  * @typedef {string | { pattern: string, template?: string }} HeaderLine
  * @typedef {(HeaderLine | HeaderLine[])} HeaderLines
  * @typedef {{ lineEndings: ('unix' | 'windows') }} HeaderSettings
- * @typedef {([string] | [string, HeaderSettings] | [('block' | 'line') | HeaderLines ] | [('block' | 'line') | HeaderLines | HeaderSettings] | [('block' | 'line') | HeaderLines | number ] | [('block' | 'line') | HeaderLines | number | HeaderSettings])} HeaderOptions
+ * @typedef {
+ *  [string]
+ *  | [string, HeaderSettings]
+ *  | [('block' | 'line') | HeaderLines ]
+ *  | [('block' | 'line') | HeaderLines | HeaderSettings]
+ *  | [('block' | 'line') | HeaderLines | number ]
+ *  | [('block' | 'line') | HeaderLines | number | HeaderSettings]
+ * } HeaderOptions
  */
 
-var fs = require("fs");
-var commentParser = require("../comment-parser");
-var os = require("os");
-
 /**
- * Tests if the passed line configuration string or object is a pattern definition.
+ * Tests if the passed line configuration string or object is a pattern
+ * definition.
  * @param {HeaderLine} object line configuration object or string
- * @returns {boolean} `true` if the line configuration is a pattern-dfining object or `false` otherwise.
+ * @returns {boolean} `true` if the line configuration is a pattern-defining
+ *                    object or `false` otherwise.
  */
 function isPattern(object) {
     return typeof object === "object" && Object.prototype.hasOwnProperty.call(object, "pattern");
 }
 
 /**
- * Utility over a line config argument to match an expected string either against a regex or for full match against a string.
+ * Utility over a line config argument to match an expected string either
+ * against a regex or for full match against a string.
  * @param {HeaderLine} actual the string to test.
  * @param {string} expected The string or regex to test again.
- * @returns {boolean} `true` if the passed string matches the expected line config or `false` otherwise.
+ * @returns {boolean} `true` if the passed string matches the expected line
+ *                    config or `false` otherwise.
  */
 function match(actual, expected) {
     if (expected.test) {
@@ -91,7 +90,9 @@ function match(actual, expected) {
 /**
  * Remove Unix she-bangs from the list of comments.
  * @param {Comment[]} comments the list of comment lines.
- * @returns {Comment[]} the list of comments with containing all incomming comments from `comments` with the shebang comments omitted.
+ * @returns {Comment[]} the list of comments with containing all incomming
+ *                      comments from `comments` with the shebang comments
+ *                      omitted.
  */
 function excludeShebangs(comments) {
     return comments.filter(function(comment) {
@@ -109,12 +110,13 @@ function excludeShebangs(comments) {
  * @returns {Comment[]} lines that constitute the leading comment.
  */
 function getLeadingComments(context, node) {
-    var all = excludeShebangs(context.getSourceCode().getAllComments(node.body.length ? node.body[0] : node));
+    const all = excludeShebangs(context.sourceCode.getAllComments(node.body.length ? node.body[0] : node));
     if (all[0].type.toLowerCase() === commentTypeOptions.block) {
         return [all[0]];
     }
-    for (var i = 1; i < all.length; ++i) {
-        var txt = context.getSourceCode().getText().slice(all[i - 1].range[1], all[i].range[0]);
+    let i = 1;
+    for (; i < all.length; ++i) {
+        const txt = context.sourceCode.text.slice(all[i - 1].range[1], all[i].range[0]);
         if (!txt.match(/^(\r\n|\r|\n)$/)) {
             break;
         }
@@ -123,40 +125,55 @@ function getLeadingComments(context, node) {
 }
 
 /**
- * Generate a comment including trailing spaces out of a number of comment body lines.
+ * Generate a comment including trailing spaces out of a number of comment body
+ * lines.
  * @param {'block' | 'line'} commentType the type of comment to generate.
  * @param {string[]} textArray list of lines of the comment content.
  * @param {'\n' | '\r\n'} eol end-of-line characters.
- * @param {number} numNewlines number of trailing lines after the comment.
  * @returns {string} resulting comment.
  */
-function genCommentBody(commentType, textArray, eol, numNewlines) {
-    var eols = eol.repeat(numNewlines);
+function genCommentBody(commentType, textArray, eol) {
     if (commentType === commentTypeOptions.block) {
-        return "/*" + textArray.join(eol) + "*/" + eols;
+        return "/*" + textArray.join(eol) + "*/";
     } else {
-        return "//" + textArray.join(eol + "//") + eols;
+        // We need one trailing EOL on line comments to ensure the fixed source
+        // is parsable.
+        return "//" + textArray.join(eol + "//");
     }
 }
 
 /**
- * ...
- * @param {RuleContext} context ESLint rule execution context.
+ * Determines the start and end position in the source code of the leading
+ * comment.
  * @param {string[]} comments list of comments.
- * @param {'\n' | '\r\n'} eol end-of-line characters
  * @returns {[number, number]} resulting range.
  */
-function genCommentsRange(context, comments, eol) {
-    var start = comments[0].range[0];
-    var end = comments.slice(-1)[0].range[1];
-    const sourceCode = context.getSourceCode().text;
-    const headerTrailingChars = sourceCode.substring(end, end + eol.length);
-    if (headerTrailingChars === eol) {
-        end += eol.length;
-    }
+function genCommentsRange(comments) {
+    const start = comments[0].range[0];
+    const end = comments.slice(-1)[0].range[1];
     return [start, end];
 }
 
+/**
+ * Calculates the number of leading empty lines in the source code. The function
+ * counts both Windows and POSIX line endings.
+ * @param {string} src the source code to traverse.
+ * @returns {number} the number of leading empty lines.
+ */
+function leadingEmptyLines(src) {
+    let numLines = 0;
+    while (true) {
+        const m = src.match(/^(\r\n|\n)/);
+        if (!m) {
+            break;
+        }
+        assert.strictEqual(m.index, 0);
+        numLines++;
+        src = src.slice(m.index + m[0].length);
+    }
+    return numLines;
+}
+
 /**
  * Factory for fixer that adds a missing header.
  * @param {'block' | 'line'} commentType type of comment to use.
@@ -168,38 +185,65 @@ function genCommentsRange(context, comments, eol) {
  */
 function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
     return function(fixer) {
-        const newHeader = genCommentBody(commentType, headerLines, eol, numNewlines);
-        if (context.sourceCode.text.substring(0, 2) === "#!") {
+        let insertPos = 0;
+        let newHeader = genCommentBody(commentType, headerLines, eol, numNewlines);
+        if (context.sourceCode.text.startsWith("#!")) {
             const firstNewLinePos = context.sourceCode.text.indexOf("\n");
-            const insertPos = firstNewLinePos === -1 ? context.sourceCode.text.length : firstNewLinePos + 1;
-            return fixer.insertTextBeforeRange(
-                [insertPos, insertPos /* don't care */],
-                (firstNewLinePos === -1 ? eol : "") + newHeader
-            );
-        } else {
-            return fixer.insertTextBeforeRange(
-                [0, 0 /* don't care */],
-                newHeader
-            );
+            insertPos = firstNewLinePos === -1 ? context.sourceCode.text.length : firstNewLinePos + 1;
+            if (firstNewLinePos === -1) {
+                newHeader = eol + newHeader;
+            }
         }
+        const numEmptyLines = leadingEmptyLines(context.sourceCode.text.substring(insertPos));
+        const additionalEmptyLines = Math.max(0, numNewlines - numEmptyLines);
+        newHeader += eol.repeat(additionalEmptyLines);
+        return fixer.insertTextBeforeRange(
+            [insertPos, insertPos /* don't care */],
+            newHeader
+        );
     };
 }
 
 /**
  * Factory for fixer that replaces an incorrect header.
  * @param {'block' | 'line'} commentType type of comment to use.
- * @param {RuleContext} context ESLint rule execution context.
+ * @param {RuleContext} context ESLint execution context.
  * @param {Comment[]} leadingComments comment elements to replace.
  * @param {string[]} headerLines lines of the header comment.
  * @param {'\n' | '\r\n'} eol end-of-line characters
  * @param {number} numNewlines number of trailing lines after the comment.
- * @returns {(fixer: RuleTextEditor) => RuleTextEdit | RuleTextEdit[] | null} the fixer.
+ * @returns {
+ *  (fixer: RuleTextEditor) => RuleTextEdit | RuleTextEdit[] | null
+ * } the fixer.
  */
 function genReplaceFixer(commentType, context, leadingComments, headerLines, eol, numNewlines) {
     return function(fixer) {
+        const commentRange = genCommentsRange(leadingComments);
+        const emptyLines = leadingEmptyLines(context.sourceCode.text.substring(commentRange[1]));
+        const missingNewlines = Math.max(0, numNewlines - emptyLines);
+        const eols = eol.repeat(missingNewlines);
         return fixer.replaceTextRange(
-            genCommentsRange(context, leadingComments, eol),
-            genCommentBody(commentType, headerLines, eol, numNewlines)
+            commentRange,
+            genCommentBody(commentType, headerLines, eol, numNewlines) + eols
+        );
+    };
+}
+
+/**
+ * Factory for fixer that replaces an incorrect header.
+ * @param {Comment[]} leadingComments comment elements to replace.
+ * @param {'\n' | '\r\n'} eol end-of-line characters
+ * @param {number} missingEmptyLinesCount number of trailing lines after the
+ *                                        comment.
+ * @returns {
+ *  (fixer: RuleTextEditor) => RuleTextEdit | RuleTextEdit[] | null
+ * } the fixer.
+ */
+function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
+    return function(fixer) {
+        return fixer.insertTextAfterRange(
+            genCommentsRange(leadingComments),
+            eol.repeat(missingEmptyLinesCount)
         );
     };
 }
@@ -207,10 +251,11 @@ function genReplaceFixer(commentType, context, leadingComments, headerLines, eol
 /**
  * Finds the option parameter within the list of rule config options.
  * @param {HeaderOptions} options the config options passed to the rule.
- * @returns {HeaderSettings | null} the settings parameter or `null` if no such is defined.
+ * @returns {HeaderSettings | null} the settings parameter or `null` if no such
+ *                                  is defined.
  */
 function findSettings(options) {
-    var lastOption = options.length > 0 ? options[options.length - 1] : null;
+    const lastOption = options[options.length - 1];
     if (typeof lastOption === "object" && !Array.isArray(lastOption) && lastOption !== null
         && !Object.prototype.hasOwnProperty.call(lastOption, "pattern")) {
         return lastOption;
@@ -219,12 +264,14 @@ function findSettings(options) {
 }
 
 /**
- * Returns the used line-termination characters per the rule's config if any or else based on the runtime environments.
+ * Returns the used line-termination characters per the rule's config if any or
+ * else based on the runtime environments.
  * @param {HeaderOptions} options rule configuration.
- * @returns {'\n' | '\r\n'} the correct line ending characters for the environment.
+ * @returns {'\n' | '\r\n'} the correct line ending characters for the
+ * environment.
  */
 function getEOL(options) {
-    var settings = findSettings(options);
+    const settings = findSettings(options);
     if (settings) {
         if (settings.lineEndings === lineEndingOptions.unix) {
             return "\n";
@@ -237,132 +284,62 @@ function getEOL(options) {
 }
 
 /**
- * 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.
+ * 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.
  */
-// TODO: check if it is valid to have the copyright notice separated by an empty line from the shebang.
 function hasHeader(src) {
-    if (src.substr(0, 2) === "#!") {
-        var m = src.match(/(\r\n|\r|\n)/);
-        if (m) {
-            src = src.slice(m.index + m[0].length);
-        }
-    }
-    return src.substr(0, 2) === "/*" || src.substr(0, 2) === "//";
+    const srcWithoutShebang = src.replace(/^#![^\n]*\r?\n/, "");
+    return srcWithoutShebang.startsWith("/*") || srcWithoutShebang.startsWith("//");
 }
 
 /**
- * Ensures that the right amount of empty lines trail the header.
- * @param {string} src source to validate.
- * @param {number} num expected number of trailing empty lines.
- * @returns {boolean} `true` if the `num` number of empty lines are appended at the end or `false` otherwise.
+ * Calculates the source location of the violation that not enough empty lines
+ * follow the header.
+ * The behavior chosen is that the violation is shown over the empty (but
+ * insufficient) lines that trail the comment. A special case is when there are
+ * no empty lines after the header in which case we highlight the next character
+ * in the source regardless of which one it is).
+ * @param {Comment[]} leadingComments the comment lines that constitute the
+ *                                    header.
+ * @param {number} actualEmptyLines the number of empty lines that follow the
+ *                                  header.
+ * @returns {SourceLocation} the location (line and column) of the violation.
  */
-function matchesLineEndings(src, num) {
-    for (var j = 0; j < num; ++j) {
-        var m = src.match(/^(\r\n|\r|\n)/);
-        if (m) {
-            src = src.slice(m.index + m[0].length);
-        } else {
-            return false;
+function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
+    const lastCommentLineLocEnd = leadingComments[leadingComments.length - 1].loc.end;
+    return {
+        start: lastCommentLineLocEnd,
+        end: {
+            column: actualEmptyLines === 0 ? lastCommentLineLocEnd.column + 1 : 0,
+            line: lastCommentLineLocEnd.line + actualEmptyLines
         }
-    }
-    return true;
+    };
 }
 
 module.exports = {
     meta: {
         type: "layout",
+        docs: {
+            description,
+            recommended,
+            url
+        },
         fixable: "whitespace",
-        schema: {
-            $ref: "#/definitions/options",
-            definitions: {
-                commentType: {
-                    type: "string",
-                    enum: [commentTypeOptions.block, commentTypeOptions.line]
-                },
-                line: {
-                    anyOf: [
-                        {
-                            type: "string"
-                        },
-                        {
-                            type: "object",
-                            properties: {
-                                pattern: {
-                                    type: "string"
-                                },
-                                template: {
-                                    type: "string"
-                                }
-                            },
-                            required: ["pattern"],
-                            additionalProperties: false
-                        }
-                    ]
-                },
-                headerLines: {
-                    anyOf: [
-                        {
-                            $ref: "#/definitions/line"
-                        },
-                        {
-                            type: "array",
-                            items: {
-                                $ref: "#/definitions/line"
-                            }
-                        }
-                    ]
-                },
-                numNewlines: {
-                    type: "integer",
-                    minimum: 0
-                },
-                settings: {
-                    type: "object",
-                    properties: {
-                        lineEndings: {
-                            type: "string",
-                            enum: [lineEndingOptions.unix, lineEndingOptions.windows]
-                        }
-                    },
-                    additionalProperties: false
-                },
-                options: {
-                    anyOf: [
-                        {
-                            type: "array",
-                            minItems: 1,
-                            maxItems: 2,
-                            items: [
-                                { type: "string" },
-                                { $ref: "#/definitions/settings" }
-                            ]
-                        },
-                        {
-                            type: "array",
-                            minItems: 2,
-                            maxItems: 3,
-                            items: [
-                                { $ref: "#/definitions/commentType" },
-                                { $ref: "#/definitions/headerLines" },
-                                { $ref: "#/definitions/settings" }
-                            ]
-                        },
-                        {
-                            type: "array",
-                            minItems: 3,
-                            maxItems: 4,
-                            items: [
-                                { $ref: "#/definitions/commentType" },
-                                { $ref: "#/definitions/headerLines" },
-                                { $ref: "#/definitions/numNewlines" },
-                                { $ref: "#/definitions/settings" }
-                            ]
-                        }
-                    ]
-                }
-            }
+        schema,
+        defaultOptions: [{}],
+        messages: {
+            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}}",
+            headerTooLong: "header too long",
+            incorrectCommentType: "header should be a {{commentType}} comment",
+            incorrectHeader: "incorrect header",
+            incorrectHeaderLine: "header line does not match pattern: {{pattern}}",
+            missingHeader: "missing header",
+            noNewlineAfterHeader: "not enough newlines after header: expected: {{expected}}, actual: {{actual}}"
         }
     },
     /**
@@ -371,26 +348,28 @@ module.exports = {
      * @returns {NodeListener} the rule definition.
      */
     create: function(context) {
-        var options = context.options;
-        var numNewlines = options.length > 2 && typeof options[2] === "number" ? options[2] : 1;
-        var eol = getEOL(options);
+        let options = context.options;
+        const numNewlines = options.length > 2 && typeof options[2] === "number" ? options[2] : 1;
+        const eol = getEOL(options);
 
         // If just one option then read comment from file
         if (options.length === 1 || (options.length === 2 && findSettings(options))) {
-            var text = fs.readFileSync(context.options[0], "utf8");
+            const text = fs.readFileSync(context.options[0], "utf8");
             options = commentParser(text);
         }
 
-        var commentType = options[0].toLowerCase();
-        var headerLines, fixLines = [];
+        const commentType = options[0].toLowerCase();
+        /** @type {(string | RegExp)[]} */
+        let headerLines;
+        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
-        var canFix = false;
+        let canFix = false;
         if (Array.isArray(options[1])) {
             canFix = true;
             headerLines = options[1].map(function(line) {
-                var isRegex = isPattern(line);
+                const isRegex = isPattern(line);
                 // Can only fix regex option if a template is also provided
                 if (isRegex && !line.template) {
                     canFix = false;
@@ -399,7 +378,7 @@ module.exports = {
                 return isRegex ? new RegExp(line.pattern) : line;
             });
         } else if (isPattern(options[1])) {
-            var line = options[1];
+            const line = options[1];
             headerLines = [new RegExp(line.pattern)];
             fixLines.push(line.template || line);
             // Same as above for regex and template
@@ -411,114 +390,346 @@ module.exports = {
         }
 
         return {
+            /**
+             * Hooks into the processing of the overall script node to do the
+             * header validation.
+             * @param {Program} node the whole script node
+             * @returns {void}
+             */
             Program: function(node) {
-                if (!hasHeader(context.sourceCode.getText())) {
+                if (!hasHeader(context.sourceCode.text)) {
+                    const hasShebang = context.sourceCode.text.startsWith("#!");
+                    const line = hasShebang ? 2 : 1;
                     context.report({
-                        loc: node.loc,
-                        message: "missing header",
+                        loc: {
+                            start: {
+                                column: 1,
+                                line
+                            },
+                            end: {
+                                column: 1,
+                                line
+                            }
+                        },
+                        messageId: "missingHeader",
                         fix: genPrependFixer(commentType, context, fixLines, eol, numNewlines)
                     });
-                } else {
-                    var leadingComments = getLeadingComments(context, node);
+                    return;
+                }
+                const leadingComments = getLeadingComments(context, node);
 
-                    if (!leadingComments.length) {
-                        context.report({
-                            loc: node.loc,
-                            message: "missing header",
-                            fix: canFix ? genPrependFixer(commentType, node, fixLines, eol, numNewlines) : null
-                        });
-                    } else if (leadingComments[0].type.toLowerCase() !== commentType) {
-                        context.report({
-                            loc: node.loc,
-                            message: "header should be a {{commentType}} comment",
-                            data: {
-                                commentType: commentType
-                            },
-                            fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                        });
+                if (leadingComments[0].type.toLowerCase() !== commentType) {
+                    context.report({
+                        loc: {
+                            start: leadingComments[0].loc.start,
+                            end: leadingComments[leadingComments.length - 1].loc.end
+                        },
+                        messageId: "incorrectCommentType",
+                        data: {
+                            commentType: commentType
+                        },
+                        fix: canFix
+                            ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                            : null
+                    });
+                    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])
+                        ) {
+                            context.report({
+                                loc: {
+                                    start: leadingComments[0].loc.start,
+                                    end: leadingComments[leadingComments.length - 1].loc.end
+                                },
+                                messageId: "incorrectHeader",
+                                fix: canFix
+                                    ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                                    : null
+                            });
+                            return;
+                        }
                     } else {
-                        if (commentType === commentTypeOptions.line) {
-                            if (leadingComments.length < headerLines.length) {
+                        for (let i = 0; i < headerLines.length; i++) {
+                            if (leadingComments.length - 1 < i) {
                                 context.report({
-                                    loc: node.loc,
-                                    message: "incorrect header",
-                                    fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
+                                    loc: {
+                                        start: leadingComments[leadingComments.length - 1].loc.end
+                                    },
+                                    messageId: "headerTooShort",
+                                    data: {
+                                        remainder: headerLines.slice(i).join(eol)
+                                    },
+                                    fix: canFix
+                                        ? genReplaceFixer(
+                                            commentType,
+                                            context,
+                                            leadingComments,
+                                            fixLines,
+                                            eol,
+                                            numNewlines)
+                                        : null
                                 });
                                 return;
                             }
-                            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])) {
+                            if (typeof headerLines[i] === "string") {
+                                const leadingCommentLength = leadingComments[i].value.length;
+                                const headerLineLength = headerLines[i].length;
+                                for (let j = 0; j < Math.min(leadingCommentLength, headerLineLength); j++) {
+                                    if (leadingComments[i].value[j] !== headerLines[i][j]) {
+                                        context.report({
+                                            loc: {
+                                                start: {
+                                                    column: "//".length + j,
+                                                    line: leadingComments[i].loc.start.line
+                                                },
+                                                end: leadingComments[i].loc.end
+                                            },
+                                            messageId: "headerLineMismatchAtPos",
+                                            data: {
+                                                expected: headerLines[i].substring(j)
+                                            },
+                                            fix: genReplaceFixer(
+                                                commentType,
+                                                context,
+                                                leadingComments,
+                                                fixLines,
+                                                eol,
+                                                numNewlines)
+                                        });
+                                        return;
+                                    }
+                                }
+                                if (leadingCommentLength < headerLineLength) {
+                                    context.report({
+                                        loc: {
+                                            start: leadingComments[i].loc.end,
+                                        },
+                                        messageId: "headerLineTooShort",
+                                        data: {
+                                            remainder: headerLines[i].substring(leadingCommentLength)
+                                        },
+                                        fix: canFix
+                                            ? genReplaceFixer(
+                                                commentType,
+                                                context,
+                                                leadingComments,
+                                                fixLines,
+                                                eol,
+                                                numNewlines)
+                                            : null
+                                    });
+                                    return;
+                                }
+                                if (leadingCommentLength > headerLineLength) {
                                     context.report({
-                                        loc: node.loc,
-                                        message: "incorrect header",
-                                        fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
+                                        loc: {
+                                            start: {
+                                                column: "//".length + headerLineLength,
+                                                line: leadingComments[i].loc.start.line
+                                            },
+                                            end: leadingComments[i].loc.end,
+                                        },
+                                        messageId: "headerLineTooLong",
+                                        fix: canFix
+                                            ? genReplaceFixer(
+                                                commentType,
+                                                context,
+                                                leadingComments,
+                                                fixLines,
+                                                eol,
+                                                numNewlines)
+                                            : null
                                     });
                                     return;
                                 }
                             } else {
-                                for (var i = 0; i < headerLines.length; i++) {
-                                    if (!match(leadingComments[i].value, headerLines[i])) {
-                                        context.report({
-                                            loc: node.loc,
-                                            message: "incorrect header",
-                                            fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                                        });
-                                        return;
-                                    }
+                                if (!match(leadingComments[i].value, headerLines[i])) {
+                                    context.report({
+                                        loc: {
+                                            start: {
+                                                column: "//".length,
+                                                line: leadingComments[i].loc.start.line,
+                                            },
+                                            end: leadingComments[i].loc.end,
+                                        },
+                                        messageId: "incorrectHeaderLine",
+                                        data: {
+                                            pattern: headerLines[i]
+                                        },
+                                        fix: canFix
+                                            ? genReplaceFixer(
+                                                commentType,
+                                                context,
+                                                leadingComments,
+                                                fixLines,
+                                                eol,
+                                                numNewlines)
+                                            : null
+                                    });
+                                    return;
                                 }
                             }
+                        }
+                    }
 
-                            var postLineHeader = context.getSourceCode().text.substr(leadingComments[headerLines.length - 1].range[1], numNewlines * 2);
-                            if (!matchesLineEndings(postLineHeader, numNewlines)) {
-                                context.report({
-                                    loc: node.loc,
-                                    message: "no newline after header",
-                                    fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                                });
-                            }
-
-                        } else {
-                            // if block comment pattern has more than 1 line, we also split the comment
-                            var leadingLines = [leadingComments[0].value];
-                            if (headerLines.length > 1) {
-                                leadingLines = leadingComments[0].value.split(/\r?\n/);
-                            }
+                    const actualLeadingEmptyLines = leadingEmptyLines(
+                        context.sourceCode.text.substring(leadingComments[headerLines.length - 1].range[1]));
+                    const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
+                    if (missingEmptyLines > 0) {
+                        context.report({
+                            loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
+                            messageId: "noNewlineAfterHeader",
+                            data: {
+                                expected: numNewlines,
+                                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/);
+                }
 
-                            var hasError = false;
-                            if (leadingLines.length > headerLines.length) {
-                                hasError = true;
+                /** @type {null | string} */
+                let errorMessageId = null;
+                /** @type {null | Record<string, string | RegExp>} */
+                let errorMessageData = null;
+                /** @type {null | SourceLocation} */
+                let errorMessageLoc = null;
+                for (let i = 0; i < headerLines.length; i++) {
+                    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;
+                                const line = leadingComments[0].loc.start.line + i;
+                                errorMessageLoc = {
+                                    start: {
+                                        column: columnOffset + j,
+                                        line
+                                    },
+                                    end: {
+                                        column: columnOffset + leadingLine.length,
+                                        line
+                                    }
+                                };
+                                errorMessageData = {
+                                    expected: headerLine.substring(j)
+                                };
+                                break;
                             }
-                            for (i = 0; !hasError && i < headerLines.length; i++) {
-                                const leadingLine = leadingLines[i];
-                                const headerLine = headerLines[i];
-                                if (!match(leadingLine, headerLine)) {
-                                    hasError = true;
-                                    break;
+                        }
+                        if (errorMessageId) {
+                            break;
+                        }
+                        if (leadingLine.length < headerLine.length) {
+                            errorMessageId = "headerLineTooShort";
+                            const startColumn = (i === 0 ? "/*".length : 0) + leadingLine.length;
+                            errorMessageLoc = {
+                                start: {
+                                    column: startColumn,
+                                    line: leadingComments[0].loc.start.line + i
+                                },
+                                end: {
+                                    column: startColumn + 1,
+                                    line: leadingComments[0].loc.start.line + i
                                 }
-                            }
-
-                            if (hasError) {
-                                if (canFix && headerLines.length > 1) {
-                                    fixLines = [fixLines.join(eol)];
+                            };
+                            errorMessageData = {
+                                remainder: headerLines[i].substring(leadingLine.length)
+                            };
+                            break;
+                        }
+                        if (leadingLine.length > headerLine.length) {
+                            errorMessageId = "headerLineTooLong";
+                            errorMessageLoc = {
+                                start: {
+                                    column: (i === 0 ? "/*".length : 0) + headerLine.length,
+                                    line: leadingComments[0].loc.start.line + i
+                                },
+                                end: {
+                                    column: (i === 0 ? "/*".length : 0) + leadingLine.length,
+                                    line: leadingComments[0].loc.start.line + i
                                 }
-                                context.report({
-                                    loc: node.loc,
-                                    message: "incorrect header",
-                                    fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                                });
-                            } else {
-                                var postBlockHeader = context.getSourceCode().text.substr(leadingComments[0].range[1], numNewlines * 2);
-                                if (!matchesLineEndings(postBlockHeader, numNewlines)) {
-                                    context.report({
-                                        loc: node.loc,
-                                        message: "no newline after header",
-                                        fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                                    });
+                            };
+                            break;
+                        }
+                    } else {
+                        if (!match(leadingLine, headerLine)) {
+                            errorMessageId = "incorrectHeaderLine";
+                            errorMessageData = {
+                                pattern: headerLine
+                            };
+                            const columnOffset = i === 0 ? "/*".length : 0;
+                            errorMessageLoc = {
+                                start: {
+                                    column: columnOffset + 0,
+                                    line: leadingComments[0].loc.start.line + i
+                                },
+                                end: {
+                                    column: columnOffset + leadingLine.length,
+                                    line: leadingComments[0].loc.start.line + i
                                 }
-                            }
+                            };
+                            break;
+                        }
+                    }
+                }
+
+                if (!errorMessageId && leadingLines.length > headerLines.length) {
+                    errorMessageId = "headerTooLong";
+                    errorMessageLoc = {
+                        start: {
+                            column: (headerLines.length === 0 ? "/*".length : 0) + 0,
+                            line: leadingComments[0].loc.start.line + headerLines.length
+                        },
+                        end: {
+                            column: leadingComments[leadingComments.length - 1].loc.end.column - "*/".length,
+                            line: leadingComments[leadingComments.length - 1].loc.end.line
                         }
+                    };
+                }
+
+                if (errorMessageId) {
+                    if (canFix && headerLines.length > 1) {
+                        fixLines = [fixLines.join(eol)];
                     }
+                    context.report({
+                        loc: errorMessageLoc,
+                        messageId: errorMessageId,
+                        data: errorMessageData,
+                        fix: canFix
+                            ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines)
+                            : null
+                    });
+                    return;
+                }
+
+                const actualLeadingEmptyLines = leadingEmptyLines(
+                    context.sourceCode.text.substring(leadingComments[0].range[1]));
+                const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
+                if (missingEmptyLines > 0) {
+                    context.report({
+                        loc: missingEmptyLinesViolationLoc(leadingComments, actualLeadingEmptyLines),
+                        messageId: "noNewlineAfterHeader",
+                        data: {
+                            expected: numNewlines,
+                            actual: actualLeadingEmptyLines
+                        },
+                        fix: genEmptyLinesFixer(leadingComments, eol, missingEmptyLines)
+                    });
                 }
             }
         };

package/lib/rules/header.schema.js

@@ -0,0 +1,135 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025-present Tony Ganchev and contributors
+ *
+ * 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.
+ */
+
+"use strict";
+
+/**
+ * @enum {string}
+ */
+const lineEndingOptions = Object.freeze({
+    os: "os",
+    unix: "unix",
+    windows: "windows",
+});
+
+/**
+ * @enum {string}
+ */
+const commentTypeOptions = Object.freeze({
+    block: "block",
+    line: "line"
+});
+
+const schema = Object.freeze({
+    $ref: "#/definitions/options",
+    definitions: {
+        commentType: {
+            type: "string",
+            enum: [commentTypeOptions.block, commentTypeOptions.line]
+        },
+        line: {
+            anyOf: [
+                {
+                    type: "string"
+                },
+                {
+                    type: "object",
+                    properties: {
+                        pattern: {
+                            type: "string"
+                        },
+                        template: {
+                            type: "string"
+                        }
+                    },
+                    required: ["pattern"],
+                    additionalProperties: false
+                }
+            ]
+        },
+        headerLines: {
+            anyOf: [
+                {
+                    $ref: "#/definitions/line"
+                },
+                {
+                    type: "array",
+                    items: {
+                        $ref: "#/definitions/line"
+                    }
+                }
+            ]
+        },
+        numNewlines: {
+            type: "integer",
+            minimum: 0
+        },
+        settings: {
+            type: "object",
+            properties: {
+                lineEndings: {
+                    type: "string",
+                    enum: [lineEndingOptions.unix, lineEndingOptions.windows]
+                }
+            },
+            additionalProperties: false
+        },
+        options: {
+            anyOf: [
+                {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 2,
+                    items: [
+                        { type: "string" },
+                        { $ref: "#/definitions/settings" }
+                    ]
+                },
+                {
+                    type: "array",
+                    minItems: 2,
+                    maxItems: 3,
+                    items: [
+                        { $ref: "#/definitions/commentType" },
+                        { $ref: "#/definitions/headerLines" },
+                        { $ref: "#/definitions/settings" }
+                    ]
+                },
+                {
+                    type: "array",
+                    minItems: 3,
+                    maxItems: 4,
+                    items: [
+                        { $ref: "#/definitions/commentType" },
+                        { $ref: "#/definitions/headerLines" },
+                        { $ref: "#/definitions/numNewlines" },
+                        { $ref: "#/definitions/settings" }
+                    ]
+                }
+            ]
+        }
+    }
+});
+
+module.exports = { lineEndingOptions, commentTypeOptions, schema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.1.9",
+  "version": "3.1.11",
   "description": "ESLint plugin to ensure files begin with a given comment, usually a copyright or license notice.",
   "main": "index.js",
   "files": [
@@ -8,16 +8,22 @@
     "!/lib/rules/test-utils.js"
   ],
   "scripts": {
+    "eslint": "npx eslint .",
+    "lint": "npm run eslint && npm run markdownlint",
+    "markdownlint": "npx markdownlint-cli *.md",
     "test": "npm run lint && npm run unit",
-    "unit": "nyc --reporter=html --reporter=text --reporter=text-summary --check-coverage=true --statements=98 --branches=90 --lines=98 --functions=100 mocha tests/lib/**/*.js",
-    "lint": "eslint ."
+    "unit": "npx nyc --reporter=html --reporter=text --reporter=text-summary --reporter=lcov --check-coverage=true --statements=100 --branches=100 --lines=100 --functions=100 mocha tests/lib/*.js tests/lib/**/*.js"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.32.0",
-    "eslint": "^9.32.0",
-    "eslint-plugin-jsdoc": "^52.0.4",
-    "mocha": "^11.7.1",
+    "@eslint/js": "^9.39.1",
+    "@eslint/markdown": "^7.5.1",
+    "@stylistic/eslint-plugin": "^5.5.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-eslint-plugin": "^7.2.0",
+    "eslint-plugin-jsdoc": "^61.1.12",
+    "eslint-plugin-n": "^17.23.1",
+    "mocha": "^11.7.5",
     "nyc": "^17.1.0",
     "testdouble": "^3.20.2"
   },