@tony.ganchev/eslint-plugin-header 3.3.4 → 3.4.1

package/README.md

@@ -7,13 +7,17 @@
 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. Supports _oxlint_.
+and banner comments in JavaScript, TypeScript, Vue, CSS, HTML, and Markdown files.
+Supports _oxlint_.
 
 ## Table of Contents
 
 1. [Motivation and Acknowledgements](#motivation-and-acknowledgements)
 2. [Major Consumers](#major-consumers)
 3. [Compatibility](#compatibility)
+   1. [Runtimes](#runtimes)
+   2. [Configuration Formats](#configuration-formats)
+   3. [Languages](#languages)
 4. [Usage](#usage)
    1. [File-based Configuration](#file-based-configuration)
    2. [Inline Configuration](#inline-configuration)
@@ -24,10 +28,15 @@ and banner comments in JavaScript and TypeScript files. Supports _oxlint_.
    3. [Support for Leading Comments](#support-for-leading-comments)
       1. [Notes on Behavior](#notes-on-behavior)
    4. [Examples](#examples)
+   5. [Linting CSS](#linting-css)
+   6. [Linting HTML](#linting-html)
+   7. [Linting Vue](#linting-vue)
+   8. [Linting Markdown](#linting-markdown)
 5. [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)
+   3. [Compared to eslint-plugin-notice](#compared-to-eslint-plugin-notice)
 6. [Versioning](#versioning)
    1. [What is a Feature?](#what-is-a-feature)
    2. [What is Backward-compatibility?](#what-is-backward-compatibility)
@@ -88,6 +97,8 @@ consistent header structures. Notable adopters include:
    
 [![Mysten Labs](https://github.com/MystenLabs.png?size=48)](./docs/consumers.md#mysten-labs)
    
+[![Suwayomi](https://github.com/Suwayomi.png?size=48)](./docs/consumers.md#suwayomi)
+   
 [![Wire Swiss GmbH](https://github.com/wireapp.png?size=48)](./docs/consumers.md#wire-swiss-gmbh)
    
 [![WPPConnect](https://github.com/wppconnect-team.png?size=48)](./docs/consumers.md#wppconnect)
@@ -97,17 +108,46 @@ Learn more about how these organizations use the plugin on our
 
 ## Compatibility
 
+### Runtimes
+
 The plugin supports **ESLint 7 / 8 / 9 / 10**. Both **flat** config and legacy,
 **hierarchical** config can be used. We have a smoke-test running to confirm the
-plugin works with the latest version of ESLint.
+plugin works with the latest version of ESLint. Certain features such as linting
+copyright headers in CSS, HTML, or Markdown rely on APIs introduced with ESLint
+9 and cannot be used with older ESLint versions.
 
 The plugin works with latest version of **oxlint** too. We have a smoke-test
-running to confirm the plugin works with the latest version of oxlint.
+running to confirm the plugin works with the latest version of oxlint. Features
+relying on the use of non-standard parsers such as linting headers in CSS, HTML,
+Vue, or Markdown cannot be supported.
+
+### Configuration Formats
+
+The plugin supports hierarchical and flat configuration format for ESLint as
+well as the configuration format for oxlint.
 
 The NPM package provides TypeScript type definitions and can be used with
 TypeScript-based ESLint flat configuration without the need for `@ts-ignore`
 statements. Smoke tests cover this support as well.
 
+### Languages
+
+Currently the plugin supports linting copyright headers in JavaScript,
+TypeScript and their JSX / TSX flavors; Vue, CSS, HTML, and Markdown files. As
+mentioned in the previous sections, not all languages are supported for oxlint
+or ESLint older than 9. Refer to the table below for more details.
+
+| Language   | ESLint 7 / 8  | ESLint 9 / 10 | oxlint |
+|------------|---------------|---------------|--------|
+| JavaScript | ✅ Yes        | ✅ Yes        | ✅ Yes |
+| TypeScript | ✅ Yes        | ✅ Yes        | ✅ Yes |
+| JSX        | ✅ Yes        | ✅ Yes        | ✅ Yes |
+| TSX        | ✅ Yes        | ✅ Yes        | ✅ Yes |
+| Vue        | ✅ Yes        | ✅ Yes        | ❌ No  |
+| CSS        | ❌ No         | ✅ Yes        | ❌ No  |
+| HTML       | ❌ No         | ✅ Yes        | ❌ No  |
+| Markdown   | ❌ No         | ✅ Yes        | ❌ No  |
+
 ## Usage
 
 The plugin and its _header_ rule goes through evolution of its configuration in
@@ -1146,10 +1186,55 @@ export default defineConfig([
 ]);
 ```
 
+### Linting CSS
+
+The rule supports validating and auto-fixing headers in CSS files. To
+use the plugin with these file types, you need to configure the official
+`@eslint/css` plugin.
+
+**Note: the plugin does not support SCSS** as no current popular parser for
+ESLint supports SCSS / LESS that being a prerequisite for this plugin to be
+called. It is possible to rely on a dummy pass-through parser to ensure the SCSS
+/ LESS sources simply reach the rule but as of the time of the publisihng of
+this document we have not tested this approach.
+
+Back to CSS, let us use the following configuration:
+
+_eslint.config.js_:
+
 ```js
-//Copyright 2017
-//My Company
-console.log(1)
+import header from "@tony.ganchev/eslint-plugin-header";
+import css from "@eslint/css";
+
+export default [
+    {
+        files: ["**/*.css"],
+        plugins: {
+            "@tony.ganchev": header,
+            css
+        },
+        language: "css/css",
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2025 "]
+                    }
+                }
+            ]
+        }
+    }
+];
+```
+
+```css
+/* Copyright 2025 */
+
+.foo {
+    color: blue;
+}
 ```
 
 With more decoration:
@@ -1184,14 +1269,174 @@ export default defineConfig([
 ]);
 ```
 
-```js
+```css
 /*************************
  * Copyright 2015
  * My Company
  *************************/
- console.log(1);
+
+.foo {
+    color: blue
+}
+```
+
+As you can expect with CSS syntax, line comments and shebangs are not supported.
+All other features of the rule remain the same.
+
+### Linting HTML
+
+The rule supports linting copyright notices in HTML files. The rule works with
+the _@html-eslint/eslint-plugin_ plugin and its parser.
+
+Similar to CSS, all you need to do to turn on header validation is to configure
+the _\@html-eslint/eslint-plugin_ plugin and the rule:
+
+```ts
+import header from "@tony.ganchev/eslint-plugin-header";
+import html from "@html-eslint/eslint-plugin";
+
+export default [
+    {
+        files: ["**/*.html"],
+        plugins: {
+            "@tony.ganchev": header,
+            html
+        },
+        language: "html/html",
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2025 "]
+                    }
+                }
+            ]
+        }
+    }
+];
+```
+
+```html
+<!-- Copyright 2025 -->
+
+<html>
+<body>
+    <h1>Hello, world!</h1>
+    <p>Lorem ipsum dolor.</p>
+</body>
+</html>
+```
+
+As with CSS, only block comments are supported - no line- or shebang comments.
+
+### Linting Vue
+
+The rule supports linting copyright notices in Vue files. The rule works with
+the _eslint-plugin-vue_ plugin and its parser.
+
+To turn on header validation for Vue files, configure the parser, the plugin,
+and the rule:
+
+```ts
+import header from "@tony.ganchev/eslint-plugin-header";
+import vueParser from "vue-eslint-parser";
+import vuePlugin from "eslint-plugin-vue";
+
+export default [
+    {
+        files: ["**/*.vue"],
+        plugins: {
+            "@tony.ganchev": header,
+            vue: vuePlugin
+        },
+        languageOptions: {
+            parser: vueParser
+        },
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2025 "]
+                    }
+                }
+            ]
+        }
+    }
+];
+```
+
+```vue
+<!-- Copyright 2025 -->
+<template>
+    <div>Hello, world!</div>
+</template>
+```
+
+As with HTML and CSS, only block comments are supported at the top of the file -
+no line- or shebang comments.
+
+### Linting Markdown
+
+The rule supports copyright comments in Markdown syntax in both _commonmark_ and
+_gfm_ flavors using the _\@eslint/markdown_ plugin and parser. Only HTML
+comments are supported - no anchor hacks or similar are accepted.
+
+Similar to CSS, all you need to do to turn on header validation is to configure
+the _\@eslint/markdown_ plugin and the rule:
+
+```ts
+import header from "@tony.ganchev/eslint-plugin-header";
+import markdown from "@eslint/markdown";
+
+export default [
+    {
+        files: ["**/*.md"],
+        plugins: {
+            "@tony.ganchev": header,
+            markdown
+        },
+        // ... or "markdown/gfm"
+        language: "markdown/commonmark",
+        rules: {
+            "@tony.ganchev/header": [
+                "error",
+                {
+                    header: {
+                        commentType: "block",
+                        lines: [" Copyright 2025 "]
+                    }
+                }
+            ]
+        }
+    }
+];
 ```
 
+```md
+    <!-- Copyright 2025 -->
+    
+    # Title
+    
+    ## Subtitle
+    
+    ## Code
+    
+    ```js
+    console.log("Hello, world!");
+    ```
+```
+
+Note that if you have configured header for `*.js` files, the linter would fail
+on the first line of the nested JavaScript snippet. Look up how to differentiate
+the configuration of JavaScript sources (`**/*.js`) from JavaScript snippets in
+Markdown (`**/*.md/*.js`). Same applies to `*.ts`, `*.jsx`, `*.tsx`, etc.
+
+As with CSS, only block comments are supported - no line- or shebang comments.
+
 ## Comparison to Alternatives
 
 A number of projects have been aiming to solve problems similar to
@@ -1209,12 +1454,16 @@ _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).
+_eslint-plugin-headers_ is not a drop-in replacement. It offers additional
+features that are not first-level use-cases for
+_\@tony.ganchev/eslint-plugin-header_. One example is support for `{year}`
+variable placeholders which are redundant with ESLint's JavaScript-based
+configuration as [already pointed out in this document](#providing-to-year-in-auto-fix).
+JSDoc support can be achieved with regular expressions and the overall
+configuration capabilities of _\@tony.ganchev/eslint-plugin-header_. It is worth
+noting that the source code of _\@tony.ganchev/eslint-plugin-header_ already
+uses JSDoc-style comments for its own header which are in turn validated using
+_\@tony.ganchev/eslint-plugin-header/header_ rule.
 
 The configuration format philosophy of the two plugin differs.
 _\@tony.ganchev/eslint-plugin-header_ supports both the legacy model inherited
@@ -1281,6 +1530,30 @@ We have prepared a detailed
 [migration guide](docs/migrate-from-license-header.md) for anyone eager to
 migrate to _\@tony.ganchev/eslint-plugin-header_.
 
+### Compared to [eslint-plugin-notice](https://github.com/earl-man/eslint-plugin-notice)
+
+_eslint-plugin-notice_ is another alternative that uses a template-based approach
+(powered by Lodash templates) to manage headers. This makes it quite powerful for
+dynamic content but also brings in more dependencies and a more complex
+configuration schema that doesn't always feel "native" to the new ESLint Flat
+Config era.
+
+Key differences:
+
+- **Philosophy**: _\@tony.ganchev/eslint-plugin-header_ focuses on a zero-bloat,
+  native ESLint feel with first-class support for Flat Config and TypeScript.
+- **ESLint 9/10**: Our plugin is built from the ground up to support the latest
+  ESLint versions and their core features.
+- **Languages**: We provide native support for linting headers in HTML, CSS,
+  and Markdown via their respective ESLint ecosystem plugins.
+- **Simplicity**: No need for external template engines or complex variable
+  mappings. Use standard JavaScript template literals in your `eslint.config.ts`
+  to handle dynamic years or other variables.
+
+We have prepared a detailed
+[migration guide](docs/migrate-from-notice.md) for anyone eager to
+migrate to _\@tony.ganchev/eslint-plugin-header_.
+
 ## Versioning
 
 The project follows standard [NPM semantic versioning policy](

package/lib/comment-parser.js

@@ -26,6 +26,10 @@
 
 const assert = require("node:assert");
 
+/**
+ * @import { CommentType, Language } from './rules/header'
+ */
+
 /**
  * Parses a line or block comment and returns the type of comment and an array
  * of content lines.
@@ -33,24 +37,34 @@ const assert = require("node:assert");
  * 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 Content to parse.
- * @returns {[import("./rules/header").CommentType, string[]]} Comment type and
- * comment content broken into lines.
+ * @param {Language} language The language
+ * configuration.
+ * @returns {[CommentType, string[]]} Comment type and
+ * content.
  * @throws {Error} If `commentText` starts with an unrecognized comment token.
  */
-module.exports = function commentParser(commentText) {
+module.exports = function commentParser(commentText, language) {
     assert.strictEqual(typeof commentText, "string");
+    assert.ok(language);
+
     const text = commentText.trim();
+    const lc = language.lineComment;
+    const bc = language.blockComment;
 
-    if (text.startsWith("//")) {
+    if (lc && text.startsWith(lc.startDelimiter)) {
         return [
             "line",
-            text.split(/\r?\n/).map((line) => line.substring(2))
+            text.split(/\r?\n/).map((line) => line.substring(lc.startDelimiter.length))
+        ];
+    } else if (bc && text.startsWith(bc.startDelimiter) && text.endsWith(bc.endDelimiter)) {
+        return [
+            "block",
+            text.substring(bc.startDelimiter.length, text.length - bc.endDelimiter.length).split(/\r?\n/)
         ];
-    } else if (text.startsWith("/*") && text.endsWith("*/")) {
-        return ["block", text.substring(2, text.length - 2).split(/\r?\n/)];
     } else {
         throw new Error(
-            "Could not parse comment file: the file must contain either just line comments (//) or a single block " +
-                "comment (/* ... */)");
+            "Could not parse comment file: the file must contain a comment " +
+            "that matches the supplied language delimiters."
+        );
     }
 };