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

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,6 +106,7 @@ 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
@@ -97,10 +116,11 @@ Suppose we want our header to look like this:
 ```
 
 All of the following configurations will match the header:
-* **Single string**:
+
+- **Single string**:
+
     ```json
     {
-        ...
         "rules": {
             "header/header": [
                 2,
@@ -110,23 +130,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,53 +163,48 @@ 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
 /*
@@ -191,8 +213,11 @@ perfectly valid such as:
  */
 ...
 ```
-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
@@ -200,11 +225,11 @@ except if all changes happen in the same year, we also need to support:
  */
 ...
 ```
+
 We can use a regular expression to support all of these cases for your header:
 
 ```json
 {
-    ...
     "rules": {
         "header/header": [
             2,
@@ -224,11 +249,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 +268,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 +283,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 +302,14 @@ Zero newlines:
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */ console.log(1)
 ```
 
 One newline (default):
+
 ```json
 {
     "plugins": [
@@ -299,6 +328,7 @@ One newline (default):
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */
@@ -306,6 +336,7 @@ console.log(1)
 ```
 
 Two newlines:
+
 ```json
 {
     "plugins": [
@@ -324,6 +355,7 @@ Two newlines:
     }
 }
 ```
+
 ```js
 /* Copyright now
 My Company */
@@ -336,6 +368,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 +384,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 +414,7 @@ console.log(1)
 console.log(1)
 ```
 
-### With more decoration
+With more decoration:
 
 ```json
 "header/header": [2, "block", [
@@ -399,6 +433,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/lib/rules/header.js

@@ -454,18 +454,19 @@ module.exports = {
                                         message: "incorrect header",
                                         fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
                                     });
-                                }
-                                return;
-                            }
-                            for (var i = 0; i < headerLines.length; i++) {
-                                if (!match(leadingComments[i].value, headerLines[i])) {
-                                    context.report({
-                                        loc: node.loc,
-                                        message: "incorrect header",
-                                        fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
-                                    });
                                     return;
                                 }
+                            } else {
+                                for (var i = 0; i < headerLines.length; i++) {
+                                    if (!match(leadingComments[i].value, headerLines[i])) {
+                                        context.report({
+                                            loc: node.loc,
+                                            message: "incorrect header",
+                                            fix: canFix ? genReplaceFixer(commentType, context, leadingComments, fixLines, eol, numNewlines) : null
+                                        });
+                                        return;
+                                    }
+                                }
                             }
 
                             var postLineHeader = context.getSourceCode().text.substr(leadingComments[headerLines.length - 1].range[1], numNewlines * 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tony.ganchev/eslint-plugin-header",
-  "version": "3.1.8",
+  "version": "3.1.9",
   "description": "ESLint plugin to ensure files begin with a given comment, usually a copyright or license notice.",
   "main": "index.js",
   "files": [