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

package/README.md

@@ -10,17 +10,18 @@ defined in the rule settings.
 ## Table of Contents
 
 1. [Scope and Acknowledgements](#scope-and-acknowledgements)
-2. [Usage](#usage)
+2. [Compatibility](#compatibility)
+3. [Usage](#usage)
    1. [File-based Configuration](#file-based-configuration)
    2. [Inline Configuration](#inline-configuration)
       1. [Header Contents Configuration](#header-contents-configuration)
       2. [Trailing Empty Lines Configuration](#trailing-empty-lines-configuration)
       3. [Line Endings](#line-endings)
-3. [Examples](#examples)
-4. [Versioning](#versioning)
+4. [Examples](#examples)
+5. [Versioning](#versioning)
    1. [What is a Feature?](#what-is-a-feature)
    2. [What is Backward-compatibility?](#what-is-backward-compatibility)
-5. [License](#license)
+6. [License](#license)
 
 ## Scope and Acknowledgements
 
@@ -39,6 +40,15 @@ It addresses the following issus:
   forward. This would come at the expense of plugin compatibility and the
   portability of fixes to the upstream repository.
 
+## Compatibility
+
+The plugin supports ESLint 7 / 8 / 9 / 10rc0 (check package.json for details).
+Both flat config and legacy, hierarchical config can be used.
+
+The NPM package provides TypeScript type definitions and can be used with
+TypeScript-based ESLint flat configuration without the need for `@ts-ignore`
+statements.
+
 ## Usage
 
 This rule takes between 1 and 4 arguments after the rule validation severity.
@@ -61,6 +71,12 @@ The configuration can take any of the following forms:
     {<settings>}]` - define the header contents inline and an expected number of
     empty lines after the header and pass additional settings.
 
+For TypesScript-based flat ESLint configuration, the following type is provided:
+
+- `HeaderRuleConfig` defines the overall rule configuration for the `header`
+  rule and includes severity level and supports both the modern object-based
+  configuration and the legacy array-based configuration.
+
 ### File-based Configuration
 
 In this configuration mode, the first argument is a string pointing to a JS
@@ -440,7 +456,7 @@ The following guidelines apply:
 - **major versions** - new functionality that breaks compatibility.
 - **minor versions** - new features that do not break compatibility. For the
   most part we would aim to continue releasing new versions in the 3.x product
-  line and have opt-in flags for changes in behavior of existign features.
+  line and have opt-in flags for changes in behavior of existing features.
 - **revisions** - bugfixes and minor non-feature improvements that do not break
   compatibility. Note that bug-fixes are allowed to break compatibility with
   previous version if the older version regressed previous expected behavior.

package/index.d.ts

@@ -0,0 +1,29 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026-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.
+ */
+
+export { HeaderOptions, HeaderRuleConfig } from "./types/lib/rules/header";
+
+import plugin = require("./types");
+
+export default plugin;

package/index.js

@@ -24,11 +24,13 @@
 
 "use strict";
 
-module.exports = {
+const { header } = require("./lib/rules/header");
+
+/** @type {import('eslint').ESLint.Plugin} */
+const pluginDefinition = {
     rules: {
-        "header": require("./lib/rules/header")
-    },
-    rulesConfig: {
-        "header": 0
+        header
     }
 };
+
+module.exports = pluginDefinition;

package/lib/comment-parser.js

@@ -24,7 +24,7 @@
 
 "use strict";
 
-const assert = require("assert");
+const assert = require("node:assert");
 
 /**
  * Parses a line or block comment and returns the type of comment and an array

package/lib/rules/eslint-utils.js

@@ -0,0 +1,42 @@
+/*
+ * 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";
+
+/**
+ * @typedef {import('eslint').Rule.RuleContext} RuleContext
+ * @typedef {import('eslint').SourceCode} SourceCode
+ */
+
+module.exports = {
+    /**
+     * Provides compatibility wrapper for ESLint 7 through 10 for getting the
+     * full source code object from the execution context.
+     * @param {RuleContext} context ESLint execution context.
+     * @returns {SourceCode} the source-code object.
+     */
+    contextSourceCode: function(context) {
+        return context.sourceCode || context.getSourceCode();
+    }
+};

package/lib/rules/header.docs.js

@@ -29,11 +29,11 @@ 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 packageJsonContent = fs.readFileSync(path.resolve(__dirname, "../../package.json"), "utf8");
 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;
+const pluginVersion = packageJson.version;
 
 exports.description = "";
 exports.recommended = true;

package/lib/rules/header.js

@@ -24,10 +24,11 @@
 
 "use strict";
 
-const assert = require("assert");
-const fs = require("fs");
-const os = require("os");
+const assert = require("node:assert");
+const fs = require("node:fs");
+const os = require("node:os");
 const commentParser = require("../comment-parser");
+const { contextSourceCode } = require("./eslint-utils");
 const { description, recommended, url } = require("./header.docs");
 const { commentTypeOptions, lineEndingOptions, schema } = require("./header.schema");
 
@@ -37,8 +38,6 @@ const { commentTypeOptions, lineEndingOptions, schema } = require("./header.sche
  * @typedef {import('eslint').Rule.NodeListener} NodeListener
  * @typedef {import('eslint').Rule.ReportFixer} ReportFixer
  * @typedef {import('eslint').Rule.RuleFixer} RuleFixer
- * @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
@@ -46,26 +45,36 @@ const { commentTypeOptions, lineEndingOptions, schema } = require("./header.sche
  */
 
 /**
- * Local type defintions.
- * @typedef {string | { pattern: string, template?: string }} HeaderLine
+ * Local type definitions.
+ * @typedef {{ pattern: string, template?: string }} HeaderLinePattern
+ * @typedef {string | HeaderLinePattern} 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 {'unix' | 'windows'} LineEndingOption
+ * @typedef {{ lineEndings?: LineEndingOption }} HeaderSettings
+ * @typedef {'block' | 'line'} CommentType
+ * @typedef {[template: string] |
+ *  [template: string, settings: HeaderSettings] |
+ *  [type: CommentType, lines: HeaderLines] |
+ *  [type: CommentType, lines: HeaderLines, settings: HeaderSettings] |
+ *  [type: CommentType, lines: HeaderLines, minLines: number] |
+ *  [
+ *     type: CommentType,
+ *     lines: HeaderLines,
+ *     minLines: number,
+ *     settings: HeaderSettings
+ *  ]
+ * } AllHeaderOptions
+ * @typedef {import('eslint').Linter.RuleEntry<AllHeaderOptions>
+ * } HeaderRuleConfig
  */
 
 /**
  * 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-defining
- *                    object or `false` otherwise.
+ * @returns {object is HeaderLinePattern} `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");
@@ -74,13 +83,13 @@ function isPattern(object) {
 /**
  * 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.
+ * @param {string} actual the string to test.
+ * @param {string | RegExp} expected The string or regex to test again.
  * @returns {boolean} `true` if the passed string matches the expected line
  *                    config or `false` otherwise.
  */
 function match(actual, expected) {
-    if (expected.test) {
+    if (expected instanceof RegExp) {
         return expected.test(actual);
     } else {
         return expected === actual;
@@ -89,34 +98,62 @@ 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
+ * @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.
  */
 function excludeShebangs(comments) {
+    /** @type {Comment[]} */
     return comments.filter(function(comment) {
         return comment.type !== "Shebang";
     });
 }
 
+/**
+ * TypeScript helper to confirm defined type.
+ * @template T
+ * @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");
+}
+
+/**
+ * TypeScript helper to confirm non-null type.
+ * @template T
+ * @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);
+}
+
 /**
  * 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.
- * @param {Program} node ESLint AST treee node being processed.
  * @returns {Comment[]} lines that constitute the leading comment.
  */
-function getLeadingComments(context, node) {
-    const all = excludeShebangs(context.sourceCode.getAllComments(node.body.length ? node.body[0] : node));
+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 txt = context.sourceCode.text.slice(all[i - 1].range[1], all[i].range[0]);
+        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;
         }
@@ -127,7 +164,7 @@ function getLeadingComments(context, node) {
 /**
  * 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 {CommentType} 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.
  * @returns {string} resulting comment.
@@ -145,12 +182,21 @@ function genCommentBody(commentType, textArray, eol) {
 /**
  * Determines the start and end position in the source code of the leading
  * comment.
- * @param {string[]} comments list of comments.
+ * @param {Comment[]} comments list of comments.
  * @returns {[number, number]} resulting range.
  */
 function genCommentsRange(comments) {
-    const start = comments[0].range[0];
-    const end = comments.slice(-1)[0].range[1];
+    assert.ok(comments.length);
+    const firstComment = comments[0];
+    assertDefined(firstComment);
+    const firstCommentRange = firstComment.range;
+    assertDefined(firstCommentRange);
+    const start = firstCommentRange[0];
+    const lastComment = comments.slice(-1)[0];
+    assertDefined(lastComment);
+    const lastCommentRange = lastComment.range;
+    assertDefined(lastCommentRange);
+    const end = lastCommentRange[1];
     return [start, end];
 }
 
@@ -176,7 +222,7 @@ function leadingEmptyLines(src) {
 
 /**
  * Factory for fixer that adds a missing header.
- * @param {'block' | 'line'} commentType type of comment to use.
+ * @param {CommentType} commentType type of comment to use.
  * @param {RuleContext} context ESLint execution runtime.
  * @param {string[]} headerLines lines of the header comment.
  * @param {'\n' | '\r\n'} eol end-of-line characters
@@ -186,15 +232,16 @@ function leadingEmptyLines(src) {
 function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
     return function(fixer) {
         let insertPos = 0;
-        let newHeader = genCommentBody(commentType, headerLines, eol, numNewlines);
-        if (context.sourceCode.text.startsWith("#!")) {
-            const firstNewLinePos = context.sourceCode.text.indexOf("\n");
-            insertPos = firstNewLinePos === -1 ? context.sourceCode.text.length : firstNewLinePos + 1;
+        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;
             if (firstNewLinePos === -1) {
                 newHeader = eol + newHeader;
             }
         }
-        const numEmptyLines = leadingEmptyLines(context.sourceCode.text.substring(insertPos));
+        const numEmptyLines = leadingEmptyLines(sourceCode.text.substring(insertPos));
         const additionalEmptyLines = Math.max(0, numNewlines - numEmptyLines);
         newHeader += eol.repeat(additionalEmptyLines);
         return fixer.insertTextBeforeRange(
@@ -206,25 +253,23 @@ function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
 
 /**
  * Factory for fixer that replaces an incorrect header.
- * @param {'block' | 'line'} commentType type of comment to use.
+ * @param {CommentType} commentType type of comment to use.
  * @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: RuleFixer) => Fix | Fix[] | 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 emptyLines = leadingEmptyLines(contextSourceCode(context).text.substring(commentRange[1]));
         const missingNewlines = Math.max(0, numNewlines - emptyLines);
         const eols = eol.repeat(missingNewlines);
         return fixer.replaceTextRange(
             commentRange,
-            genCommentBody(commentType, headerLines, eol, numNewlines) + eols
+            genCommentBody(commentType, headerLines, eol) + eols
         );
     };
 }
@@ -235,9 +280,7 @@ function genReplaceFixer(commentType, context, leadingComments, headerLines, eol
  * @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.
+ * @returns {(fixer: RuleFixer) => Fix | Fix[] | null} the fixer.
  */
 function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
     return function(fixer) {
@@ -250,7 +293,7 @@ function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
 
 /**
  * Finds the option parameter within the list of rule config options.
- * @param {HeaderOptions} options the config options passed to the rule.
+ * @param {AllHeaderOptions} options the config options passed to the rule.
  * @returns {HeaderSettings | null} the settings parameter or `null` if no such
  *                                  is defined.
  */
@@ -258,7 +301,7 @@ function findSettings(options) {
     const lastOption = options[options.length - 1];
     if (typeof lastOption === "object" && !Array.isArray(lastOption) && lastOption !== null
         && !Object.prototype.hasOwnProperty.call(lastOption, "pattern")) {
-        return lastOption;
+        return /** @type {HeaderSettings} */ (lastOption);
     }
     return null;
 }
@@ -266,7 +309,7 @@ function findSettings(options) {
 /**
  * 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.
+ * @param {AllHeaderOptions} options rule configuration.
  * @returns {'\n' | '\r\n'} the correct line ending characters for the
  * environment.
  */
@@ -280,7 +323,7 @@ function getEOL(options) {
             return "\r\n";
         }
     }
-    return os.EOL;
+    return /** @type {'\n' | '\r\n'} */ (os.EOL);
 }
 
 /**
@@ -308,7 +351,11 @@ function hasHeader(src) {
  * @returns {SourceLocation} the location (line and column) of the violation.
  */
 function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
-    const lastCommentLineLocEnd = leadingComments[leadingComments.length - 1].loc.end;
+    assert.ok(leadingComments);
+    const loc = leadingComments[leadingComments.length - 1].loc;
+    assertDefined(loc);
+    assertNotNull(loc);
+    const lastCommentLineLocEnd = loc.end;
     return {
         start: lastCommentLineLocEnd,
         end: {
@@ -318,7 +365,8 @@ function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
     };
 }
 
-module.exports = {
+/** @type {import('eslint').Rule.RuleModule} */
+const headerRule = {
     meta: {
         type: "layout",
         docs: {
@@ -348,7 +396,7 @@ module.exports = {
      * @returns {NodeListener} the rule definition.
      */
     create: function(context) {
-        let options = context.options;
+        let options = /** @type {AllHeaderOptions} */ (context.options);
         const numNewlines = options.length > 2 && typeof options[2] === "number" ? options[2] : 1;
         const eol = getEOL(options);
 
@@ -358,9 +406,10 @@ module.exports = {
             options = commentParser(text);
         }
 
-        const commentType = options[0].toLowerCase();
-        /** @type {(string | RegExp)[]} */
+        const commentType = /** @type {CommentType} */ (options[0].toLowerCase());
+        /** @type {(string | RegExp)[] | string[]} */
         let headerLines;
+        /** @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
@@ -371,34 +420,42 @@ module.exports = {
             headerLines = options[1].map(function(line) {
                 const isRegex = isPattern(line);
                 // Can only fix regex option if a template is also provided
-                if (isRegex && !line.template) {
-                    canFix = false;
+                if (isRegex) {
+                    if (line.template) {
+                        fixLines.push(line.template);
+                    } else {
+                        canFix = false;
+                    }
+                    return new RegExp(line.pattern);
+                } else {
+                    fixLines.push(line);
+                    return line;
                 }
-                fixLines.push(line.template || line);
-                return isRegex ? new RegExp(line.pattern) : line;
             });
-        } else if (isPattern(options[1])) {
-            const line = options[1];
-            headerLines = [new RegExp(line.pattern)];
-            fixLines.push(line.template || line);
-            // Same as above for regex and template
-            canFix = !!line.template;
         } else {
-            canFix = true;
-            headerLines = options[1].split(/\r?\n/);
-            fixLines = headerLines;
+            const line = /** @type {HeaderLine} */ (options[1]);
+            if (isPattern(line)) {
+                headerLines = [new RegExp(line.pattern)];
+                fixLines.push(line.template || "");
+                // Same as above for regex and template
+                canFix = !!line.template;
+            } else {
+                canFix = true;
+                headerLines = line.split(/\r?\n/);
+                fixLines = /** @type {string[]} */ (headerLines);
+            }
         }
 
         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.text)) {
-                    const hasShebang = context.sourceCode.text.startsWith("#!");
+            Program: function() {
+                const sourceCode = contextSourceCode(context);
+                if (!hasHeader(sourceCode.text)) {
+                    const hasShebang = sourceCode.text.startsWith("#!");
                     const line = hasShebang ? 2 : 1;
                     context.report({
                         loc: {
@@ -416,13 +473,22 @@ module.exports = {
                     });
                     return;
                 }
-                const leadingComments = getLeadingComments(context, node);
+                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: leadingComments[0].loc.start,
-                            end: leadingComments[leadingComments.length - 1].loc.end
+                            start: firstLeadingCommentLoc.start,
+                            end: lastLeadingCommentLoc.end
                         },
                         messageId: "incorrectCommentType",
                         data: {
@@ -441,10 +507,14 @@ module.exports = {
                             !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: leadingComments[0].loc.start,
-                                    end: leadingComments[leadingComments.length - 1].loc.end
+                                    start: firstLeadingCommentLoc.start,
+                                    end: lastLeadingCommentLoc.end
                                 },
                                 messageId: "incorrectHeader",
                                 fix: canFix
@@ -456,9 +526,12 @@ module.exports = {
                     } else {
                         for (let i = 0; i < headerLines.length; i++) {
                             if (leadingComments.length - 1 < i) {
+                                assertDefined(lastLeadingCommentLoc);
+                                assertNotNull(lastLeadingCommentLoc);
                                 context.report({
                                     loc: {
-                                        start: leadingComments[leadingComments.length - 1].loc.end
+                                        start: lastLeadingCommentLoc.end,
+                                        end: lastLeadingCommentLoc.end
                                     },
                                     messageId: "headerTooShort",
                                     data: {
@@ -476,22 +549,27 @@ module.exports = {
                                 });
                                 return;
                             }
-                            if (typeof headerLines[i] === "string") {
-                                const leadingCommentLength = leadingComments[i].value.length;
-                                const headerLineLength = headerLines[i].length;
+                            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 (leadingComments[i].value[j] !== headerLines[i][j]) {
+                                    if (comment.value[j] !== headerLine[j]) {
                                         context.report({
                                             loc: {
                                                 start: {
                                                     column: "//".length + j,
-                                                    line: leadingComments[i].loc.start.line
+                                                    line: commentLoc.start.line
                                                 },
-                                                end: leadingComments[i].loc.end
+                                                end: commentLoc.end
                                             },
                                             messageId: "headerLineMismatchAtPos",
                                             data: {
-                                                expected: headerLines[i].substring(j)
+                                                expected: headerLine.substring(j)
                                             },
                                             fix: genReplaceFixer(
                                                 commentType,
@@ -507,11 +585,12 @@ module.exports = {
                                 if (leadingCommentLength < headerLineLength) {
                                     context.report({
                                         loc: {
-                                            start: leadingComments[i].loc.end,
+                                            start: commentLoc.end,
+                                            end: commentLoc.end,
                                         },
                                         messageId: "headerLineTooShort",
                                         data: {
-                                            remainder: headerLines[i].substring(leadingCommentLength)
+                                            remainder: headerLine.substring(leadingCommentLength)
                                         },
                                         fix: canFix
                                             ? genReplaceFixer(
@@ -530,9 +609,9 @@ module.exports = {
                                         loc: {
                                             start: {
                                                 column: "//".length + headerLineLength,
-                                                line: leadingComments[i].loc.start.line
+                                                line: commentLoc.start.line
                                             },
-                                            end: leadingComments[i].loc.end,
+                                            end: commentLoc.end,
                                         },
                                         messageId: "headerLineTooLong",
                                         fix: canFix
@@ -548,18 +627,18 @@ module.exports = {
                                     return;
                                 }
                             } else {
-                                if (!match(leadingComments[i].value, headerLines[i])) {
+                                if (!match(comment.value, headerLine)) {
                                     context.report({
                                         loc: {
                                             start: {
                                                 column: "//".length,
-                                                line: leadingComments[i].loc.start.line,
+                                                line: commentLoc.start.line,
                                             },
-                                            end: leadingComments[i].loc.end,
+                                            end: commentLoc.end,
                                         },
                                         messageId: "incorrectHeaderLine",
                                         data: {
-                                            pattern: headerLines[i]
+                                            pattern: headerLine
                                         },
                                         fix: canFix
                                             ? genReplaceFixer(
@@ -577,8 +656,9 @@ module.exports = {
                         }
                     }
 
-                    const actualLeadingEmptyLines = leadingEmptyLines(
-                        context.sourceCode.text.substring(leadingComments[headerLines.length - 1].range[1]));
+                    const commentRange = leadingComments[headerLines.length - 1].range;
+                    assertDefined(commentRange);
+                    const actualLeadingEmptyLines = leadingEmptyLines(sourceCode.text.substring(commentRange[1]));
                     const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
                     if (missingEmptyLines > 0) {
                         context.report({
@@ -602,8 +682,8 @@ module.exports = {
 
                 /** @type {null | string} */
                 let errorMessageId = null;
-                /** @type {null | Record<string, string | RegExp>} */
-                let errorMessageData = null;
+                /** @type {undefined | Record<string, string | RegExp>} */
+                let errorMessageData;
                 /** @type {null | SourceLocation} */
                 let errorMessageLoc = null;
                 for (let i = 0; i < headerLines.length; i++) {
@@ -614,7 +694,9 @@ module.exports = {
                             if (leadingLine[j] !== headerLine[j]) {
                                 errorMessageId = "headerLineMismatchAtPos";
                                 const columnOffset = i === 0 ? "/*".length : 0;
-                                const line = leadingComments[0].loc.start.line + i;
+                                assertDefined(firstLeadingCommentLoc);
+                                assertNotNull(firstLeadingCommentLoc);
+                                const line = firstLeadingCommentLoc.start.line + i;
                                 errorMessageLoc = {
                                     start: {
                                         column: columnOffset + j,
@@ -637,31 +719,35 @@ module.exports = {
                         if (leadingLine.length < headerLine.length) {
                             errorMessageId = "headerLineTooShort";
                             const startColumn = (i === 0 ? "/*".length : 0) + leadingLine.length;
+                            assertDefined(firstLeadingCommentLoc);
+                            assertNotNull(firstLeadingCommentLoc);
                             errorMessageLoc = {
                                 start: {
                                     column: startColumn,
-                                    line: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 },
                                 end: {
                                     column: startColumn + 1,
-                                    line: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 }
                             };
                             errorMessageData = {
-                                remainder: headerLines[i].substring(leadingLine.length)
+                                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: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 },
                                 end: {
                                     column: (i === 0 ? "/*".length : 0) + leadingLine.length,
-                                    line: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 }
                             };
                             break;
@@ -673,14 +759,16 @@ module.exports = {
                                 pattern: headerLine
                             };
                             const columnOffset = i === 0 ? "/*".length : 0;
+                            assertDefined(firstLeadingCommentLoc);
+                            assertNotNull(firstLeadingCommentLoc);
                             errorMessageLoc = {
                                 start: {
                                     column: columnOffset + 0,
-                                    line: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 },
                                 end: {
                                     column: columnOffset + leadingLine.length,
-                                    line: leadingComments[0].loc.start.line + i
+                                    line: firstLeadingCommentLoc.start.line + i
                                 }
                             };
                             break;
@@ -690,14 +778,18 @@ module.exports = {
 
                 if (!errorMessageId && leadingLines.length > headerLines.length) {
                     errorMessageId = "headerTooLong";
+                    assertDefined(firstLeadingCommentLoc);
+                    assertNotNull(firstLeadingCommentLoc);
+                    assertDefined(lastLeadingCommentLoc);
+                    assertNotNull(lastLeadingCommentLoc);
                     errorMessageLoc = {
                         start: {
                             column: (headerLines.length === 0 ? "/*".length : 0) + 0,
-                            line: leadingComments[0].loc.start.line + headerLines.length
+                            line: firstLeadingCommentLoc.start.line + headerLines.length
                         },
                         end: {
-                            column: leadingComments[leadingComments.length - 1].loc.end.column - "*/".length,
-                            line: leadingComments[leadingComments.length - 1].loc.end.line
+                            column: lastLeadingCommentLoc.end.column - "*/".length,
+                            line: lastLeadingCommentLoc.end.line
                         }
                     };
                 }
@@ -706,6 +798,7 @@ module.exports = {
                     if (canFix && headerLines.length > 1) {
                         fixLines = [fixLines.join(eol)];
                     }
+                    assertNotNull(errorMessageLoc);
                     context.report({
                         loc: errorMessageLoc,
                         messageId: errorMessageId,
@@ -717,8 +810,8 @@ module.exports = {
                     return;
                 }
 
-                const actualLeadingEmptyLines = leadingEmptyLines(
-                    context.sourceCode.text.substring(leadingComments[0].range[1]));
+                const actualLeadingEmptyLines =
+                    leadingEmptyLines(sourceCode.text.substring(firstLeadingCommentRange[1]));
                 const missingEmptyLines = numNewlines - actualLeadingEmptyLines;
                 if (missingEmptyLines > 0) {
                     context.report({
@@ -735,3 +828,5 @@ module.exports = {
         };
     }
 };
+
+exports.header = headerRule;

package/lib/rules/header.schema.js

@@ -41,6 +41,7 @@ const commentTypeOptions = Object.freeze({
     line: "line"
 });
 
+/** @type {import('json-schema').JSONSchema4} */
 const schema = Object.freeze({
     $ref: "#/definitions/options",
     definitions: {

package/package.json

@@ -1,31 +1,47 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.1.11",
+  "version": "3.1.13",
   "description": "ESLint plugin to ensure files begin with a given comment, usually a copyright or license notice.",
   "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.js"
+    }
+  },
   "files": [
-    "/lib/**/*.js",
-    "!/lib/rules/test-utils.js"
+    "lib/**/*.js",
+    "index.d.ts*",
+    "types",
+    "!lib/rules/test-utils.js"
   ],
   "scripts": {
+    "build": "npx tsc",
+    "e2e": "npm run build && npx mocha --timeout 60000 tests/e2e/*.js",
     "eslint": "npx eslint .",
     "lint": "npm run eslint && npm run markdownlint",
     "markdownlint": "npx markdownlint-cli *.md",
-    "test": "npm run lint && npm run unit",
+    "test": "npm run lint && npm run unit && npm run e2e",
     "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.39.1",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
     "@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",
+    "@stylistic/eslint-plugin": "^5.7.1",
+    "@types/node": "^25.2.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-eslint-plugin": "^7.3.0",
+    "eslint-plugin-jsdoc": "^62.5.2",
+    "eslint-plugin-n": "^17.23.2",
+    "markdownlint-cli": "^0.47.0",
+    "mocha": "^12.0.0-beta-6",
     "nyc": "^17.1.0",
-    "testdouble": "^3.20.2"
+    "testdouble": "^3.20.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
   },
   "peerDependencies": {
     "eslint": ">=7.7.0"
@@ -40,7 +56,7 @@
   },
   "author": "Stuart Knightley",
   "license": "MIT",
-  "contributors": [
+  "maintainers": [
     "Tony Ganchev"
   ]
 }

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export = pluginDefinition;
+/** @type {import('eslint').ESLint.Plugin} */
+declare const pluginDefinition: import("eslint").ESLint.Plugin;
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":";AA4BA,6CAA6C;AAC7C,gCADW,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,CAKvC"}

package/types/lib/comment-parser.d.ts

@@ -0,0 +1,3 @@
+declare function _exports(commentText: string): ["block" | "line", string | string[]];
+export = _exports;
+//# sourceMappingURL=comment-parser.d.ts.map

package/types/lib/comment-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-parser.d.ts","sourceRoot":"","sources":["../../lib/comment-parser.js"],"names":[],"mappings":"AAsCiB,uCAJN,MAAM,GACJ,CAAC,OAAO,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAmBjD"}

package/types/lib/rules/eslint-utils.d.ts

@@ -0,0 +1,10 @@
+declare namespace _exports {
+    export { RuleContext, SourceCode };
+}
+declare namespace _exports {
+    function contextSourceCode(context: RuleContext): SourceCode;
+}
+export = _exports;
+type RuleContext = import("eslint").Rule.RuleContext;
+type SourceCode = import("eslint").SourceCode;
+//# sourceMappingURL=eslint-utils.d.ts.map

package/types/lib/rules/eslint-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eslint-utils.d.ts","sourceRoot":"","sources":["../../../lib/rules/eslint-utils.js"],"names":[],"mappings":";;;;IAsCuB,oCAHR,WAAW,GACT,UAAU,CAItB;;;mBAbQ,OAAO,QAAQ,EAAE,IAAI,CAAC,WAAW;kBACjC,OAAO,QAAQ,EAAE,UAAU"}

package/types/lib/rules/header.d.ts

@@ -0,0 +1,73 @@
+export { headerRule as header };
+/**
+ * Import type definitions.
+ */
+export type Fix = import("eslint").Rule.Fix;
+/**
+ * Import type definitions.
+ */
+export type NodeListener = import("eslint").Rule.NodeListener;
+/**
+ * Import type definitions.
+ */
+export type ReportFixer = import("eslint").Rule.ReportFixer;
+/**
+ * Import type definitions.
+ */
+export type RuleFixer = import("eslint").Rule.RuleFixer;
+/**
+ * Import type definitions.
+ */
+export type RuleContext = import("eslint").Rule.RuleContext;
+/**
+ * Import type definitions.
+ */
+export type Comment = import("estree").Comment;
+/**
+ * Import type definitions.
+ */
+export type Program = import("estree").Program;
+/**
+ * Import type definitions.
+ */
+export type SourceLocation = import("estree").SourceLocation;
+/**
+ * Local type definitions.
+ */
+export type HeaderLinePattern = {
+    pattern: string;
+    template?: string;
+};
+/**
+ * Local type definitions.
+ */
+export type HeaderLine = string | HeaderLinePattern;
+/**
+ * Local type definitions.
+ */
+export type HeaderLines = (HeaderLine | HeaderLine[]);
+/**
+ * Local type definitions.
+ */
+export type LineEndingOption = "unix" | "windows";
+/**
+ * Local type definitions.
+ */
+export type HeaderSettings = {
+    lineEndings?: LineEndingOption;
+};
+/**
+ * Local type definitions.
+ */
+export type CommentType = "block" | "line";
+/**
+ * Local type definitions.
+ */
+export type AllHeaderOptions = [template: string] | [template: string, settings: HeaderSettings] | [type: CommentType, lines: HeaderLines] | [type: CommentType, lines: HeaderLines, settings: HeaderSettings] | [type: CommentType, lines: HeaderLines, minLines: number] | [type: CommentType, lines: HeaderLines, minLines: number, settings: HeaderSettings];
+/**
+ * Local type definitions.
+ */
+export type HeaderRuleConfig = import("eslint").Linter.RuleEntry<AllHeaderOptions>;
+/** @type {import('eslint').Rule.RuleModule} */
+declare const headerRule: import("eslint").Rule.RuleModule;
+//# sourceMappingURL=header.d.ts.map

package/types/lib/rules/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.js"],"names":[],"mappings":";;;;kBAoCa,OAAO,QAAQ,EAAE,IAAI,CAAC,GAAG;;;;2BACzB,OAAO,QAAQ,EAAE,IAAI,CAAC,YAAY;;;;0BAClC,OAAO,QAAQ,EAAE,IAAI,CAAC,WAAW;;;;wBACjC,OAAO,QAAQ,EAAE,IAAI,CAAC,SAAS;;;;0BAC/B,OAAO,QAAQ,EAAE,IAAI,CAAC,WAAW;;;;sBACjC,OAAO,QAAQ,EAAE,OAAO;;;;sBACxB,OAAO,QAAQ,EAAE,OAAO;;;;6BACxB,OAAO,QAAQ,EAAE,cAAc;;;;gCAK/B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;yBACtC,MAAM,GAAG,iBAAiB;;;;0BAC1B,CAAC,UAAU,GAAG,UAAU,EAAE,CAAC;;;;+BAC3B,MAAM,GAAG,SAAS;;;;6BAClB;IAAE,WAAW,CAAC,EAAE,gBAAgB,CAAA;CAAE;;;;0BAClC,OAAO,GAAG,MAAM;;;;+BAChB,CAAC,QAAQ,EAAE,MAAM,CAAC,GAC9B,CAAI,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,GAC/C,CAAI,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,GAC1C,CAAI,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC,GACpE,CAAI,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,GAC5D,CACM,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,CAC1B;;;;+BAEQ,OAAO,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC;AA6ShE,+CAA+C;AAC/C,0BADW,OAAO,QAAQ,EAAE,IAAI,CAAC,UAAU,CA8czC"}

package/types/lib/rules/header.docs.d.ts

@@ -0,0 +1,4 @@
+export const description: "";
+export const recommended: true;
+export const url: string;
+//# sourceMappingURL=header.docs.d.ts.map

package/types/lib/rules/header.docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.docs.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.docs.js"],"names":[],"mappings":""}

package/types/lib/rules/header.schema.d.ts

@@ -0,0 +1,20 @@
+export type lineEndingOptions = string;
+/**
+ * @enum {string}
+ */
+export const lineEndingOptions: Readonly<{
+    os: "os";
+    unix: "unix";
+    windows: "windows";
+}>;
+export type commentTypeOptions = string;
+/**
+ * @enum {string}
+ */
+export const commentTypeOptions: Readonly<{
+    block: "block";
+    line: "line";
+}>;
+/** @type {import('json-schema').JSONSchema4} */
+export const schema: import("json-schema").JSONSchema4;
+//# sourceMappingURL=header.schema.d.ts.map

package/types/lib/rules/header.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.schema.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.schema.js"],"names":[],"mappings":"gCA2BU,MAAM;AADhB;;GAEG;AACH;;;;GAIG;iCAGO,MAAM;AADhB;;GAEG;AACH;;;GAGG;AAEH,gDAAgD;AAChD,qBADW,OAAO,aAAa,EAAE,WAAW,CA0FzC"}

package/types/lib/rules/test-utils.d.ts

@@ -0,0 +1,10 @@
+declare namespace _exports {
+    export { InvalidTestCase, TestCaseError };
+}
+declare namespace _exports {
+    function generateInvalidTestCaseNames(invalidTests: InvalidTestCase[]): InvalidTestCase[];
+}
+export = _exports;
+type InvalidTestCase = import("eslint").RuleTester.InvalidTestCase;
+type TestCaseError = import("eslint").RuleTester.TestCaseError;
+//# sourceMappingURL=test-utils.d.ts.map

package/types/lib/rules/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../lib/rules/test-utils.js"],"names":[],"mappings":";;;;IA4EkC,oDAJnB,eAAe,EAAE,GACf,eAAe,EAAE,CA4B7B;;;uBAxEQ,OAAO,QAAQ,EAAE,UAAU,CAAC,eAAe;qBAC3C,OAAO,QAAQ,EAAE,UAAU,CAAC,aAAa"}