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

package/README.md

@@ -1,49 +1,63 @@
-# 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`
@@ -447,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
@@ -607,7 +659,7 @@ 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.
 
@@ -749,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/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"), "utf8");
-const packageJson = JSON.parse(packageJsonContent);
-assert.equal(Object.prototype.hasOwnProperty.call(packageJson, "version"), true,
-    "The plugin's package.json should be available two directories above the rule.");
-const pluginVersion = packageJson.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;

package/lib/rules/header.js

@@ -29,7 +29,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const commentParser = require("../comment-parser");
 const { contextSourceCode } = require("./eslint-utils");
-const { description, recommended, url } = require("./header.docs");
+const { description, recommended } = require("./header.docs");
 const { lineEndingOptions, commentTypeOptions, schema } = require("./header.schema");
 
 /**
@@ -525,8 +525,7 @@ const headerRule = {
         type: "layout",
         docs: {
             description,
-            recommended,
-            url
+            recommended
         },
         fixable: "whitespace",
         schema,
@@ -803,7 +802,7 @@ const headerRule = {
                                         },
                                         messageId: "incorrectHeaderLine",
                                         data: {
-                                            pattern: headerLine
+                                            pattern: headerLine.toString()
                                         },
                                         fix: canFix
                                             ? genReplaceFixer(
@@ -847,7 +846,7 @@ const headerRule = {
 
                 /** @type {null | string} */
                 let errorMessageId = null;
-                /** @type {undefined | Record<string, string | RegExp>} */
+                /** @type {undefined | Record<string, string>} */
                 let errorMessageData;
                 /** @type {null | SourceLocation} */
                 let errorMessageLoc = null;
@@ -921,7 +920,7 @@ const headerRule = {
                         if (!match(leadingLine, headerLine)) {
                             errorMessageId = "incorrectHeaderLine";
                             errorMessageData = {
-                                pattern: headerLine
+                                pattern: headerLine.toString()
                             };
                             const columnOffset = i === 0 ? "/*".length : 0;
                             assertDefined(firstLeadingCommentLoc);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.2.1",
-  "description": "ESLint plugin to ensure files begin with a given comment, usually a copyright or license notice.",
+  "version": "3.2.2",
+  "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",
   "exports": {
@@ -14,8 +14,7 @@
   "files": [
     "lib/**/*.js",
     "index.d.ts*",
-    "types",
-    "!lib/rules/test-utils.js"
+    "types"
   ],
   "scripts": {
     "build": "npx tsc",
@@ -28,35 +27,63 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
     "@eslint/markdown": "^7.5.1",
-    "@stylistic/eslint-plugin": "^5.7.1",
-    "@types/node": "^25.2.1",
-    "eslint": "^9.39.2",
+    "@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.2",
+    "eslint-plugin-jsdoc": "^62.5.4",
     "eslint-plugin-n": "^17.23.2",
     "markdownlint-cli": "^0.47.0",
-    "mocha": "^12.0.0-beta-6",
+    "mocha": "^12.0.0-beta-9",
     "nyc": "^17.1.0",
     "testdouble": "^3.20.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0"
+    "typescript-eslint": "^8.56.0"
   },
   "peerDependencies": {
     "eslint": ">=7.7.0"
   },
+  "overrides": {
+    "eslint": "^10.0.0"
+  },
   "keywords": [
     "eslint",
-    "eslintplugin"
+    "eslint-plugin",
+    "eslint9",
+    "flat-config",
+    "header",
+    "copyright",
+    "license",
+    "banner",
+    "notice",
+    "license-header",
+    "copyright-header",
+    "legal",
+    "gdpr",
+    "source-header",
+    "typescript",
+    "react",
+    "check",
+    "fix"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tonyganchev/eslint-plugin-header.git"
+    "url": "https://github.com/tonyganchev/eslint-plugin-header.git"
+  },
+  "homepage": "https://github.com/tonyganchev/eslint-plugin-header#readme",
+  "bugs": {
+    "url": "https://github.com/tonyganchev/eslint-plugin-header/issues"
   },
-  "author": "Stuart Knightley",
   "license": "MIT",
+  "author": "Tony Ganchev",
   "maintainers": [
+    "Gyokan Syuleymanov",
     "Tony Ganchev"
+  ],
+  "contributors": [
+    "Josh Kelley",
+    "Stuart Knightley"
   ]
 }

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

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

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,CA+dzC"}
+{"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"}

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

@@ -1,4 +1,3 @@
-export const description: "";
+export const description: "The rule validates that the source file starts with a specific header comment pattern.";
 export const recommended: true;
-export const url: string;
 //# sourceMappingURL=header.docs.d.ts.map

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

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

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

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