eslint-plugin-greasemonkey 1.0.0 → 1.2.0

package/README.md

@@ -1,37 +1,492 @@
-# eslint-plugin-greasemonkey
-
-[![](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">
-
-## Installation
-
-```bash
-npm i -D eslint-plugin-greasemonkey
-```
-
-## Usage (flat config)
-
-```js
-import greasemonkey from 'eslint-plugin-greasemonkey'
-export default [
-    {
-        files: ['**/*.user.js'],
-        plugins: { greasemonkey },
-        rules: {
-            'greasemonkey/meta-spacing': 'error',
-            'greasemonkey/no-unused-grants': 'error',
-            'greasemonkey/no-unused-resources': 'error',
-            'greasemonkey/require-matching-localized-fields': 'error',
-            'greasemonkey/require-required-fields': 'error',
-            'greasemonkey/valid-field-values': 'error'
-        }
-    }
-]
-```
-
-## License
-
-Copyright © 2026 [Adam Lui](https://codeberg.org/adamlui).
+<a id="top"></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/c9ac2985bb/assets/images/screenshots/vs-code/squiggles.png">
+
+## Installation
+
+From your project root:
+
+```bash
+npm i -D eslint-plugin-greasemonkey
+```
+
+## Usage
+
+Add `greasemonkey` to your flat config:
+
+```js
+import greasemonkey from 'eslint-plugin-greasemonkey'
+
+export default [
+    {
+        files: ['**/*.user.js'],
+        plugins: { greasemonkey },
+        rules: {
+            'greasemonkey/meta-spacing': ['error', 3],
+            'greasemonkey/no-duplicate-keys': 'error',
+            'greasemonkey/no-unused-grants': 'error',
+            'greasemonkey/no-unused-resources': 'error',
+            'greasemonkey/require-matching-localized-fields': 'error',
+            'greasemonkey/require-required-fields': 'error',
+            'greasemonkey/require-user-js-filename': 'error',
+            'greasemonkey/valid-field-values': ['error', { versionType: 'semver' }],
+            'greasemonkey/valid-grants': ['error', { allowedGrants: [] }]
+        }
+    }
+]
+```
+
+**Note:** Rule config is either a severity string (`'off'`, `'warn'`, `'error'`) or an array `[severity, options]` when the rule accepts options.
+
+To use the bundled recommended config (enables all 8 rules at `'error'`):
+
+```js
+import greasemonkey from 'eslint-plugin-greasemonkey'
+
+export default [
+    {
+        files: ['**/*.user.js'],
+        ...greasemonkey.configs.recommended
+    }
+]
+```
+
+## Supported rules
+
+| ID | Description | Auto-fixable | Recommended |
+| --- | --- | :-: | :-: |
+| [`meta-spacing`](#meta-spacing) | Aligns metadata values to the column after the longest key | ✅ | ✅ |
+| [`no-duplicate-keys`](#no-duplicate-keys) | Disallows duplicate metadata keys | ❌ | ✅ |
+| [`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 | ❌ | ✅ |
+| [`require-matching-localized-fields`](#require-matching-localized-fields) | Requires matching localized `@name:xx` / `@description:xx` pairs | ❌ | ✅ |
+| [`require-required-fields`](#require-required-fields) | Requires essential metadata fields | ❌ | ✅ |
+| [`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`
+
+> Aligns metadata values to the column after the longest key. The longest `@resource` name (if present) is included in the column calculation so resource URLs align with other values.
+
+#### 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-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 declare grants for APIs you use indirectly (e.g. via dynamic variable names or `eval`).
+
+<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 reference resources indirectly (e.g., building the resource name dynamically).
+
+<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` (string[], 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-required-fields`
+
+> Requires essential metadata fields (`@name`, `@namespace`, `@version`) and at least one `@match` or `@include`.
+
+#### Options
+
+- `fields` (string[], default `['name', 'namespace', 'version']`) – override the required field list
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// @namespace example.com
+// @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-user-js-filename`
+
+> Requires that files containing a userscript metadata block end in `.user.js`.
+
+#### Incorrect code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+// (file: script.js)
+```
+
+#### Correct code
+
+```js
+// ==UserScript==
+// @name My Script
+// ==/UserScript==
+// (file: script.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` (`'semver'` | `'date'`, default `'semver'`) – version format to enforce
+
+#### 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` (string[], 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 unlisted grants, prefer the `allowedGrants` option 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
+
+<details>
+
+<summary>
+
+Copyright © 2026 [Adam Lui][adamlui-cb] under the [MIT license](./docs/LICENSE.md).
+
+</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] / [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">
+<br><br>
+
+<div align="center">
+
+[**Latest releases**][epg-releases] / [Report a bug][epg-bugs] / [More packages by author][adamlui-npmx] / [Back to top ↑](#top)
+
+</div>
+
+<!-- Links -->
+
+[adamlui-cb]: https://codeberg.org/adamlui
+[adamlui-npmx]: https://npmx.dev/org/adamlui
+[epg-bugs]: https://codeberg.org/adamlui/eslint-plugin-greasemonkey/issues/new
+[epg-npm]: https://www.npmjs.com/package/eslint-plugin-greasemonkey
+[epg-releases]: https://codeberg.org/adamlui/eslint-plugin-greasemonkey/releases
+[epg-rules]: #supported-rules

package/docs/LICENSE.md

@@ -0,0 +1,9 @@
+# 🏛️ MIT License
+
+**Copyright © 2026 [Adam Lui](https://codeberg.org/adamlui).**
+
+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

package/docs/SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+
+If you find a vulnerability, please e-mail <security@kudoai.org>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-greasemonkey",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
   "type": "module",
   "engines": {
@@ -12,9 +12,27 @@
     "url": "https://codeberg.org/adamlui"
   },
   "homepage": "https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#readme",
+  "bugs": {
+    "url": "https://codeberg.org/adamlui/eslint-plugin-greasemonkey/issues",
+    "email": "support@adamlui.com"
+  },
   "license": "MIT",
+  "funding": [
+    {
+      "type": "ko-fi",
+      "url": "https://ko-fi.com/adamlui"
+    },
+    {
+      "type": "paypal",
+      "url": "https://paypal.me/adamlui"
+    }
+  ],
   "main": "src/index.js",
-  "files": ["src"],
+  "files": [
+    "docs/",
+    "src/"
+  ],
+  "types": "src/index.d.ts",
   "scripts": {
     "prepare": "husky",
     "lint": "eslint . --cache",
@@ -22,29 +40,45 @@
     "lint:fix": "eslint . --fix --cache",
     "lint:fix-all": "eslint . --fix",
     "test": "node tests/run.js",
-    "demo": "eslint --config demo/eslint.config.js demo/example.user.js"
+    "demo": "eslint --config demo/eslint.config.js demo/example.user.js",
+    "bump:patch": "bash utils/bump.sh patch",
+    "bump:minor": "bash utils/bump.sh minor",
+    "bump:feat": "npm run bump:minor",
+    "bump:major": "bash utils/bump.sh major"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/adamlui/eslint-plugin-greasemonkey.git"
   },
   "keywords": [
-    "greasemonkey",
-    "tampermonkey",
-    "userscript",
     "eslint",
     "eslint-plugin",
-    "metadata"
+    "eslintplugin",
+    "greasemonkey",
+    "metadata",
+    "tampermonkey",
+    "userscript"
   ],
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
   "devDependencies": {
+    "@e18e/eslint-plugin": "^0.8.0",
     "@eslint/js": "^10.0.1",
     "@eslint/json": "^2.1.0",
     "@eslint/markdown": "^8.0.3",
     "@stylistic/eslint-plugin": "^5.10.0",
     "eslint": "^10.10.0",
-    "eslint-plugin-eslint-plugin": "^6.5.0",
+    "eslint-plugin-constructors": "^1.0.3",
+    "eslint-plugin-eslint-plugin": "^7.6.2",
     "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-no-secrets": "^2.3.3",
+    "eslint-plugin-no-unsanitized": "^4.1.5",
     "eslint-plugin-promise": "^7.3.0",
     "eslint-plugin-regexp": "^3.3.0",
-    "globals": "^17.12.0"
-  },
-  "peerDependencies": {
-    "eslint": ">=9.0.0"
+    "eslint-plugin-security": "^4.0.1",
+    "globals": "^17.12.0",
+    "husky": "^9.1.7"
   }
 }

package/src/index.d.ts

@@ -0,0 +1,6 @@
+declare const plugin: {
+    rules: Record<string, unknown>
+    configs: { recommended: Record<string, unknown> }
+}
+
+export default plugin