@tony.ganchev/eslint-plugin-header 3.1.8 → 3.1.10

package/LICENSE.md

@@ -1,3 +1,5 @@
+# MIT License
+
 Copyright (c) 2015-present Stuart Knightley, Tony Ganchev and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
@@ -15,4 +17,4 @@ 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.
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,4 +1,30 @@
-This is a fork of https://github.com/Stuk/eslint-plugin-header.
+# eslint-plugin-header
+
+ESLint plugin / rule to ensure that files begin with a given comment - usually a
+copyright notice.
+
+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.
+
+## Table of Contents
+
+1. [Scope and Acknowledgements](#scope-and-acknowledgements)
+2. [Usage](#usage)
+   1. [File-based Configuration](#file-based-configuration)
+   2. [Inline Configuration](#inline-configuration)
+      1. [Header Contents Configuration](#header-contents-configuration)
+      2. [Trailing Empty Lines Configuration](#trailing-empty-lines-configuration)
+      3. [Line Endings](#line-endings)
+3. [Examples](#examples)
+4. [Versioning](#versioning)
+   1. [What is a Feature?](#what-is-a-feature)
+   2. [What is Backward-compatibility?](#what-is-backward-compatibility)
+5. [License](#license)
+
+## Scope and Acknowledgements
+
+This is a fork of <https://github.com/Stuk/eslint-plugin-header>.
 
 It addresses the following issus:
 
@@ -13,36 +39,27 @@ It addresses the following issus:
   forward. This would come at the expense of plugin compatibility and the
   portability of fixes to the upstream repository.
 
-eslint-plugin-header
-====================
-
-ESLint plugin to ensure that files begin with given comment.
-
-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.
-
 ## Usage
 
 This rule takes between 1 and 4 arguments after the rule validation severity.
 
 The configuration can take any of the following forms:
 
-* File-based Configuration
-  * `[<severity>, "<file>"]` - read the header template from a file.
-  * `[<severity>, "<file>", {<settings>}]` - read the header template from a
+- File-based Configuration
+  - `[<severity>, "<file>"]` - read the header template from a file.
+  - `[<severity>, "<file>", {<settings>}]` - read the header template from a
     file with additional settings.
-* Inline Configuration
-  * `"<severity>", "<comment-type>", <header-contents>` - define the header
+- Inline Configuration
+  - `"<severity>", "<comment-type>", <header-contents>` - define the header
     contents inline.
-  * `[<severity>, "<comment-type>", <header-contents>, {<settings>}]` - define
+  - `[<severity>, "<comment-type>", <header-contents>, {<settings>}]` - define
     the header contents inline and pass additional settings.
-  * `[<severity>, "<comment-type>", <header-contents>, <n-empty-lines>]` -
+  - `[<severity>, "<comment-type>", <header-contents>, <n-empty-lines>]` -
     define the header contents inline and an expected number of empty lines
     after the header.
-  * `[<severity>, "<comment-type>", <header-contents>, <n-empty-lines>, {<settings>}]` -
-    define the header contents inline and an expected number of empty lines
-    after the header and pass additional settings.
+  - `[<severity>, "<comment-type>", <header-contents>, <n-empty-lines>,
+    {<settings>}]` - define the header contents inline and an expected number of
+    empty lines after the header and pass additional settings.
 
 ### File-based Configuration
 
@@ -78,6 +95,7 @@ tree then the header file will not be found.
 ### Inline Configuration
 
 The inline configuration expects at least two arguments to be given:
+
 - _comment-type_ which is either `"block"` or `"line"` to indicate what style
   of comment should be used.
 - _header-contents_ which defines the lines of the header. It can be either a
@@ -88,19 +106,20 @@ The inline configuration expects at least two arguments to be given:
 #### Header Contents Configuration
 
 Suppose we want our header to look like this:
+
 ```js
 /*
  * Copyright (c) 2015
  * My Company
  */
-...
 ```
 
 All of the following configurations will match the header:
-* **Single string**:
+
+- **Single string**:
+
     ```json
     {
-        ...
         "rules": {
             "header/header": [
                 2,
@@ -110,23 +129,30 @@ All of the following configurations will match the header:
         }
     }
     ```
+
     Note that the above would work for both Windows and POSIX systems even
     though the EOL in the header content was specified as `\n`.
 
     Also, notice how we have an empty space before each line. This is because
-    the plugin only strips the leading `//` characters from a line comment/
-    Similar for a block comment, only the opening `/*` and closing `*/` will be
-    preserved.
+    the plugin only strips the leading `//` characters from a line comment.
+    Similarly, for a block comment, only the opening `/*` and closing `*/` will
+    be preserved with all new lines and whitespace preserved. Keep this in mind
+    as this can lead to poorly configured header matching rules that never
+    pass. In a future release error messages would be more detailed and show
+    exactly where header validation failed.
+
+- **Single regular expression**:
 
-* **Single regular expression**:
     ```json
     {
-        ...
         "rules": {
             "header/header": [
                 2,
                 "block",
-                { "pattern": "\\n \\* Copyright \\(c\\) 2015\\n \\* My Company\\n " }
+                {
+                    "pattern":
+                        "\\n \\* Copyright \\(c\\) 2015\\n \\* My Company\\n "
+                }
             ]
         }
     }
@@ -136,75 +162,71 @@ All of the following configurations will match the header:
     `RegExp` objects, the backslashes need to be present in the string instead
     of disappear as escape characters.
 
-    For the comparable example using line comments we cannot use a single
-    expression as the second argument after the severity instead of a string or
-    an array. This is because the pattern will be matched against the first
-    single-line line comment and validation would fail. In general, using the
-    array form is preferable as it is easier to follow.
-
-* **Array of strings**:
-  ```json
-  {
-     ...
-     "rules": {
-        "header/header": [
-            2,
-            "block",
-            [
-                "",
-                " * Copyright (c) 2015",
-                " * My Company",
-                " "
+- **Array of strings**:
+
+    ```json
+    {
+        "rules": {
+            "header/header": [
+                2,
+                "block",
+                [
+                    "",
+                    " * Copyright (c) 2015",
+                    " * My Company",
+                    " "
+                ]
             ]
-        ]
-     }
-  }
-  ```
-* **Array of strings and/or patterns**:
-  ```json
-  {
-     ...
-     "rules": {
-        "header/header": [
-            2,
-            "block",
-            [
-                "",
-                { "pattern": " \\* Copyright \\(c\\) 2015" },
-                " * My Company",
-                " "
+        }
+    }
+    ```
+
+- **Array of strings and/or patterns**:
+
+    ```json
+    {
+        "rules": {
+            "header/header": [
+                2,
+                "block",
+                [
+                    "",
+                    { "pattern": " \\* Copyright \\(c\\) 2015" },
+                    " * My Company",
+                    " "
+                ]
             ]
-        ]
-     }
-  }
-  ```
+        }
+    }
+    ```
 
 Regular expressions allow for a number of improvements in the maintainability
 of the headers. Given the example above, what is clear is that new sources may
 have been created later than 2015 and a comment with a different year should be
-perfectly valid such as:
+perfectly valid, such as:
 
 ```js
 /*
  * Copyright 2020
  * My company
  */
-...
 ```
-Moreover, suppose legal expects that the year of first and last change be added
-except if all changes happen in the same year, we also need to support:
+
+Moreover, suppose your legal department expects that the year of first and last
+change be added except if all changes happen in the same year, we also need to
+support:
+
 ```js
 /*
  * Copyright 2017-2022
  * My company
  */
-...
 ```
+
 We can use a regular expression to support all of these cases for your header:
 
 ```json
 {
-    ...
     "rules": {
         "header/header": [
             2,
@@ -224,11 +246,10 @@ Note on auto-fixes i.e. `eslint --fix`: whenever strings are used to define the
 header - counting in file-based configuration - the same strings would be used
 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. 
+property `template` adds a replacement string.
 
 ```json
 {
-    ...
     "rules": {
         "header/header": [
             2,
@@ -244,7 +265,9 @@ property `template` adds a replacement string.
     }
 }
 ```
+
 There are a number of things to consider:
+
 - Templates need to be matched by the regular expression pattern or otherwise
   an auto-fixed source would again fail linting. This needs to be validated
   manually today as the plugin does not do it for you.
@@ -257,6 +280,7 @@ The third argument of the rule configuration which defaults to 1 specifies the
 number of newlines that are enforced after the header.
 
 Zero newlines:
+
 ```json
 {
     "plugins": [
@@ -275,12 +299,14 @@ Zero newlines:
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */ console.log(1)
 ```
 
 One newline (default):
+
 ```json
 {
     "plugins": [
@@ -299,6 +325,7 @@ One newline (default):
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */
@@ -306,6 +333,7 @@ console.log(1)
 ```
 
 Two newlines:
+
 ```json
 {
     "plugins": [
@@ -324,6 +352,7 @@ Two newlines:
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */
@@ -336,6 +365,7 @@ console.log(1)
 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:
+
 ```json
 "rules": {
     "header/header": [
@@ -351,6 +381,7 @@ system (via Node's `os` package). This setting can be overwritten as follows:
     ]
 }
 ```
+
 Possible values are `"unix"` for `\n` and `"windows"` for `\r\n` line endings.
 
 ## Examples
@@ -380,7 +411,7 @@ console.log(1)
 console.log(1)
 ```
 
-### With more decoration
+With more decoration:
 
 ```json
 "header/header": [2, "block", [
@@ -399,6 +430,51 @@ console.log(1)
  console.log(1);
 ```
 
+## Versioning
+
+The project follows standard [NPM semantic versioning policy](
+https://docs.npmjs.com/about-semantic-versioning).
+
+The following guidelines apply:
+
+- **major versions** - new functionality that breaks compatibility.
+- **minor versions** - new features that do not break compatibility. For the
+  most part we would aim to continue releasing new versions in the 3.x product
+  line and have opt-in flags for changes in behavior of existign features.
+- **revisions** - bugfixes and minor non-feature improvements that do not break
+  compatibility. Note that bug-fixes are allowed to break compatibility with
+  previous version if the older version regressed previous expected behavior.
+
+Two concepts are important when going over the above guidelines and we will go
+over them in the next sections.
+
+### What is a Feature?
+
+We keep the distinction between a feature and a non-feature improvement / bug
+fix as simple as possible:
+
+- If configuration changes, it's a **feature**.
+- If it doesn't, then you have two cases:
+  - If it changes behavior back to what is expected, it is a bug.
+  - If it changes the expected behavior, it is an improvement.
+
+### What is Backward-compatibility?
+
+Backward compatibility in the context of this plugin relates to how the plugin
+consistently passes or fails one and the same code in between upgrades to newer
+backward-compatible versions. This guarantees that plugin updates can be done
+without breaking CI/CD pipeline linting.
+
+Backward-compatibility does not cover the following functional aspects:
+
+- Rule violation messages are not kept stable between backward-compatible
+  versions. This allows us to improve error reporting in addition to bug fixes.
+- Auto-fix behavior is not stable between backward-compatible versions. As auto-
+  fixes are not part of CI/CD processes results of them may vary.
+- Bugs to released functionality. Bugs are considered regression to expected
+  functionality regardless of whether they went into a release or not. We fix
+  bugs without maintaining bug-compatibility.
+
 ## License
 
 MIT

package/index.js

@@ -1,7 +1,7 @@
 /*
  * MIT License
  *
- * Copyright (c) 2015-present Stuart Knightley and contributors
+ * Copyright (c) 2015-present Stuart Knightley, 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
@@ -10,8 +10,8 @@
  * 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 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,

package/lib/comment-parser.js

@@ -1,7 +1,7 @@
 /*
  * MIT License
  *
- * Copyright (c) 2015-present Stuart Knightley and contributors
+ * Copyright (c) 2015-present Stuart Knightley, 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
@@ -10,8 +10,8 @@
  * 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 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,
@@ -24,30 +24,32 @@
 
 "use strict";
 
+const assert = require("assert");
+
 /**
- * Parses a line or block comment and returns the type of comment and an array of content lines.
+ * Parses a line or block comment and returns the type of comment and an array
+ * of content lines.
  *
  * 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.
+ * @returns {['block' | 'line', string | string[]]} comment type and comment
+ *                                                  content broken into lines.
  */
 module.exports = function commentParser(commentText) {
+    assert.strictEqual(typeof commentText, "string");
     const text = commentText.trim();
 
-    if (text.substr(0, 2) === "//") {
+    if (text.startsWith("//")) {
         return [
             "line",
-            text.split(/\r?\n/).map(function(line) {
-                return line.substr(2);
-            })
+            text.split(/\r?\n/).map((line) => line.substring(2))
         ];
-    } else if (
-        text.substr(0, 2) === "/*" &&
-        text.substr(-2) === "*/"
-    ) {
+    } else if (text.startsWith("/*") && text.endsWith("*/")) {
         return ["block", text.substring(2, text.length - 2)];
     } else {
-        throw new Error("Could not parse comment file: the file must contain either just line comments (//) or a single block comment (/* ... */)");
+        throw new Error(
+            "Could not parse comment file: the file must contain either just line comments (//) or a single block " +
+                "comment (/* ... */)");
     }
 };

package/lib/rules/header.docs.js

@@ -0,0 +1,40 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025-present Tony Ganchev and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the “Software”), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+
+"use strict";
+
+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.recommended = true;
+exports.url = "https://www.npmjs.com/package/@tony.ganchev/eslint-plugin-header/v/" + pluginVersion;