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

package/CONTRIBUTING.md

@@ -45,20 +45,20 @@ There are two product lines as of today:
 After cloning the repository you can try to do a full CI/CD run:
 
 ```bash
-$ npm install
+$ pnpm install
 ...
-$ npm run test
+$ pnpm run test
 ...
 ```
 
 It will run a number of other npm scripts that together verify the code:
 
-| script          | Description                                                |
-|-----------------|------------------------------------------------------------|
-| `npm run lint`  | Lints the source and docs.                                 |
-| `npm run unit`  | Runs all mocha unit tests.                                 |
-| `npm run build` | Generates TypeScript bindings. Prerequisite for E2E tests. |
-| `npm run e2e`   | Runs E2E smoke tests for all supported versions of ESLint. |
+| script       | Description                                                   |
+|--------------|---------------------------------------------------------------|
+| `pnpm lint`  | Lints the source and docs.                                    |
+| `pnpm unit`  | Runs all mocha unit tests.                                    |
+| `pnpm build` | Generates TypeScript bindings. Prerequisite for E2E tests.    |
+| `pnpm e2e`   | Runs E2E smoke tests for all supported versions of ESLint.    |
 
 ## Development
 

package/LICENSE.md

@@ -1,6 +1,7 @@
 # MIT License
 
-Copyright (c) 2015-present Stuart Knightley, Tony Ganchev and contributors
+Copyright (c) 2015-present Stuart Knightley and contributors
+Copyright (c) 2024-present Tony Ganchev
 
 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

