eslint-plugin-greasemonkey 1.1.0 → 1.3.0

package/README.md

@@ -1,40 +1,703 @@
-# eslint-plugin-greasemonkey
+<a id="top"></a>
 
-[![](https://img.shields.io/npm/v/eslint-plugin-greasemonkey?style=for-the-badge&label=Latest%20Build&color=32fcee)](https://www.npmjs.com/package/eslint-plugin-greasemonkey)
-<a href="./#license">
-    <img src="https://img.shields.io/badge/License-MIT-f99b27.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+# <img height=24 src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/e9128375d4/assets/images/icons/eslint/purple/icon32.png"> eslint-plugin-greasemonkey
+
+[![](https://img.shields.io/npm/v/eslint-plugin-greasemonkey?logo=icinga&style=for-the-badge&label=Latest%20Build&color=32fcee)][epg-npm]
+[![](https://img.shields.io/badge/License-MIT-f1f20a.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge)](#license)
 [![](https://img.shields.io/badge/Requires-ESLint_%3E%3D9.0.0-4B32C3?style=for-the-badge&logo=eslint)](https://eslint.org/)
 
 ESLint rules for Greasemonkey userscripts.
 
-<img src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/b7c510f949/assets/images/screenshots/meta-spacing/auto-fix.png">
+<img src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/c9ac2985bb/assets/images/screenshots/vs-code/squiggles.png">
+
+---
 
 ## Installation
 
+From your project root:
+
 ```bash
 npm i -D eslint-plugin-greasemonkey
 ```
 
-## Usage (flat config)
+---
+
+## Usage
+
+Add `greasemonkey` [rules][epg-rules] to your `eslint.config.*js`:
 
 ```js
+...
 import greasemonkey from 'eslint-plugin-greasemonkey'
+
 export default [
+    // other configs
     {
         files: ['**/*.user.js'],
         plugins: { greasemonkey },
-        rules: {
-            'greasemonkey/meta-spacing': 'error',
+        rules: { // recommended set w/ default options
+            'greasemonkey/meta-spacing': ['error', 3],
+            'greasemonkey/no-duplicate-keys': 'error',
+            'greasemonkey/no-missing-grants': 'error',
             'greasemonkey/no-unused-grants': 'error',
             'greasemonkey/no-unused-resources': 'error',
+            'greasemonkey/prefer-match': 'error',
             'greasemonkey/require-matching-localized-fields': 'error',
+            'greasemonkey/require-meta-newline': 'error',
             'greasemonkey/require-required-fields': 'error',
-            'greasemonkey/valid-field-values': 'error'
+            'greasemonkey/require-space-before-meta-key': 'error',
+            'greasemonkey/require-user-js-filename': 'error',
+            'greasemonkey/valid-field-values': ['error', { versionType: 'semver' }],
+            'greasemonkey/valid-grants': ['error', { allowedGrants: [] }]
+        }
+    }
+]
+```
+
+...or use a bundled config:
+
+```js
+...
+import greasemonkey from 'eslint-plugin-greasemonkey'
+
+export default [
+    // other configs
+    {
+        files: ['**/*.user.js'],
+        plugins: { greasemonkey }
+        rules: {
+            ...greasemonkey.configs.recommended.rules,  // or .strict.rules
+            'greasemonkey/no-unused-resources': 'off',  // selectively disable rule
+            'greasemonkey/meta-spacing': ['error', 2]   // selectively tweak rule
         }
     }
 ]
 ```
 
+**Note:** Rule config is either a severity string (`'off'`, `'warn'`, `'error'`) or an array `[severity, options]` when the rule accepts options.
+
+---
+
+## Supported rules
+
+| ID | Description | Auto-fixable | Recommended |
+| --- | --- | :-: | :-: |
+| [`meta-spacing`](#meta-spacing-auto-fixable) | Aligns metadata values to the column after the longest key | ✅ | ✅ |
+| [`no-duplicate-keys`](#no-duplicate-keys) | Disallows duplicate metadata keys | ❌ | ✅ |
+| [`no-missing-grants`](#no-missing-grants) | Flags API calls w/o a matching `@grant` | ❌ | ✅ |
+| [`no-unused-grants`](#no-unused-grants) | Flags `@grant` entries whose APIs are never used | ❌ | ✅ |
+| [`no-unused-resources`](#no-unused-resources) | Flags `@resource` entries that are never referenced | ❌ | ✅ |
+| [`prefer-match`](#prefer-match) | Prefers `@match` over `@include` | ❌ | ✅ |
+| [`require-homepage-pair`](#require-homepage-pair-auto-fixable) | Requires `@homepage` and `@homepageURL` to be used together | ✅ | ❌ |
+| [`require-matching-localized-fields`](#require-matching-localized-fields) | Requires matching localized `@name:xx` / `@description:xx` pairs | ❌ | ✅ |
+| [`require-meta-newline`](#require-meta-newline-auto-fixable) | Requires a newline between the metadata and code | ✅ | ✅ |
+| [`require-required-fields`](#require-required-fields) | Requires essential metadata fields | ❌ | ✅ |
+| [`require-space-before-meta-key`](#require-space-before-meta-key-auto-fixable) | Requires exactly one space between `//` and metadata keys | ✅ | ✅ |
+| [`require-update-download-pair`](#require-update-download-pair) | Requires `@updateURL` and `@downloadURL` to be used together | ❌ | ❌ |
+| [`require-user-js-filename`](#require-user-js-filename) | Requires userscript filenames end in `.user.js` | ❌ | ✅ |
+| [`valid-field-values`](#valid-field-values) | Validates `@version` and URL fields | ❌ | ✅ |
+| [`valid-grants`](#valid-grants) | Disallows invalid `@grant` values | ❌ | ✅ |
+---
+
+### `meta-spacing` (auto-fixable)
+
+> Aligns metadata values to the column after the longest key.
+
+#### Options
+
+- `number` (default `3`) – minimum spaces after the longest key
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// @namespace example.com
+// @version 1.0.0
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name        My Script
+// @namespace   example.com
+// @version     1.0.0
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you don't care about visual alignment in metadata blocks.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `no-duplicate-keys`
+
+> Disallows duplicate metadata keys. Multi-value keys are exempt (`@compatible`, `@connect`, `@description`, `@exclude`, `@exclude-match`, `@grant`, `@homepageURL`, `@include`, `@license`, `@match`, `@require`, `@resource`, `@supportURL`).
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name Foo
+// @name Bar
+// @version 1.0.0
+// @version 2.0.0
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// @version 1.0.0
+// @match https://a.example.com/*
+// @match https://b.example.com/*
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you intentionally repeat single-value keys.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `no-missing-grants`
+
+> Flags API calls (e.g. `GM_setValue`, `GM.setValue`, `CAT.agent.dom`) used w/o a matching `@grant` declaration.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+
+GM_setValue('key', 'value')
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// @grant GM_setValue
+// ==/UserScript==
+
+GM_setValue('key', 'value')
+```
+
+#### When not to use it
+
+If you use APIs through aliases or wrappers that obscure the original call site.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `no-unused-grants`
+
+> Flags `@grant` entries whose APIs are never used in the script.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @grant GM_setValue
+// ==/UserScript==
+
+console.log('no GM_setValue call')
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @grant GM_setValue
+// ==/UserScript==
+
+GM_setValue('key', 'value')
+```
+
+#### When not to use it
+
+If you access the granted API through an alias or computed property rather than calling it directly.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `no-unused-resources`
+
+> Flags `@resource` entries that are never referenced via `GM_getResourceText()` or `GM_getResourceURL()`.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @resource myCSS https://example.com/style.css
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @resource myCSS https://example.com/style.css
+// ==/UserScript==
+
+GM_getResourceText('myCSS')
+```
+
+#### When not to use it
+
+If you pass the resource name through a variable or alias rather than using it literally.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `prefer-match`
+
+> Prefers `@match` over `@include` (deprecated in Chrome MV3).
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @include https://example.com/*
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @match https://example.com/*
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you use `@include` in non-MV3 environments, or rely on regex syntax that `@match` cannot express.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-homepage-pair` (auto-fixable)
+
+> Requires `@homepage` and `@homepageURL` to be used together.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @homepage https://example.com
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @homepage    https://example.com
+// @homepageURL https://example.com
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If your target manager does not fall back to `@namespace` when a homepage key is missing (which usually produces a broken URL).
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-matching-localized-fields`
+
+> Requires that every `@name:xx` has a matching `@description:xx` (and vice versa).
+
+#### Options
+
+- `ignoreLanguages` (default `[]`) – language codes to skip, e.g. `['fr', 'de']`
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name:en My Script
+// @description:en Does something
+// @name:fr Mon Script
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name:en My Script
+// @description:en Does something
+// @name:fr Mon Script
+// @description:fr Fait quelque chose
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you intentionally provide localized names without descriptions (or vice versa).
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-meta-newline` (auto-fixable)
+
+> Requires a newline between the closing `// ==/UserScript==` comment and the first line of code.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+console.log('hi')
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+
+console.log('hi')
+```
+
+#### When not to use it
+
+If you don't care about visual separation between metadata and code.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-required-fields`
+
+> Requires essential metadata fields (`@name`, `@version` by default) and at least one `@match` or `@include`.
+
+#### Options
+
+- `fields` (default `['name', 'version']`) – override the required field list
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// @version 1.0.0
+// @match https://example.com/*
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you use a subset of metadata fields that doesn't match the convention.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-space-before-meta-key` (auto-fixable)
+
+> Requires exactly one space between `//` and metadata keys.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+//@name My Script
+//  @version 1.0.0
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// @version 1.0.0
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you intentionally use a different prefix style.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-update-download-pair`
+
+> Requires `@updateURL` and `@downloadURL` to be used together.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @downloadURL https://example.com/script.user.js
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @downloadURL https://example.com/script.user.js
+// @updateURL   https://example.com/script.meta.js
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you don't target Tampermonkey (where `@updateURL` avoids re-downloading the full script on every update check).
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `require-user-js-filename`
+
+> Requires that files containing a userscript metadata block end in `.user.js`.
+
+#### When not to use it
+
+If you intentionally name your userscripts something other than `*.user.js`.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `valid-field-values`
+
+> Validates `@version` (semver or date format) and URL fields (`@homepage`, `@icon`, `@icon64`, `@require`, `@resource`, `@source`, `@website`, any key ending in `URL` case-insensitively).
+
+#### Options
+
+- `versionType` (default `'semver'`) – version format to enforce (`'semver'`, `'date'`)
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @version abc
+// @homepage not-a-url
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @version 1.0.0
+// @homepage https://example.com
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you use a custom versioning scheme or URLs that aren't standard.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+### `valid-grants`
+
+> Disallows invalid `@grant` values.
+
+#### Options
+
+- `allowedGrants` (default `[]`) – additional `@grant` values to allow beyond the built-in list (covering Tampermonkey, Violentmonkey and ScriptCat)
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @grant GM_notificaiton
+// @grant gm_setvalue
+// @grant GM_xmlHttpRequest
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @grant GM_notification
+// @grant GM_setValue
+// @grant GM_xmlhttpRequest
+// ==/UserScript==
+```
+
+#### When not to use it
+
+If you don't want `@grant` validation at all. For individual uncovered grants, prefer whitelisting via `allowedGrants` over disabling the rule.
+
+<div align="center">
+
+[Back to index ↑][epg-rules]
+
+</div>
+
+---
+
+## Shield
+
+<a href="https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#readme">
+    <img height=32 alt="[Linted by eslint-plugin-greasemonkey]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--greasemonkey-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+
+#### HTML
+
+```html
+<a href="https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#readme">
+    <img height=32 alt="[Linted by eslint-plugin-greasemonkey]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--greasemonkey-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+```
+
+#### Markdown
+
+```md
+[![Linted by eslint-plugin-greasemonkey](https://img.shields.io/badge/Linted_by-eslint--plugin--greasemonkey-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge)](https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#readme)
+```
+
+---
+
 ## License
 
-Copyright © 2026 [Adam Lui](https://codeberg.org/adamlui).
+[<img height=62 src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/9e820e5d51/assets/images/logos/mit-license/red-pixelated.png">][epg-license] 
+
+<details>
+
+<summary>Copyright © 2026 <a href="https://codeberg.org/adamlui">Adam Lui</a> under the <a href="https://codeberg.org/adamlui/eslint-plugin-greasemonkey/src/branch/main/docs/LICENSE.md">MIT license</a>.</summary><br>
+
+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
+
+</details>
+
+---
+
+## Related
+
+ <!-- eslint-plugin-constructors -->
+
+### [<img height=15 width=auto src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/e9128375d4/assets/images/icons/eslint/purple/icon16.png">][epc-readme] [eslint-plugin-constructors][epc-readme]
+
+<details>
+
+<summary>ESLint rules for JavaScript constructor usage.</summary><br>
+
+> [<img width=555 src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-constructors/6eeba7b2cb/assets/images/screenshots/vs-code/squiggles.png">][epc-readme]
+
+> [**Install**][epc-install] / [Readme][epc-readme] / [Supported rules][epc-rules]
+
+</details>
+
+[epc-install]: https://codeberg.org/adamlui/eslint-plugin-constructors/#installation
+[epc-readme]: https://codeberg.org/adamlui/eslint-plugin-constructors/#readme
+[epc-rules]: https://codeberg.org/adamlui/eslint-plugin-constructors/#supported-rules
+
+<!-- Footer -->
+
+<img height=10 width="100%" src="https://cdn.staticdelivr.com/gl/adamlui/ai-web-extensions/d11d2ee/assets/images/separators/gradient-aqua.png">
+
+<div align="center">
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.staticdelivr.com/gl/adamlui/js-utils/6b0d399/assets/images/icons/tag/white/icon16.svg"><img height=14 src="https://cdn.staticdelivr.com/gl/adamlui/js-utils/6b0d399/assets/images/icons/tag/dark-gray/icon16.svg"></picture>
+[**Latest releases**][epg-releases] / [Report a bug][epg-bugs] / [More packages by author][adamlui-npmx] / [Back to top ↑](#top)
+
+</div>
+
+<!-- Links -->
+
+[adamlui-npmx]: https://npmx.dev/org/adamlui
+[epg-bugs]: https://codeberg.org/adamlui/eslint-plugin-greasemonkey/issues/new
+[epg-license]: https://codeberg.org/adamlui/eslint-plugin-constructors/src/branch/main/docs/LICENSE.md
+[epg-npm]: https://www.npmjs.com/package/eslint-plugin-greasemonkey
+[epg-releases]: https://codeberg.org/adamlui/eslint-plugin-greasemonkey/releases
+[epg-rules]: #supported-rules