@tony.ganchev/eslint-plugin-header 3.3.3 → 3.4.0

package/README.md

@@ -2,18 +2,23 @@
 
 [![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)
+[![Build Status](https://github.com/tonyganchev/eslint-plugin-header/actions/workflows/test.yml/badge.svg)](https://github.com/tonyganchev/eslint-plugin-header/actions/workflows/test.yml?query=branch%3Amain)
 
 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.
+and banner comments in JavaScript, TypeScript, CSS, HTML, and Markdown files.
+Supports _oxlint_.
 
 ## Table of Contents
 
 1. [Motivation and Acknowledgements](#motivation-and-acknowledgements)
-2. [Compatibility](#compatibility)
-3. [Usage](#usage)
+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)
       1. [Header Contents Configuration](#header-contents-configuration)
@@ -23,14 +28,17 @@ and banner comments in JavaScript and TypeScript files.
    3. [Support for Leading Comments](#support-for-leading-comments)
       1. [Notes on Behavior](#notes-on-behavior)
    4. [Examples](#examples)
-4. [Comparison to Alternatives](#comparison-to-alternatives)
+   5. [Linting CSS](#linting-css)
+   6. [Linting HTML](#linting-html)
+   7. [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)
-5. [Versioning](#versioning)
+6. [Versioning](#versioning)
    1. [What is a Feature?](#what-is-a-feature)
    2. [What is Backward-compatibility?](#what-is-backward-compatibility)
-6. [License](#license)
+7. [License](#license)
 
 ## Motivation and Acknowledgements
 
@@ -56,19 +64,87 @@ 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.
 
+## Major Consumers
+
+The plugin is used by hundreds of projects to enforce license compliance and
+consistent header structures. Notable adopters include:
+
+[![Microsoft](https://github.com/microsoft.png?size=48)](./docs/consumers.md#microsoft)
+   
+[![Microsoft Azure](https://github.com/azure.png?size=48)](./docs/consumers.md#azure)
+   
+[![Salesforce](https://github.com/forcedotcom.png?size=48)](./docs/consumers.md#salesforce)
+   
+[![Angular](https://github.com/angular.png?size=48)](./docs/consumers.md#angular)
+   
+[![Amazon](https://github.com/aws.png?size=48)](./docs/consumers.md#amazon)
+   
+[![Amazon Cloudscape Design System](https://github.com/cloudscape-design.png?size=48)](./docs/consumers.md#cloudscape-design-system)
+   
+[![Eclipse GLSP](https://github.com/eclipse.png?size=48)](./docs/consumers.md#eclipse-foundation)
+   
+[![Salto](https://github.com/salto-io.png?size=48)](./docs/consumers.md#salto)
+   
+[![Dash0 OpenTelemetry JS Distribution](https://github.com/dash0hq.png?size=48)](./docs/consumers.md#dash0)
+   
+[![IBM InspectorRAGet](https://github.com/ibm.png?size=48)](./docs/consumers.md#ibm)
+   
+[![FlowCrypt Browser Extensions](https://github.com/flowcrypt.png?size=48)](./docs/consumers.md#flowcrypt)
+   
+[![Cratis](https://github.com/Cratis.png?size=48)](./docs/consumers.md#cratis)
+   
+[![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)
+
+Learn more about how these organizations use the plugin on our
+[consumers list](./docs/consumers.md).
+
 ## 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,
+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; 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 |
+| 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
@@ -141,6 +217,34 @@ Due to limitations in ESLint plugins, the file is read relative to the working
 directory that ESLint is executed in. If you run ESLint from elsewhere in your
 tree then the header file will not be found.
 
+The equivalent configuration for _oxlint_ is:
+
+```json
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    "overrides": [
+        {
+            "files": [
+                "**/*.js"
+            ],
+            "rules": {
+                "@tony.ganchev/header/header": [
+                    "error",
+                    {
+                        "header": {
+                            "file": "config/header.js"
+                        }
+                    }
+                ]
+            },
+            "jsPlugins": [
+                "@tony.ganchev/eslint-plugin-header"
+            ]
+        }
+    ]
+}
+```
+
 ### Inline Configuration
 
 In this configuration mode, the matching rules for the header are given inline.
@@ -194,6 +298,37 @@ All of the following configurations will match the header:
     ]);
     ```
 
+    Equivalent configuration for _oxlint_:
+
+    ```json
+    {
+        "$schema": "./node_modules/oxlint/configuration_schema.json",
+        "overrides": [
+            {
+                "files": [
+                    "**/*.js"
+                ],
+                "rules": {
+                    "@tony.ganchev/header/header": [
+                        "error",
+                        {
+                            "header": {
+                                "commentType": "block",
+                                "lines": [
+                                    "\n * Copyright (c) 2015\n * My Company\n "
+                                ]
+                            }
+                        }
+                    ]
+                },
+                "jsPlugins": [
+                    "@tony.ganchev/eslint-plugin-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`.
 
@@ -1048,10 +1183,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:
@@ -1086,14 +1266,126 @@ 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 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

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."
+        );
     }
 };