package/index.d.ts

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2026-present Tony Ganchev and contributors
- *
+/**
+ * @file Entry point `index.js` type definitions to support TypeScript-based
+ * ESLint configuration. Ensures only the public interfaces are exposed.
+ * @copyright Copyright (c) 2026 Tony Ganchev
+ * @license MIT
  * 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

package/index.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
- *
+/**
+ * @file Entry point for the plugin.
+ * @copyright Copyright (c) 2015-present Stuart Knightley and contributors
+ * @copyright Copyright (c) 2025-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -26,7 +26,7 @@
 
 const { header } = require("./lib/rules/header");
 
-/** @type {import('eslint').ESLint.Plugin} */
+/** @type {import("eslint").ESLint.Plugin} */
 const pluginDefinition = {
     rules: {
         header

package/lib/comment-parser.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
- *
+/**
+ * @file Parsing utility for JavaScript comments to get text content and type.
+ * @copyright Copyright (c) 2015-present Stuart Knightley and contributors
+ * @copyright Copyright (c) 2025-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -32,9 +32,10 @@ const assert = require("node:assert");
  *
  * 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.
+ * @param {string} commentText Content to parse.
+ * @returns {[import("./rules/header").CommentType, string[]]} Comment type and
+ * comment content broken into lines.
+ * @throws {Error} If `commentText` starts with an unrecognized comment token.
  */
 module.exports = function commentParser(commentText) {
     assert.strictEqual(typeof commentText, "string");

package/lib/rules/eslint-utils.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2025-present Tony Ganchev and contributors
- *
+/**
+ * @file Utilities to bridge incompatible versions of ESLint APIs. Currently it
+ * wraps methods removed in ESLint 10 but required for ESLint 7.
+ * @copyright Copyright (c) 2025-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -25,8 +25,8 @@
 "use strict";
 
 /**
- * @typedef {import('eslint').Rule.RuleContext} RuleContext
- * @typedef {import('eslint').SourceCode} SourceCode
+ * @typedef {import("eslint").Rule.RuleContext} RuleContext
+ * @typedef {import("eslint").SourceCode} SourceCode
  */
 
 module.exports = {
@@ -34,7 +34,7 @@ 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.
+     * @returns {SourceCode} The source-code object.
      */
     contextSourceCode: function(context) {
         return context.sourceCode

package/lib/rules/header.docs.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2025-present Tony Ganchev and contributors
- *
+/**
+ * @file Constants to use when constructing the metadata of the `header` rule.
+ * It aims to reduce the size of the already large main header.js.
+ * @copyright Copyright (c) 2025-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -22,7 +22,6 @@
  * SOFTWARE.
  */
 
-
 "use strict";
 
 exports.description = "The rule validates that the source file starts with a specific header comment pattern.";

package/lib/rules/header.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2015-present Stuart Knightley, Tony Ganchev, and contributors
- *
+/**
+ * @file Header validation rule implementation.
+ * @copyright Copyright (c) 2015-present Stuart Knightley and contributors
+ * @copyright Copyright (c) 2024-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -33,66 +33,117 @@ const { description, recommended } = require("./header.docs");
 const { lineEndingOptions, commentTypeOptions, schema } = require("./header.schema");
 
 /**
- * Import type definitions.
- * @typedef {import('eslint').Rule.Fix} Fix
- * @typedef {import('eslint').Rule.NodeListener} NodeListener
- * @typedef {import('eslint').Rule.ReportFixer} ReportFixer
- * @typedef {import('eslint').Rule.RuleFixer} RuleFixer
- * @typedef {import('eslint').Rule.RuleContext} RuleContext
- * @typedef {import('estree').Comment} Comment
- * @typedef {import('estree').Program} Program
- * @typedef {import("estree").SourceLocation} SourceLocation
- */
-
-/**
- * Local type definitions.
- * @typedef {{ pattern: string | RegExp, template?: string }} HeaderLinePattern
- * @typedef {string | RegExp | HeaderLinePattern} HeaderLine
- * @typedef {HeaderLine | HeaderLine[]} HeaderLines
- * @typedef {'os' | 'unix' | 'windows'} LineEndingOption
- * @typedef {{ lineEndings?: LineEndingOption }} HeaderSettings
- * @typedef {'block' | 'line'} CommentType
- * @typedef {{
- *      file: string,
- *      encoding?: BufferEncoding
- *  }
- * } FileBasedConfig
- * @typedef {{
- *      commentType: CommentType,
- *      lines: HeaderLine[]
- *  }
- * } InlineConfig
- * @typedef {{ minimum?: number }} TrailingEmptyLines
- * @typedef {{
- *      header: FileBasedConfig | InlineConfig,
- *      trailingEmptyLines?: TrailingEmptyLines
- *  }
- *  & HeaderSettings
- * } HeaderOptions
- * @typedef {[HeaderOptions] |
- *  [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
+ * @import { Linter, Rule } from "eslint"
+ * @import { Comment, SourceLocation, Program } from "estree"
+ * @typedef {Rule.NodeListener} NodeListener
+ * @typedef {Rule.ReportFixer} ReportFixer
+ * @typedef {Rule.RuleFixer} RuleFixer
+ * @typedef {Rule.RuleContext} RuleContext
+ */
+
+/**
+ * @typedef {"\n" | "\r\n"} LineEnding The sequence of characters that define
+ * the end of a line.
+ */
+
+/**
+ * @typedef {object} HeaderLinePattern Matching rule for a line from the header
+ * using regular expression and optionally providing an auto-fix replacement.
+ * @property {string | RegExp} pattern A regular expression that should match
+ * the header line.
+ * @property {string} [template] When set, if the actual header line does not
+ * match `pattern`, this value is to be used when running auto-fix.
+ */
+
+/**
+ * @typedef {string | RegExp | HeaderLinePattern} HeaderLine Matching rule for
+ * a single line of the header comment or the header comment as a whole if only
+ * one used.
+ * @typedef {HeaderLine | HeaderLine[]} HeaderLines The set of header comment-
+ * matching rules.
+ * @typedef {"os" | "unix" | "windows"} LineEndingOption Defines what EOL
+ * characters to expect - either forced to be Windows / POSIX-compatible, or
+ * defaulting to whatever the OS expects.
+ * @typedef {{ lineEndings?: LineEndingOption }} HeaderSettings How to treat
+ * line endings.
+ * @typedef {"block" | "line"} CommentType The expected type of comment to use
+ * for the header.
+ */
+
+/**
+ * @typedef {object} FileBasedConfig Header content configuration defined in a
+ * separate JavaScript template file.
+ * @property {string} file Template file path relative to the directory
+ * from which ESLint runs.
+ * @property {BufferEncoding} [encoding] Encoding to use when reading the
+ * file. If omitted, `"utf8"` will be assumed.
+ */
+
+/**
+ * @typedef {object} InlineConfig Header content configuration defined inline
+ * within the ESLint configuration.
+ * @property {CommentType} commentType The type of comment to expect.
+ * @property {HeaderLine[]} lines Matching rules for lines. If only one rule
+ * is provided, the rule would attempt to match either the first line ar all
+ * lines together.
+ */
+
+/**
+ * @typedef {object} TrailingEmptyLines Rule configuration on the handling of
+ * empty lines after the header comment.
+ * @property {number} [minimum] If set, the rule would check that at least
+ * a `minimum` number of EOL characters trail the header.
+ */
+
+/**
+ * @typedef {object} HeaderOptionsWithoutSettings
+ * @property {FileBasedConfig | InlineConfig} header The text matching rules
+ * for the header.
+ * @property {TrailingEmptyLines} [trailingEmptyLines] Rules about empty lines
+ * after the header comment.
+ */
+
+/**
+ * @typedef {HeaderOptionsWithoutSettings & HeaderSettings} HeaderOptions Modern
+ * object-based rule configuration.
+ */
+
+/**
+ * @typedef {[template: string]} LegacyFileBasedConfig
+ * @typedef {[template: string, settings: HeaderSettings]
+ * } LegacyFileBasedSettingsConfig
+ * @typedef {[type: CommentType, lines: HeaderLines]} LegacyInlineConfig
+ * @typedef {[type: CommentType, lines: HeaderLines, settings: HeaderSettings]
+ * } LegacyInlineSettingsConfig
+ * @typedef {[type: CommentType, lines: HeaderLines, minLines: number]
+ * } LegacyInlineMinLinesConfig
+ * @typedef {[
+ * type: CommentType,
+ * lines: HeaderLines,
+ * minLines: number,
+ * settings: HeaderSettings
+ * ]} LegacyInlineMinLinesSettingsConfig
+ * @typedef {[HeaderOptions]
+ * | LegacyFileBasedConfig
+ * | LegacyFileBasedSettingsConfig
+ * | LegacyInlineConfig
+ * | LegacyInlineSettingsConfig
+ * | LegacyInlineMinLinesConfig
+ * | LegacyInlineMinLinesSettingsConfig
+ * } AllHeaderOptions Full possible rule configuration options.
+ */
+
+/**
+ * @typedef {Linter.RuleEntry<AllHeaderOptions>} HeaderRuleConfig Rule
+ * configuration array including severity.
  */
 
 /**
  * Tests if the passed line configuration string or object is a pattern
  * definition.
- * @param {HeaderLine} object line configuration object or string
+ * @param {HeaderLine} object Line configuration object or string.
  * @returns {object is HeaderLinePattern} `true` if the line configuration is a
- *                                        pattern-defining object or `false`
- *                                        otherwise.
+ * pattern-defining object or `false` otherwise.
  */
 function isPattern(object) {
     return typeof object === "object"
@@ -102,10 +153,10 @@ 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 {string} actual the string to test.
+ * @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.
+ * config or `false` otherwise.
  */
 function match(actual, expected) {
     if (expected instanceof RegExp) {
@@ -117,11 +168,10 @@ function match(actual, expected) {
 
 /**
  * Remove Unix she-bangs from the list of comments.
- * @param {(Comment | { type: "Shebang" })[]} comments the list of comment
- *                                                     lines.
- * @returns {Comment[]} the list of comments with containing all incoming
- *                      comments from `comments` with the shebang comments
- *                      omitted.
+ * @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[]} */
@@ -132,9 +182,9 @@ function excludeShebangs(comments) {
 
 /**
  * TypeScript helper to confirm defined type.
- * @template T
- * @param {T | undefined} val  the value to validate.
- * @returns {asserts val is T} validates defined type
+ * @template T Target type to validate for definiteness.
+ * @param {T | undefined} val The value to validate.
+ * @returns {asserts val is T} Validates defined type.
  */
 function assertDefined(val) {
     assert.strict.notEqual(typeof val, "undefined");
@@ -142,9 +192,9 @@ function assertDefined(val) {
 
 /**
  * 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
+ * @template T Target type to validate is non-null.
+ * @param {T | null} val The value to validate.
+ * @returns {asserts val is T} Validates non-null type.
  */
 function assertNotNull(val) {
     assert.strict.notEqual(val, null);
@@ -156,7 +206,7 @@ function assertNotNull(val) {
  * check if they are at the start of the file since that is already checked by
  * `hasHeader()`.
  * @param {RuleContext} context ESLint execution environment.
- * @returns {Comment[]} lines that constitute the leading comment.
+ * @returns {Comment[]} Lines That constitute the leading comment.
  */
 function getLeadingComments(context) {
     const sourceCode = contextSourceCode(context);
@@ -183,10 +233,10 @@ function getLeadingComments(context) {
 /**
  * Generate a comment including trailing spaces out of a number of comment body
  * lines.
- * @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.
+ * @param {CommentType} commentType The type of comment to generate.
+ * @param {string[]} textArray List of lines of the comment content.
+ * @param {LineEnding} eol End-of-line characters.
+ * @returns {string} Resulting comment.
  */
 function genCommentBody(commentType, textArray, eol) {
     if (commentType === commentTypeOptions.block) {
@@ -201,8 +251,8 @@ function genCommentBody(commentType, textArray, eol) {
 /**
  * Determines the start and end position in the source code of the leading
  * comment.
- * @param {Comment[]} comments list of comments.
- * @returns {[number, number]} resulting range.
+ * @param {Comment[]} comments List of comments.
+ * @returns {[number, number]} Resulting range.
  */
 function genCommentsRange(comments) {
     assert.ok(comments.length);
@@ -222,8 +272,8 @@ function genCommentsRange(comments) {
 /**
  * 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.
+ * @param {string} src The source code to traverse.
+ * @returns {number} The number of leading empty lines.
  */
 function leadingEmptyLines(src) {
     let numLines = 0;
@@ -241,12 +291,12 @@ function leadingEmptyLines(src) {
 
 /**
  * Factory for fixer that adds a missing header.
- * @param {CommentType} 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
- * @param {number} numNewlines number of trailing lines after the comment.
- * @returns {ReportFixer} the fixer.
+ * @param {string[]} headerLines Lines of the header comment.
+ * @param {LineEnding} eol End-of-line characters.
+ * @param {number} numNewlines Number of trailing lines after the comment.
+ * @returns {ReportFixer} The fix to apply.
  */
 function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
     return function(fixer) {
@@ -272,13 +322,13 @@ function genPrependFixer(commentType, context, headerLines, eol, numNewlines) {
 
 /**
  * Factory for fixer that replaces an incorrect header.
- * @param {CommentType} 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: RuleFixer) => Fix | Fix[] | null} the fixer.
+ * @param {Comment[]} leadingComments Comment elements to replace.
+ * @param {string[]} headerLines Lines of the header comment.
+ * @param {LineEnding} eol End-of-line characters.
+ * @param {number} numNewlines Number of trailing lines after the comment.
+ * @returns {ReportFixer} The fix to apply.
  */
 function genReplaceFixer(commentType, context, leadingComments, headerLines, eol, numNewlines) {
     return function(fixer) {
@@ -295,11 +345,11 @@ function genReplaceFixer(commentType, context, leadingComments, headerLines, eol
 
 /**
  * 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: RuleFixer) => Fix | Fix[] | null} the fixer.
+ * @param {Comment[]} leadingComments Comment elements to replace.
+ * @param {LineEnding} eol End-of-line characters.
+ * @param {number} missingEmptyLinesCount Number of trailing lines after the
+ * comment.
+ * @returns {ReportFixer} The fix to apply.
  */
 function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
     return function(fixer) {
@@ -313,9 +363,8 @@ function genEmptyLinesFixer(leadingComments, eol, missingEmptyLinesCount) {
 /**
  * Returns the used line-termination characters per the rule's config if any or
  * else based on the runtime environments.
- * @param {LineEndingOption} style line-ending styles.
- * @returns {'\n' | '\r\n'} the correct line ending characters for the
- *                          environment.
+ * @param {LineEndingOption} style Line-ending styles.
+ * @returns {LineEnding} The correct line ending characters for the environment.
  */
 function getEol(style) {
     assert.strictEqual(Object.prototype.hasOwnProperty.call(lineEndingOptions, style), true,
@@ -327,14 +376,14 @@ function getEol(style) {
             return "\r\n";
         case lineEndingOptions.os:
         default:
-            return /** @type {'\n' | '\r\n'} */ (os.EOL);
+            return /** @type {LineEnding} */ (os.EOL);
     }
 }
 
 /**
  * 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.
+ * @param {string} src Source code to test.
  * @returns {boolean} `true` if there is a comment or `false` otherwise.
  */
 function hasHeader(src) {
@@ -343,10 +392,10 @@ function hasHeader(src) {
 }
 
 /**
- * asserts on an expression and adds template texts to the failure message.
+ * Asserts on an expression and adds template texts to the failure message.
  * Helper to write cleaner code.
- * @param {boolean} condition assert condition.
- * @param {string} message assert message on violation.
+ * @param {boolean} condition Condition to verify.
+ * @param {string} message Assert message on violation.
  */
 function schemaAssert(condition, message) {
     assert.strictEqual(condition, true, message + " - should have been handled by eslint schema validation.");
@@ -359,10 +408,10 @@ function schemaAssert(condition, message) {
  * options in that some settings are still union types and unspecified
  * properties are not replaced by defaults. If the options follow the new
  * format, a simple seep copy would be returned.
- * @param {AllHeaderOptions} originalOptions the options as configured by the
- *                                           user.
- * @returns {HeaderOptions} the transformed new-style options with no
- *                             normalization.
+ * @param {AllHeaderOptions} originalOptions The options as configured by the
+ * user.
+ * @returns {HeaderOptions} The transformed new-style options with no
+ * normalization.
  */
 function transformLegacyOptions(originalOptions) {
     schemaAssert(originalOptions?.length > 0,
@@ -428,17 +477,20 @@ function transformLegacyOptions(originalOptions) {
 }
 
 /**
- * @param {FileBasedConfig | InlineConfig} config the header configuration.
- * @returns {config is FileBasedConfig} true if `config` is `FileBasedConfig`.
+ * Type guard for `FileBasedConfig`.
+ * @param {FileBasedConfig | InlineConfig} config The header configuration.
+ * @returns {config is FileBasedConfig} `true` if `config` is `FileBasedConfig`,
+ * else `false`.
  */
 function isFileBasedHeaderConfig(config) {
     return Object.prototype.hasOwnProperty.call(config, "file");
 }
 
 /**
- * @param {FileBasedConfig | InlineConfig} config the header configuration.
- * @returns {asserts config is InlineConfig} asserts `config` is
- *                                               `LineBasedConfig`.
+ * Type guard for `InlineConfig`.
+ * @param {FileBasedConfig | InlineConfig} config The header configuration.
+ * @returns {asserts config is InlineConfig} Asserts `config` is
+ * `LineBasedConfig`.
  */
 function assertLineBasedHeaderConfig(config) {
     assert.ok(Object.prototype.hasOwnProperty.call(config, "lines"));
@@ -447,8 +499,8 @@ function assertLineBasedHeaderConfig(config) {
 /**
  * Transforms a set of new-style options adding defaults and standardizing on
  * one of multiple config styles.
- * @param {HeaderOptions} originalOptions new-style options to normalize.
- * @returns {HeaderOptions} normalized options.
+ * @param {HeaderOptions} originalOptions New-style options to normalize.
+ * @returns {HeaderOptions} Normalized options.
  */
 function normalizeOptions(originalOptions) {
     const options = structuredClone(originalOptions);
@@ -498,11 +550,11 @@ function normalizeOptions(originalOptions) {
  * 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.
+ * @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 missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
     assert.ok(leadingComments);
@@ -519,7 +571,7 @@ function missingEmptyLinesViolationLoc(leadingComments, actualEmptyLines) {
     };
 }
 
-/** @type {import('eslint').Rule.RuleModule} */
+/** @type {Rule.RuleModule} */
 const headerRule = {
     meta: {
         type: "layout",
@@ -551,10 +603,11 @@ const headerRule = {
             noNewlineAfterHeader: "not enough newlines after header: expected: {{expected}}, actual: {{actual}}"
         }
     },
+
     /**
      * Rule creation function.
      * @param {RuleContext} context ESLint rule execution context.
-     * @returns {NodeListener} the rule definition.
+     * @returns {NodeListener} The rule definition.
      */
     create: function(context) {
 
@@ -851,6 +904,30 @@ const headerRule = {
                 /** @type {null | SourceLocation} */
                 let errorMessageLoc = null;
                 for (let i = 0; i < headerLines.length; i++) {
+                    if (leadingLines.length - 1 < i) {
+                        assertDefined(lastLeadingCommentLoc);
+                        assertNotNull(lastLeadingCommentLoc);
+                        context.report({
+                            loc: {
+                                start: lastLeadingCommentLoc.end,
+                                end: lastLeadingCommentLoc.end
+                            },
+                            messageId: "headerTooShort",
+                            data: {
+                                remainder: headerLines.slice(i).join(eol)
+                            },
+                            fix: canFix
+                                ? genReplaceFixer(
+                                    commentType,
+                                    context,
+                                    leadingComments,
+                                    fixLines,
+                                    eol,
+                                    numLines)
+                                : null
+                        });
+                        return;
+                    }
                     const leadingLine = leadingLines[i];
                     const headerLine = headerLines[i];
                     if (typeof headerLine === "string") {

package/lib/rules/header.schema.js

@@ -1,8 +1,8 @@
-/*
- * MIT License
- *
- * Copyright (c) 2025-present Tony Ganchev and contributors
- *
+/**
+ * @file Schema definition for `header` rule.
+ * @copyright Copyright (c) 2015-present Stuart Knightley and contributors
+ * @copyright Copyright (c) 2025-2026 Tony Ganchev
+ * @license MIT
  * 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
@@ -22,6 +22,7 @@
  * SOFTWARE.
  */
 
+
 "use strict";
 
 /**
@@ -41,7 +42,7 @@ const commentTypeOptions = Object.freeze({
     line: "line"
 });
 
-/** @type {import('json-schema').JSONSchema4} */
+/** @type {import("json-schema").JSONSchema4} */
 const schema = Object.freeze({
     $ref: "#/definitions/options",
     definitions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "The native ESLint 9/10 header plugin. A zero-bloat, drop-in replacement for 'eslint-plugin-header' with first-class Flat Config & TypeScript support. Auto-fix Copyright, License, and banner comments in JavaScrip and TypeScript files.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -17,38 +17,28 @@
     "types",
     "CONTRIBUTING.md"
   ],
-  "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 && 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.3",
     "@eslint/js": "^10.0.1",
     "@eslint/markdown": "^7.5.1",
-    "@stylistic/eslint-plugin": "^5.8.0",
-    "@types/node": "^25.2.3",
-    "eslint": "^10.0.0",
-    "eslint-plugin-eslint-plugin": "^7.3.0",
-    "eslint-plugin-jsdoc": "^62.5.4",
-    "eslint-plugin-n": "^17.23.2",
+    "@stylistic/eslint-plugin": "^5.9.0",
+    "@types/estree": "^1.0.8",
+    "@types/json-schema": "^7.0.15",
+    "@types/node": "^25.3.0",
+    "c8": "^10.1.3",
+    "eslint": "^10.0.2",
+    "eslint-plugin-eslint-plugin": "^7.3.1",
+    "eslint-plugin-jsdoc": "^62.7.1",
+    "eslint-plugin-n": "^17.24.0",
+    "globals": "^17.3.0",
     "markdownlint-cli": "^0.47.0",
-    "mocha": "^12.0.0-beta-9",
-    "nyc": "^17.1.0",
+    "mocha": "12.0.0-beta-9",
     "testdouble": "^3.20.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0"
+    "typescript-eslint": "^8.56.1"
   },
   "peerDependencies": {
     "eslint": ">=7.7.0"
   },
-  "overrides": {
-    "eslint": "^10.0.0"
-  },
   "keywords": [
     "eslint",
     "eslint-plugin",
@@ -86,5 +76,14 @@
   "contributors": [
     "Josh Kelley",
     "Stuart Knightley"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc",
+    "e2e": "pnpm build && mocha --timeout 60000 tests/e2e/*.js",
+    "eslint": "eslint .",
+    "lint": "pnpm eslint && pnpm markdownlint",
+    "markdownlint": "markdownlint *.md",
+    "test": "pnpm lint && pnpm unit && pnpm e2e",
+    "unit": "c8 --reporter=html --reporter=text --reporter=text-summary --reporter=lcov --check-coverage --100 mocha tests/lib/*.js tests/lib/**/*.js"
+  }
+}

package/types/index.d.ts

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

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

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

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

@@ -1 +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,EAAE,CAAC,CAmBxC"}
+{"version":3,"file":"comment-parser.d.ts","sourceRoot":"","sources":["../../lib/comment-parser.js"],"names":[],"mappings":"AAuCiB,uCALN,MAAM,GACJ,CAAC,OAAO,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAoB5D"}

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

@@ -1,100 +1,135 @@
 export { headerRule as header };
+export type NodeListener = Rule.NodeListener;
+export type ReportFixer = Rule.ReportFixer;
+export type RuleFixer = Rule.RuleFixer;
+export type RuleContext = Rule.RuleContext;
 /**
- * Import type definitions.
+ * The sequence of characters that define
+ * the end of a line.
  */
-export type Fix = import("eslint").Rule.Fix;
+export type LineEnding = "\n" | "\r\n";
 /**
- * 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.
+ * Matching rule for a line from the header
+ * using regular expression and optionally providing an auto-fix replacement.
  */
 export type HeaderLinePattern = {
+    /**
+     * A regular expression that should match
+     * the header line.
+     */
     pattern: string | RegExp;
-    template?: string;
+    /**
+     * When set, if the actual header line does not
+     * match `pattern`, this value is to be used when running auto-fix.
+     */
+    template?: string | undefined;
 };
 /**
- * Local type definitions.
+ * Matching rule for
+ * a single line of the header comment or the header comment as a whole if only
+ * one used.
  */
 export type HeaderLine = string | RegExp | HeaderLinePattern;
 /**
- * Local type definitions.
+ * The set of header comment-
+ * matching rules.
  */
 export type HeaderLines = HeaderLine | HeaderLine[];
 /**
- * Local type definitions.
+ * Defines what EOL
+ * characters to expect - either forced to be Windows / POSIX-compatible, or
+ * defaulting to whatever the OS expects.
  */
 export type LineEndingOption = "os" | "unix" | "windows";
 /**
- * Local type definitions.
+ * How to treat
+ * line endings.
  */
 export type HeaderSettings = {
     lineEndings?: LineEndingOption;
 };
 /**
- * Local type definitions.
+ * The expected type of comment to use
+ * for the header.
  */
 export type CommentType = "block" | "line";
 /**
- * Local type definitions.
+ * Header content configuration defined in a
+ * separate JavaScript template file.
  */
 export type FileBasedConfig = {
+    /**
+     * Template file path relative to the directory
+     * from which ESLint runs.
+     */
     file: string;
-    encoding?: BufferEncoding;
+    /**
+     * Encoding to use when reading the
+     * file. If omitted, `"utf8"` will be assumed.
+     */
+    encoding?: BufferEncoding | undefined;
 };
 /**
- * Local type definitions.
+ * Header content configuration defined inline
+ * within the ESLint configuration.
  */
 export type InlineConfig = {
+    /**
+     * The type of comment to expect.
+     */
     commentType: CommentType;
+    /**
+     * Matching rules for lines. If only one rule
+     * is provided, the rule would attempt to match either the first line ar all
+     * lines together.
+     */
     lines: HeaderLine[];
 };
 /**
- * Local type definitions.
+ * Rule configuration on the handling of
+ * empty lines after the header comment.
  */
 export type TrailingEmptyLines = {
-    minimum?: number;
+    /**
+     * If set, the rule would check that at least
+     * a `minimum` number of EOL characters trail the header.
+     */
+    minimum?: number | undefined;
+};
+export type HeaderOptionsWithoutSettings = {
+    /**
+     * The text matching rules
+     * for the header.
+     */
+    header: FileBasedConfig | InlineConfig;
+    /**
+     * Rules about empty lines
+     * after the header comment.
+     */
+    trailingEmptyLines?: TrailingEmptyLines | undefined;
 };
 /**
- * Local type definitions.
+ * Modern
+ * object-based rule configuration.
  */
-export type HeaderOptions = {
-    header: FileBasedConfig | InlineConfig;
-    trailingEmptyLines?: TrailingEmptyLines;
-} & HeaderSettings;
+export type HeaderOptions = HeaderOptionsWithoutSettings & HeaderSettings;
+export type LegacyFileBasedConfig = [template: string];
+export type LegacyFileBasedSettingsConfig = [template: string, settings: HeaderSettings];
+export type LegacyInlineConfig = [type: CommentType, lines: HeaderLines];
+export type LegacyInlineSettingsConfig = [type: CommentType, lines: HeaderLines, settings: HeaderSettings];
+export type LegacyInlineMinLinesConfig = [type: CommentType, lines: HeaderLines, minLines: number];
+export type LegacyInlineMinLinesSettingsConfig = [type: CommentType, lines: HeaderLines, minLines: number, settings: HeaderSettings];
 /**
- * Local type definitions.
+ * Full possible rule configuration options.
  */
-export type AllHeaderOptions = [HeaderOptions] | [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];
+export type AllHeaderOptions = [HeaderOptions] | LegacyFileBasedConfig | LegacyFileBasedSettingsConfig | LegacyInlineConfig | LegacyInlineSettingsConfig | LegacyInlineMinLinesConfig | LegacyInlineMinLinesSettingsConfig;
 /**
- * Local type definitions.
+ * Rule
+ * configuration array including severity.
  */
-export type HeaderRuleConfig = import("eslint").Linter.RuleEntry<AllHeaderOptions>;
-/** @type {import('eslint').Rule.RuleModule} */
-declare const headerRule: import("eslint").Rule.RuleModule;
+export type HeaderRuleConfig = Linter.RuleEntry<AllHeaderOptions>;
+/** @type {Rule.RuleModule} */
+declare const headerRule: Rule.RuleModule;
+import type { Rule } from "eslint";
+import type { Linter } from "eslint";
 //# sourceMappingURL=header.d.ts.map

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

@@ -1 +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,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;yBAC/C,MAAM,GAAG,MAAM,GAAG,iBAAiB;;;;0BACnC,UAAU,GAAG,UAAU,EAAE;;;;+BACzB,IAAI,GAAG,MAAM,GAAG,SAAS;;;;6BACzB;IAAE,WAAW,CAAC,EAAE,gBAAgB,CAAA;CAAE;;;;0BAClC,OAAO,GAAG,MAAM;;;;8BAChB;IACL,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC5B;;;;2BAEQ;IACL,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,UAAU,EAAE,CAAA;CACtB;;;;iCAEQ;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE;;;;4BACpB;IACL,MAAM,EAAE,eAAe,GAAG,YAAY,CAAC;IACvC,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;CAC1C,GACC,cAAc;;;;+BAEP,CAAC,aAAa,CAAC,GAC3B,CAAI,QAAQ,EAAE,MAAM,CAAC,GACrB,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;AAqbhE,+CAA+C;AAC/C,0BADW,OAAO,QAAQ,EAAE,IAAI,CAAC,UAAU,CA8dzC"}
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.js"],"names":[],"mappings":";2BAqCa,iBAAiB;0BACjB,gBAAgB;wBAChB,cAAc;0BACd,gBAAgB;;;;;yBAIhB,IAAI,GAAG,MAAM;;;;;;;;;;aAOZ,MAAM,GAAG,MAAM;;;;;;;;;;;;yBAOhB,MAAM,GAAG,MAAM,GAAG,iBAAiB;;;;;0BAGnC,UAAU,GAAG,UAAU,EAAE;;;;;;+BAEzB,IAAI,GAAG,MAAM,GAAG,SAAS;;;;;6BAGzB;IAAE,WAAW,CAAC,EAAE,gBAAgB,CAAA;CAAE;;;;;0BAElC,OAAO,GAAG,MAAM;;;;;;;;;;UAOf,MAAM;;;;;;;;;;;;;;;iBASN,WAAW;;;;;;WACX,UAAU,EAAE;;;;;;;;;;;;;;;;;;YAcZ,eAAe,GAAG,YAAY;;;;;;;;;;;4BAO/B,4BAA4B,GAAG,cAAc;oCAK7C,CAAC,QAAQ,EAAE,MAAM,CAAC;4CAClB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC;iCAE5C,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC;yCACvC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC;yCAEjE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC;iDAEzD,CACV,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,CACvB;;;;+BACS,CAAC,aAAa,CAAC,GACvB,qBAAqB,GACrB,6BAA6B,GAC7B,kBAAkB,GAClB,0BAA0B,GAC1B,0BAA0B,GAC1B,kCAAkC;;;;;+BAK1B,iBAAiB,gBAAgB,CAAC;AAqb/C,8BAA8B;AAC9B,0BADW,eAAe,CAufxB;0BAjhC+B,QAAQ;4BAAR,QAAQ"}

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

@@ -15,6 +15,6 @@ export const commentTypeOptions: Readonly<{
     block: "block";
     line: "line";
 }>;
-/** @type {import('json-schema').JSONSchema4} */
+/** @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

@@ -1 +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,CAwKzC"}
+{"version":3,"file":"header.schema.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.schema.js"],"names":[],"mappings":"gCA4BU,MAAM;AADhB;;GAEG;AACH;;;;GAIG;iCAGO,MAAM;AADhB;;GAEG;AACH;;;GAGG;AAEH,gDAAgD;AAChD,qBADW,OAAO,aAAa,EAAE,WAAW,CAwKzC"}