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

package/README.md

@@ -45,6 +45,10 @@ It addresses the following issus:
 The plugin supports ESLint 7 / 8 / 9 / 10rc0 (check package.json for details).
 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
 
 The plugin and its _header_ rule goes through evolution of its configuration in
@@ -63,14 +67,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 +103,8 @@ export default defineConfig([
                     header: {
                         file: "config/header.js"
                     }
-                }
-            ]
+                } as HeaderOptions
+            ] as HeaderRuleConfig
         }
     }
 ]);
@@ -132,8 +149,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 +167,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 +190,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 +210,7 @@ All of the following configurations will match the header:
                                 /\n \* Copyright \(c\) 2015\n \* Company\n /
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -203,8 +220,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 +241,7 @@ All of the following configurations will match the header:
                                     + "\\n \\* My Company\\n "}
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -239,8 +256,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 +276,7 @@ All of the following configurations will match the header:
                                 { pattern: /Copyright \(c\) 20\d{2}/ }
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -268,8 +285,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 +308,7 @@ All of the following configurations will match the header:
                                 " "
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -300,8 +317,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 +340,7 @@ All of the following configurations will match the header:
                                 " "
                             ]
                         }
-                    }
+                    } as HeaderOptions
                 ]
             }
         }
@@ -355,8 +372,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 +395,7 @@ export default defineConfig([
                             " "
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -391,8 +408,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 +432,7 @@ export default defineConfig([
                             " My Company"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -437,8 +454,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 +478,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 0
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -475,8 +492,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 +516,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 1
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -514,8 +531,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 +555,7 @@ export default defineConfig([
                     trailingEmptyLines: {
                         minimum: 2
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -558,8 +575,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 +597,7 @@ export default defineConfig([
                         ]
                     },
                     lineEndings: "windows"
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -594,8 +611,8 @@ The default value is `"os"` which means assume the system-specific line endings.
 
 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 +629,7 @@ export default defineConfig([
                         commentType: "block",
                         lines: ["Copyright 2015, My Company"]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -624,8 +641,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 +662,7 @@ export default defineConfig([
                             "My Company"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -658,8 +675,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 +696,7 @@ export default defineConfig([
                             /^My Company$/
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }
@@ -694,8 +711,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 +734,7 @@ export default defineConfig([
                             " ************************"
                         ]
                     }
-                }
+                } as HeaderOptions
             ]
         }
     }

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/header.docs.js

@@ -29,11 +29,11 @@ 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 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 = packageJsonContent.version;
+const pluginVersion = packageJson.version;
 
 exports.description = "";
 exports.recommended = true;