@tony.ganchev/eslint-plugin-header 3.2.0 → 3.2.2

package/README.md

@@ -1,49 +1,67 @@
-# eslint-plugin-header
+# @tony.ganchev/eslint-plugin-header
 
-ESLint plugin / rule to ensure that files begin with a given comment - usually a
-copyright notice.
+[![npm version](https://img.shields.io/npm/v/@tony.ganchev/eslint-plugin-header.svg)](https://www.npmjs.com/package/@tony.ganchev/eslint-plugin-header)
+[![Downloads/month](https://img.shields.io/npm/dm/@tony.ganchev/eslint-plugin-header.svg)](http://www.npmtrends.com/@tony.ganchev/eslint-plugin-header)
+[![Build Status](https://github.com/tonyganchev/eslint-plugin-header/workflows/Test/badge.svg)](https://github.com/tonyganchev/eslint-plugin-header)
 
-Often you will want to have a copyright notice at the top of every file. This
-ESLint plugin checks that the first comment in every file has the contents
-defined in the rule settings.
+The native ESLint 9/10 standard header-validating plugin. A zero-bloat, drop-in
+replacement for [eslint-plugin-header](https://github.com/Stuk/eslint-plugin-header)
+with first-class Flat Config & TypeScript support. Auto-fix copyright, license,
+and banner comments in JavaScript and TypeScript files.
 
 ## Table of Contents
 
-1. [Scope and Acknowledgements](#scope-and-acknowledgements)
+1. [Motivation and Acknowledgements](#motivation-and-acknowledgements)
 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)
-4. [Examples](#examples)
+      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)
+4. [Comparison to Alternatives](#comparison-to-alternatives)
+   1. [Compared to eslint-plugin-headers](#compared-to-eslint-plugin-headers)
+      1. [Health Scans](#health-scans)
+   2. [Compared to eslint-plugin-license-header](#compared-to-eslint-plugin-license-header)
 5. [Versioning](#versioning)
    1. [What is a Feature?](#what-is-a-feature)
    2. [What is Backward-compatibility?](#what-is-backward-compatibility)
 6. [License](#license)
 
-## Scope and Acknowledgements
+## Motivation and Acknowledgements
 
-This is a fork of <https://github.com/Stuk/eslint-plugin-header>.
+The plugin started as a fork of [eslint-plugin-header](https://github.com/Stuk/eslint-plugin-header)
+to address missing ESLint 9 compatibility.
 
-It addresses the following issus:
+Today it addresses the following issues:
 
-- Adds bugfixes where the original project has not been updated in the last
-  three years.
-- Adds support for ESLint 9 with a fully-validated configuration schema.
-- Addresses a number of bugs on Windows and adds significant amount of tests to
-  verify there are no future regressions.
+- Support for ESLint 9/10 with a fully-validated configuration schema.
+- Continued support for ESLint 7/8.
+- Complete Windows support.
+- New object-based configuration providing the bases for future enhancements.
+- Continued support for _eslint-plugin-header_ array configuration.
+- Bugfixes where the original project has not been updated for the three
+  years before the fork.
 - Fixes issues with she-bangs and empty lines before the header. See PR history
   for more details.
-- Provides the foundation to evolve the plugin to add more capabilities moving
-  forward. This would come at the expense of plugin compatibility and the
-  portability of fixes to the upstream repository.
+- Good error reporting and improved auto-fixes.
+- Complete drop-in-replacement compatibility with existing projects using
+  _eslint-plugin-header_.
+
+Multiple other projects took from where _eslint-plugin-header_ left off. A
+comparison of the current project to these alternatives is available in a
+dedicated section.
 
 ## 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 plugin supports ESLint 7 / 8 / 9 / 10. 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
 
@@ -63,14 +81,27 @@ This _header_ rule takes a single object as configuration, after the severity
 level. At the very least, the object should contain a `header` field describing
 the expected header to match in the source files.
 
+For TypesScript-based flat ESLint configuration, two types are 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.
+- `HeaderOptions` helper type that defines the structure of the configuration
+  object used in the modern configuration style that is used in this document.
+  It can be used to either simplify auto-completion since this type is not mixed
+  with a large number of named tuple types, or it can be used when the config
+  object is defined outside of the definition of a specific rule.
+
 ### File-based Configuration
 
 In this configuration mode, the header template is read from a file.
 
-_eslint.config.mjs_:
+_eslint.config.ts_:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, {
+    HeaderOptions, HeaderRuleConfig
+} from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -86,8 +117,8 @@ export default defineConfig([
                     header: {
                         file: "config/header.js"
                     }
-                }
-            ]
+                } as HeaderOptions
+            ] as HeaderRuleConfig
         }
     }
 ]);
@@ -132,8 +163,8 @@ All of the following configurations will match the header:
 
 - **Single string**:
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -150,7 +181,7 @@ All of the following configurations will match the header:
                             commentType: "block",
                             lines: ["\n * Copyright (c) 2015\n * My Company\n "]
                         }
-                    },
+                    } as HeaderOptions
                 ]
             }
         }
@@ -173,8 +204,8 @@ All of the following configurations will match the header:
     You can match the whole header with a regular expression. To do it, simply
     pass a `RegExp` object in place of a string.
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -193,7 +224,7 @@ All of the following configurations will match the header:
                                 /\n \* Copyright \(c\) 2015\n \* Company\n /
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -203,8 +234,8 @@ All of the following configurations will match the header:
     If you still use hierarchical configuration, you can define the regular
     expression as a string.
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -224,7 +255,7 @@ All of the following configurations will match the header:
                                     + "\\n \\* My Company\\n "}
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -239,8 +270,8 @@ All of the following configurations will match the header:
     you want to add an aut-fix for the line as we will explain further in this
     document.
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -259,7 +290,7 @@ All of the following configurations will match the header:
                                 { pattern: /Copyright \(c\) 20\d{2}/ }
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -268,8 +299,8 @@ All of the following configurations will match the header:
 
 - **Array of strings**:
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -291,7 +322,7 @@ All of the following configurations will match the header:
                                 " "
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -300,8 +331,8 @@ All of the following configurations will match the header:
 
 - **Array of strings and/or patterns**:
 
-    ```js
-    import header from "@tony.ganchev/eslint-plugin-header";
+    ```ts
+    import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
     import { defineConfig } from "eslint/config";
 
     export default defineConfig([
@@ -323,7 +354,7 @@ All of the following configurations will match the header:
                                 " "
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -355,8 +386,8 @@ support:
 
 We can use a regular expression to support all of these cases for your header:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -378,7 +409,7 @@ export default defineConfig([
                             " "
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -391,8 +422,8 @@ to replace a header comment that did not pass validation. This is not possible
 with regular expressions. For regular expression pattern-objects, a second
 property `template` adds a replacement string.
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -415,7 +446,7 @@ export default defineConfig([
                             " My Company"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -430,6 +461,44 @@ There are a number of things to consider:
 - Templates are hardcoded strings therefore it may be better to hand-fix a bad
   header in order not to lose the from- and to-years in the copyright notice.
 
+#### Providing To-year in Auto-fix
+
+A common request across similar plugins is to provide for `{year}` variable to
+not change the ESLint configuration every year. While such special requests were
+relevant to old JSON-based configuration, this can be handled with JavaScript in
+the flat configuration format:
+
+```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: "line",
+                        lines: [
+                            {
+                                pattern: / Copyright \(c\) (\d{4}-)?\d{4}/,
+                                template: ` Copyright ${new Date().getFullYear()}`,
+                            },
+                            " My Company"
+                        ]
+                    }
+                } as HeaderOptions
+            ]
+        }
+    }
+]);
+```
+
 #### Trailing Empty Lines Configuration
 
 The third argument of the rule configuration which defaults to 1 specifies the
@@ -437,8 +506,8 @@ number of newlines that are enforced after the header.
 
 Zero newlines:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -461,7 +530,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 0
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -475,8 +544,8 @@ My Company */ console.log(1)
 
 One newline (default):
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -499,7 +568,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 1
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -514,8 +583,8 @@ console.log(1)
 
 Two newlines:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -538,7 +607,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 2
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -558,8 +627,8 @@ The rule works with both Unix/POSIX and Windows line endings. For ESLint
 `--fix`, the rule will use the line ending format of the current operating
 system (via Node's `os` package). This setting can be overwritten as follows:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -580,7 +649,7 @@ export default defineConfig([
                         ]
                     },
                     lineEndings: "windows"
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -590,12 +659,12 @@ 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.
 
-## Examples
+### Examples
 
 The following examples are all valid.
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -612,7 +681,7 @@ export default defineConfig([
                         commentType: "block",
                         lines: ["Copyright 2015, My Company"]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -624,8 +693,8 @@ export default defineConfig([
 console.log(1);
 ```
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -645,7 +714,7 @@ export default defineConfig([
                             "My Company"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -658,8 +727,8 @@ export default defineConfig([
 console.log(1)
 ```
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -679,7 +748,7 @@ export default defineConfig([
                             /^My Company$/
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -694,8 +763,8 @@ console.log(1)
 
 With more decoration:
 
-```js
-import header from "@tony.ganchev/eslint-plugin-header";
+```ts
+import header, { HeaderOptions } from "@tony.ganchev/eslint-plugin-header";
 import { defineConfig } from "eslint/config";
 
 export default defineConfig([
@@ -717,7 +786,7 @@ export default defineConfig([
                             " ************************"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -732,6 +801,70 @@ export default defineConfig([
  console.log(1);
 ```
 
+## Comparison to Alternatives
+
+A number of projects have been aiming to solve problems similar to
+_\@tony.ganchev/eslint-plugin-header_ - mainly with respect to providing ESLint
+9 support. The section below tries to outline why developers may choose either.
+The evaluation is based on the versions of each project as of the time of
+publishing the current version of _\@tony.ganchev/eslint-plugin-header_.
+
+Further iterations of this document would add migration information.
+
+### Compared to [eslint-plugin-headers](https://github.com/robmisasi/eslint-plugin-headers)
+
+_\@tony.ganchev/eslint-plugin-header_ is a drop-in replacement for
+_eslint-plugin-header_ and all plugins that already use the latter can migrate
+to the fork right away. At the same time, it provides improved user experience
+and windows support.
+
+eslint-plugin-headers is not a drop-in replacement. It offers additional
+features. Some of them, such as support for Vue templates do not have an
+analogue in the current version of _\@tony.ganchev/eslint-plugin-header_ while
+others such as `{year}` variable placeholders are redundant in the world of
+ESLint 9's flat, JavaScript-based configuration as [already pointed out in this
+document](#providing-to-year-in-auto-fix).
+
+The configuration format philosophy of the two plugin differs.
+_\@tony.ganchev/eslint-plugin-header_ supports both the legacy model inherited
+from _eslint-plugin-header_ and a new object-based configuration that is easy to
+adopt and offers both a lot of power to the user as to what the headers should
+look like, and keeps the configuration compact - just a few lines defining the
+content inside the comment. At the same time, the configuration is structured in
+a way that can evolve without breaking compatibility, which is critical for a
+tool that is not differentiating for the critical delivery of teams.
+
+_eslint-plugin-headers_ also offers an object-based format, but the content is
+flat and may need breaking changes to be kept concise as new features come
+about. Further, it makes assumption that then need to be corrected such as a
+block comment starting with `/**` instead of `/*` by default. The correction
+needs to happen not by adjusting the header template but through a separate
+confusing configuration properties.
+Overall, the configuration tends to be noisier nad harder to read than that of
+_\@tony.ganchev/eslint-plugin-header_.
+
+#### Health Scans
+
+- _\@tony.ganchev/eslint-plugin-header_</th> -
+  [snyk.io](https://security.snyk.io/package/npm/%40tony.ganchev%2Feslint-plugin-header),
+  [socket.dev](https://socket.dev/npm/package/@tony.ganchev/eslint-plugin-header/overview/3.2.2)
+
+- _eslint-plugin-headers_ -
+  [snyk.io](https://security.snyk.io/package/npm/eslint-plugin-headers),
+  [socket.dev](https://socket.dev/npm/package/eslint-plugin-headers/overview/1.3.4)
+
+At the time of the publishing of the current version of
+_\@tony.ganchev/eslint-plugin-header_, the latter has a slight edge in both
+scans against _eslint-plugin-headers_.
+
+### Compared to [eslint-plugin-license-header](https://github.com/nikku/eslint-plugin-license-header)
+
+_eslint-plugin-license-header_ per its limited documentation does not have a lot
+of features including not matching arbitrary from-years in the copyright notice.
+This on one hand leads to it having a nice, dead-simple configuration, but means
+no complex multi-year project would be happy with it. Surprisingly, given the
+limited feature set, the plugin has more peer dependencies than the competition.
+
 ## Versioning
 
 The project follows standard [NPM semantic versioning policy](

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

@@ -37,6 +37,7 @@ module.exports = {
      * @returns {SourceCode} the source-code object.
      */
     contextSourceCode: function(context) {
-        return context.sourceCode || context.getSourceCode();
+        return context.sourceCode
+            || /** @type {RuleContext & { getSourceCode: () => SourceCode }} */(context).getSourceCode();
     }
 };

package/lib/rules/header.docs.js

@@ -25,16 +25,5 @@
 
 "use strict";
 
-const assert = require("node:assert");
-const fs = require("node:fs");
-const path = require("node:path");
-
-const packageJsonContent = fs.readFileSync(path.resolve(__dirname, "../../package.json"));
-const packageJson = JSON.parse(packageJsonContent);
-assert.equal(Object.prototype.hasOwnProperty.call(packageJson, "version"), true,
-    "The plugin's package.json should be available two directories above the rule.");
-const pluginVersion = packageJsonContent.version;
-
-exports.description = "";
+exports.description = "The rule validates that the source file starts with a specific header comment pattern.";
 exports.recommended = true;
-exports.url = "https://www.npmjs.com/package/@tony.ganchev/eslint-plugin-header/v/" + pluginVersion;