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

package/README.md

@@ -20,7 +20,9 @@ and banner comments in JavaScript and TypeScript files.
       2. [Providing To-year in Auto-fix](#providing-to-year-in-auto-fix)
       3. [Trailing Empty Lines Configuration](#trailing-empty-lines-configuration)
       4. [Line Endings](#line-endings)
-   3. [Examples](#examples)
+   3. [Support for Leading Comments](#support-for-leading-comments)
+      1. [Notes on Behavior](#notes-on-behavior)
+   4. [Examples](#examples)
 4. [Comparison to Alternatives](#comparison-to-alternatives)
    1. [Compared to eslint-plugin-headers](#compared-to-eslint-plugin-headers)
       1. [Health Scans](#health-scans)
@@ -659,6 +661,293 @@ export default defineConfig([
 Possible values are `"unix"` for `\n` and `"windows"` for `\r\n` line endings.
 The default value is `"os"` which means assume the system-specific line endings.
 
+### Support for Leading Comments
+
+_NOTE: This feature is still experimental and as such may break between minor
+versions and revisions._
+
+_NOTE: This feature will **only** be available with the modern object-based
+configuration._
+
+Some frameworks such as [Jest](https://jestjs.io/) change behavior based on
+pragma comments such as:
+
+```js
+/** @jest-environement node */
+```
+
+The problem with these is that they are not part of the header comment and
+should be allowed to appear before the header comment. The `leadingComments`
+option allows you to specify a set of comments that are allowed to appear before
+the header comment. It is configured as an array of comments-matching rules
+similar to the `header` section. For example to match the following header with
+a leading pragma:
+
+```js
+/** @jest-environement node */
+/* Copyright 2015, My Company */
+```
+
+... we can use the following configuration:
+
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    {
+        files: ["**/*.js"],
+        plugins: {
+            "@tony.ganchev": header
+        },
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2015, My Company "]
+                    },
+                    leadingComments: {
+                        comments: [
+                            {
+                                commentType: "block",
+                                lines: ["* @jest-environement node "]
+                            }
+                        ]
+                    }
+                } as HeaderOptions
+            ]
+        }
+    }
+]);
+```
+
+Assuming you need to tolerate more pragmas, you can have a longer list of
+comments e.g.
+
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    {
+        files: ["**/*.js"],
+        plugins: {
+            "@tony.ganchev": header
+        },
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2015, My Company "]
+                    },
+                    leadingComments: {
+                        comments: [
+                            {
+                                commentType: "block",
+                                lines: ["* @jest-environement node "]
+                            },
+                            {
+                                commentType: "line",
+                                lines: [" @ts-ignore"]
+                            }
+                        ]
+                    }
+                } as HeaderOptions
+            ]
+        }
+    }
+]);
+```
+
+You can also use file-based configuration for any of these allowed comments.
+
+#### Notes on Behavior
+
+There are a number of things to consider when validating headers when allowing
+some leading comments. It is important to understand the algorithm behind.
+During validation, the rule breaks up all comments before the first actual code
+token based either on the beginning and end of a block comments or based on the
+separation of line comments by more than one line. These discrete comment blocks
+are then validated against both the header-matching rule and all the leading
+comment-matching rules.
+
+For each comment, header is tested first and if it matches, validation completes
+successfully. If not, the algorithm verifies that the comment satisfies at least
+one comment matcher and if so, validation moves to the next comment.
+
+If the comment matches neither the header, nor any of the leading comment
+matchers, validation fails. To provide good troubleshooting information, errors
+are reported for the header matcher, followed by all leading comment matchers.
+While the information may seem overwhelming, this helps developers understand
+all possible failures and let them pick the essential one.
+
+Let's have the following configuration example:
+
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    {
+        files: ["**/*.js"],
+        plugins: {
+            "@tony.ganchev": header
+        },
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2015, My Company "]
+                    },
+                    leadingComments: {
+                        comments: [
+                            {
+                                commentType: "block",
+                                lines: ["* @jest-environement node "]
+                            },
+                            {
+                                commentType: "line",
+                                lines: [" @ts-ignore"]
+                            }
+                        ]
+                    }
+                } as HeaderOptions
+            ]
+        }
+    }
+]);
+```
+
+Let's lint the following piece of code:
+
+```js
+/** @jest-environement node */
+/* Copyright 2010, My Company */
+
+console.log(1);
+```
+
+The following errors would be shown:
+
+```bash
+  2:1  error  leading comment validation failed: should be a line comment
+        @tony.ganchev/header         
+  2:3  error  header line does not match expected after this position;
+    expected: 'Copyright 2015, My Company'
+        @tony.ganchev/header         
+  2:3  error  leading comment validation failed: line does not match expected
+    after this position; expected: '* @jest-environement node '
+        @tony.ganchev/header
+```
+
+Notice how all errors are reported on the second line. That is because the first
+line passes validation against the first leading comment matcher, while the
+second fails validation against all matchers.
+
+Requiring an empty line between line leading comments is important as it keeps
+the rule simple and fast but needs to be kept into account. Let's take the
+following configuration for example:
+
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    {
+        files: ["**/*.js"],
+        plugins: {
+            "@tony.ganchev": header
+        },
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2015, My Company "]
+                    },
+                    leadingComments: {
+                        comments: [
+                            {
+                                commentType: "line",
+                                lines: [" foo"]
+                            },
+                            {
+                                commentType: "line",
+                                lines: [" bar"]
+                            }
+                        ]
+                    }
+                } as HeaderOptions
+            ]
+        }
+    }
+]);
+```
+
+This configuration would successfully lint any of the following snippets:
+
+```js
+// foo
+
+// bar
+/* Copyright 2015, My Company */
+console.log();
+```
+
+```js
+// bar
+
+// foo
+
+/* Copyright 2015, My Company */
+console.log();
+```
+
+```js
+// bar
+
+// bar
+/* Copyright 2015, My Company */
+console.log();
+```
+
+It will not pass the following snippets though:
+
+```js
+// foo
+// bar
+
+/* Copyright 2015, My Company */
+console.log();
+```
+
+```js
+// bar
+// foo
+/* Copyright 2015, My Company */
+console.log();
+```
+
+```js
+// bar
+// bar
+
+/* Copyright 2015, My Company */
+console.log();
+```
+
+Finally, it is worth noting that the current version accepts an arbitrary number
+of empty lines in between comments. The only expectation still in place is that
+there is no empty line after a shebang comment. Any of these details may change
+through configuration in the future.
+
 ### Examples
 
 The following examples are all valid.
@@ -937,4 +1226,4 @@ Backward-compatibility does not cover the following functional aspects:
 
 ## License
 
-MIT
+MIT, see [license file](./LICENSE.md) for more details.

package/lib/rules/header.js

@@ -89,6 +89,14 @@ const { lineEndingOptions, commentTypeOptions, schema } = require("./header.sche
  * lines together.
  */
 
+/**
+ * @typedef {object} LeadingComments A set of comments that can appear before
+ * the header.
+ * @property {(FileBasedConfig | InlineConfig)[]} comments The set of comments
+ * that are allowed. If none of the matching rules matches the first comment the
+ * rule assumes the first comment *is* the header.
+ */
+
 /**
  * @typedef {object} TrailingEmptyLines Rule configuration on the handling of
  * empty lines after the header comment.
@@ -100,6 +108,9 @@ const { lineEndingOptions, commentTypeOptions, schema } = require("./header.sche
  * @typedef {object} HeaderOptionsWithoutSettings
  * @property {FileBasedConfig | InlineConfig} header The text matching rules
  * for the header.
+ * @property {LeadingComments} [leadingComments] The set of allowed comments to
+ * precede the header. Useful to allow position-sensitive pragma comments for
+ * certain tools.
  * @property {TrailingEmptyLines} [trailingEmptyLines] Rules about empty lines
  * after the header comment.
  */
@@ -168,42 +179,66 @@ function match(actual, expected) {
 }
 
 /**
- * Remove Unix she-bangs from the list of comments.
- * @param {(Comment | { type: "Shebang" })[]} comments The list of comment
- * lines.
- * @returns {Comment[]} The list of comments with containing all incoming
- * comments from `comments` with the shebang comments omitted.
- */
-function excludeShebangs(comments) {
-    /** @type {Comment[]} */
-    return comments.filter(function (comment) {
-        return comment.type !== "Shebang";
-    });
-}
-
-/**
- * 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()`.
+ * Returns an array of comment groups before the actual code.
+ * Block comments form single-element groups.
+ * Line comments without empty lines between them form grouped elements.
  * @param {SourceCode} sourceCode AST.
- * @returns {Comment[]} Lines That constitute the leading comment.
+ * @returns {Comment[][]} Array of groups of leading comments.
  */
 function getLeadingComments(sourceCode) {
-    const all = excludeShebangs(sourceCode.getAllComments());
-    if (all[0].type.toLowerCase() === commentTypeOptions.block) {
-        return [all[0]];
+    const all = sourceCode.getAllComments();
+    if (all.length === 0) {
+        return [];
     }
-    let i = 1;
-    for (; i < all.length; ++i) {
-        const previousRange = /** @type {[number, number]} */ (all[i - 1].range);
-        const currentRange = /** @type {[number, number]} */ (all[i].range);
-        const txt = sourceCode.text.slice(previousRange[1], currentRange[0]);
-        if (!txt.match(/^(\r\n|\r|\n)$/)) {
-            break;
+    // Determine where the actual code starts. If no code, use end of file.
+    const firstToken = sourceCode.getFirstToken(sourceCode.ast);
+    const codeStart = firstToken ? firstToken.range[0] : sourceCode.text.length;
+    // Filter comments that appear before the actual code starts.
+    const commentsBeforeCode = all.filter((c) => /** @type {[number, number]} */(c.range)[1] <= codeStart);
+    if (commentsBeforeCode.length === 0) {
+        return [];
+    }
+    /** @type {Comment[][]} */
+    const groups = [];
+    /** @type {Comment[]} */
+    let currentGroup = [];
+    for (let i = 0; i < commentsBeforeCode.length; ++i) {
+        const comment = commentsBeforeCode[i];
+
+        if (comment.type === "Block") {
+            // Push any existing current group first
+            if (currentGroup.length > 0) {
+                groups.push(currentGroup);
+                currentGroup = [];
+            }
+            groups.push([comment]);
+        } else {
+            if (currentGroup.length === 0) {
+                currentGroup.push(comment);
+            } else {
+                const previous = currentGroup[currentGroup.length - 1];
+                const previousRange = /** @type {[number, number]} */ (previous.range);
+                const currentRange = /** @type {[number, number]} */ (comment.range);
+                const txt = sourceCode.text.slice(previousRange[1], currentRange[0]);
+
+                // If there is more than 1 newline, there is an empty line
+                // between comments.
+                const newlineCount = /** @type {RegExpMatchArray} */ (txt.match(/\r?\n/g)).length;
+                if (newlineCount <= 1) {
+                    currentGroup.push(comment);
+                } else {
+                    groups.push(currentGroup);
+                    currentGroup = [comment];
+                }
+            }
         }
     }
-    return all.slice(0, i);
+
+    if (currentGroup.length > 0) {
+        groups.push(currentGroup);
+    }
+
+    return groups;
 }
 
 /**
@@ -351,17 +386,6 @@ function getEol(style) {
     }
 }
 
-/**
- * Tests if the first line in the source code (after a Unix she-bang) is a
- * comment. Does not tolerate empty lines before the first match.
- * @param {string} src Source code to test.
- * @returns {boolean} `true` if there is a comment or `false` otherwise.
- */
-function hasHeader(src) {
-    const srcWithoutShebang = src.replace(/^#![^\n]*\r?\n/, "");
-    return srcWithoutShebang.startsWith("/*") || srcWithoutShebang.startsWith("//");
-}
-
 /**
  * Asserts on an expression and adds template texts to the failure message.
  * Helper to write cleaner code.
@@ -433,14 +457,14 @@ function transformLegacyOptions(originalOptions) {
             transformedOptions.trailingEmptyLines = { minimum: originalOptions[2] };
             if (originalOptions.length === 4) {
                 schemaAssert(typeof originalOptions[3] === "object",
-                    "Fourth header option after severity should be either number of required trailing empty lines or " +
-                    "a settings object");
+                    "Fourth header option after severity should be either number of required trailing empty lines or "
+                    + "a settings object");
                 Object.assign(transformedOptions, originalOptions[3]);
             }
         } else {
             schemaAssert(typeof originalOptions[2] === "object",
-                "Third header option after severity should be either number of required trailing empty lines or a " +
-                "settings object");
+                "Third header option after severity should be either number of required trailing empty lines or a "
+                + "settings object");
             Object.assign(transformedOptions, originalOptions[2]);
         }
     }
@@ -454,7 +478,7 @@ function transformLegacyOptions(originalOptions) {
  * else `false`.
  */
 function isFileBasedHeaderConfig(config) {
-    return Object.prototype.hasOwnProperty.call(config, "file");
+    return "file" in config;
 }
 
 /**
@@ -506,6 +530,13 @@ function normalizeOptions(originalOptions) {
         options.lineEndings = "os";
     }
 
+    if (originalOptions.leadingComments) {
+        options.leadingComments = {
+            comments: originalOptions.leadingComments.comments.map((c) => normalizeMatchingRules(c))
+        };
+    } else {
+        options.leadingComments = { comments: [] };
+    }
     if (!options.trailingEmptyLines) {
         options.trailingEmptyLines = {};
     }
@@ -561,13 +592,18 @@ class CommentMatcher {
         this.numLines = numLines;
     }
 
+    /**
+     * @typedef {ViolationReport<JSSyntaxElement, string>} ViolationReportBad
+     * @typedef {ViolationReportBad & { messageId: string }} ViolationReportEx
+     */
+
     /**
      * Performs a validation of a comment against a header matching
      * configuration.
      * @param {Comment[]} leadingComments The block comment or sequence of line
      * comments to test.
      * @param {SourceCode} sourceCode The source code AST.
-     * @returns {ViolationReport<JSSyntaxElement, string> | null} If set a
+     * @returns {ViolationReportEx | null} If set a
      * violation report to pass back to ESLint or interpret as necessary.
      */
     validate(leadingComments, sourceCode) {
@@ -602,6 +638,9 @@ class CommentMatcher {
                             end: lastLeadingCommentLoc.end
                         },
                         messageId: "incorrectHeader",
+                        data: {
+                            pattern: this.headerLines[0].toString()
+                        }
                     };
                 }
             } else {
@@ -869,14 +908,33 @@ const headerRule = {
             }
         ],
         messages: {
-            headerLineMismatchAtPos: "header line does not match expected after this position; expected: {{expected}}",
+            // messages customized for header validation.
+            headerLineMismatchAtPos:
+                "header line does not match expected after this position; expected: '{{expected}}'",
             headerLineTooLong: "header line longer than expected",
-            headerLineTooShort: "header line shorter than expected; missing: {{remainder}}",
-            headerTooShort: "header too short: missing lines: {{remainder}}",
+            headerLineTooShort: "header line shorter than expected; missing: '{{remainder}}'",
+            headerTooShort: "header too short; missing lines: '{{remainder}}'",
             headerTooLong: "header too long",
             incorrectCommentType: "header should be a {{commentType}} comment",
-            incorrectHeader: "incorrect header",
-            incorrectHeaderLine: "header line does not match pattern: {{pattern}}",
+            incorrectHeader: "header does not match pattern: '{{pattern}}'",
+            incorrectHeaderLine: "header line does not match pattern: '{{pattern}}'",
+            // messages customized for leading comments validation.
+            "leadingComment-headerLineMismatchAtPos":
+                "leading comment validation failed: line does not match expected after this position; "
+                + "expected: '{{expected}}'",
+            "leadingComment-headerLineTooLong": "leading comment validation failed: line longer than expected",
+            "leadingComment-headerLineTooShort":
+                "leading comment validation failed: line shorter than expected; missing: '{{remainder}}'",
+            "leadingComment-headerTooShort":
+                "leading comment validation failed: comment too short; missing lines: '{{remainder}}'",
+            "leadingComment-headerTooLong": "leading comment validation failed: comment too long",
+            "leadingComment-incorrectCommentType":
+                "leading comment validation failed: should be a {{commentType}} comment",
+            "leadingComment-incorrectHeader":
+                "leading comment validation failed: comment does not match pattern: '{{pattern}}'",
+            "leadingComment-incorrectHeaderLine":
+                "leading comment validation failed: comment line does not match pattern: '{{pattern}}'",
+            // messages only applicable to header validation.
             missingHeader: "missing header",
             noNewlineAfterHeader: "not enough newlines after header: expected: {{expected}}, actual: {{actual}}"
         }
@@ -891,25 +949,20 @@ const headerRule = {
 
         const newStyleOptions = transformLegacyOptions(/** @type {AllHeaderOptions} */(context.options));
         const options = normalizeOptions(newStyleOptions);
-
-        const eol = getEol(
-            /** @type {LineEndingOption} */(options.lineEndings)
-        );
-
+        const eol = getEol(/** @type {LineEndingOption} */(options.lineEndings));
         const header = /** @type {InlineConfig} */ (options.header);
-
         const canFix = !header.lines.some((line) => isPattern(line) && !("template" in line));
-
         const fixLines = header.lines.map((line) => {
             if (isPattern(line)) {
                 return ("template" in line) ? /** @type {string} */(line.template) : "";
             }
             return /** @type {string} */(line);
         });
-
         const numLines = /** @type {number} */ (options.trailingEmptyLines?.minimum);
-
         const headerMatcher = new CommentMatcher(header, eol, numLines);
+        const allowedLeadingComments = /** @type {LeadingComments} */ (options.leadingComments).comments;
+        const allowedCommentsMatchers =
+            allowedLeadingComments.map((c) => new CommentMatcher(/** @type {InlineConfig} */(c), eol, 0));
 
         return {
             /**
@@ -919,18 +972,27 @@ const headerRule = {
              */
             Program: function () {
                 const sourceCode = contextSourceCode(context);
-                if (!hasHeader(sourceCode.text)) {
-                    const hasShebang = sourceCode.text.startsWith("#!");
-                    const line = hasShebang ? 2 : 1;
+                const leadingComments = getLeadingComments(sourceCode);
+                const hasShebang = leadingComments.length > 0
+                    && /** @type {string} */ (leadingComments[0][0].type) === "Shebang";
+                let startingHeaderLine = 1;
+                if (hasShebang) {
+                    leadingComments.splice(0, 1);
+                    startingHeaderLine = 2;
+                }
+
+                if (leadingComments.length === 0
+                    || /** @type {SourceLocation} */ (leadingComments[0][0].loc).start.line > startingHeaderLine) {
+
                     context.report({
                         loc: {
                             start: {
-                                column: 1,
-                                line
+                                column: 0,
+                                line: startingHeaderLine
                             },
                             end: {
-                                column: 1,
-                                line
+                                column: 0,
+                                line: startingHeaderLine
                             }
                         },
                         messageId: "missingHeader",
@@ -945,26 +1007,69 @@ const headerRule = {
                     });
                     return;
                 }
-                const leadingComments = getLeadingComments(sourceCode);
 
-                const report = headerMatcher.validate(leadingComments, sourceCode);
+                for (const leadingComment of leadingComments) {
+
+                    const headerReport = headerMatcher.validate(leadingComment, sourceCode);
+                    if (headerReport === null) {
+                        return;
+                    }
+                    const leadingCommentReports =
+                        allowedCommentsMatchers.map((m) => m.validate(leadingComment, sourceCode));
+                    const commentMatched = leadingCommentReports.some((report) => report === null);
+
+                    if (!commentMatched) {
+                        if ("messageId" in headerReport && headerReport.messageId === "noNewlineAfterHeader") {
+                            const { expected, actual } =
+                                /** @type {{ expected: number, actual: number }} */ (headerReport.data);
+                            headerReport.fix = genEmptyLinesFixer(leadingComment, eol, expected - actual);
+                        } else if (canFix) {
+                            headerReport.fix = genReplaceFixer(
+                                headerMatcher.commentType,
+                                sourceCode,
+                                leadingComment,
+                                fixLines,
+                                eol,
+                                numLines);
+                        }
+
+                        context.report(headerReport);
+                        for (const commentReport of leadingCommentReports) {
+                            if (commentReport !== null) {
+                                /** @type {{ messageId: string }} */ (commentReport).messageId =
+                                    "leadingComment-" + /** @type {{ messageId: string }} */ (commentReport).messageId;
+                                context.report(commentReport);
+                            }
+                        }
+                        return;
+                    }
+                }
+
+                const lastComment = leadingComments[leadingComments.length - 1];
+                const lastCommentLine = lastComment[lastComment.length - 1];
+                const lineIndex = /** @type {number} */ (lastCommentLine.loc?.end.line) + 1;
 
-                if (report !== null) {
-                    if ("messageId" in report && report.messageId === "noNewlineAfterHeader") {
-                        const { expected, actual } =
-                            /** @type {{ expected: number, actual: number }} */ (report.data);
-                        report.fix = genEmptyLinesFixer(leadingComments, eol, expected - actual);
-                    } else if (canFix) {
-                        report.fix = genReplaceFixer(
+                context.report({
+                    loc: {
+                        start: {
+                            column: 0,
+                            line: lineIndex
+                        },
+                        end: {
+                            column: 0,
+                            line: lineIndex
+                        }
+                    },
+                    messageId: "missingHeader",
+                    fix: canFix
+                        ? genPrependFixer(
                             headerMatcher.commentType,
                             sourceCode,
-                            leadingComments,
                             fixLines,
                             eol,
-                            numLines);
-                    }
-                    context.report(report);
-                }
+                            numLines)
+                        : null
+                });
             }
         };
     }

package/lib/rules/header.schema.js

@@ -142,6 +142,28 @@ const schema = Object.freeze({
             required: ["commentType", "lines"],
             additionalProperties: false
         },
+        header: {
+            anyOf: [
+                { $ref: "#/definitions/fileBasedHeader" },
+                { $ref: "#/definitions/inlineHeader" }
+            ],
+            description: "Header comment matching rules."
+        },
+        leadingComments: {
+            type: "object",
+            properties: {
+                comments: {
+                    type: "array",
+                    items: { $ref: "#/definitions/header" },
+                    description: "The set of comment matching rules. The rule can match one or more comments against " +
+                        "these rules."
+                }
+            },
+            required: ["comments"],
+            additionalProperties: false,
+            description: "Set of comments that can appear before the header comment. Useful for pragmas used by some " +
+                "tools that expect these to be the first comment in the file."
+        },
         trailingEmptyLines: {
             type: "object",
             properties: {
@@ -156,12 +178,8 @@ const schema = Object.freeze({
         newOptions: {
             type: "object",
             properties: {
-                header: {
-                    anyOf: [
-                        { $ref: "#/definitions/fileBasedHeader" },
-                        { $ref: "#/definitions/inlineHeader" }
-                    ]
-                },
+                header: { $ref: "#/definitions/header" },
+                leadingComments: { $ref: "#/definitions/leadingComments" },
                 lineEndings: { $ref: "#/definitions/lineEndings" },
                 trailingEmptyLines: { $ref: "#/definitions/trailingEmptyLines" }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.2.6",
+  "version": "3.3.0",
   "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",

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

@@ -85,6 +85,18 @@ export type InlineConfig = {
      */
     lines: HeaderLine[];
 };
+/**
+ * A set of comments that can appear before
+ * the header.
+ */
+export type LeadingComments = {
+    /**
+     * The set of comments
+     * that are allowed. If none of the matching rules matches the first comment the
+     * rule assumes the first comment *is* the header.
+     */
+    comments: (FileBasedConfig | InlineConfig)[];
+};
 /**
  * Rule configuration on the handling of
  * empty lines after the header comment.
@@ -102,6 +114,12 @@ export type HeaderOptionsWithoutSettings = {
      * for the header.
      */
     header: FileBasedConfig | InlineConfig;
+    /**
+     * The set of allowed comments to
+     * precede the header. Useful to allow position-sensitive pragma comments for
+     * certain tools.
+     */
+    leadingComments?: LeadingComments | undefined;
     /**
      * Rules about empty lines
      * after the header comment.

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

@@ -1 +1 @@
-{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.js"],"names":[],"mappings":";2BAsCa,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;AA0sB/C,8BAA8B;AAC9B,0BADW,eAAe,CAuHxB;0BAv6B4D,QAAQ;4BAAR,QAAQ"}
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../lib/rules/header.js"],"names":[],"mappings":";2BAsCa,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;;;;;;;;;;;;cAQZ,CAAC,eAAe,GAAG,YAAY,CAAC,EAAE;;;;;;;;;;;;;;;;;;YAclC,eAAe,GAAG,YAAY;;;;;;;;;;;;;;;;;4BAU/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;AAsuB/C,8BAA8B;AAC9B,0BADW,eAAe,CAyLxB;0BAhhC4D,QAAQ;4BAAR,QAAQ"}

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":"gCA4BU,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,CA0LzC"}