eslint-plugin-greasemonkey 1.2.0 → 1.3.0

package/README.md

@@ -10,6 +10,8 @@ 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:
@@ -18,24 +20,32 @@ From your project root:
 npm i -D eslint-plugin-greasemonkey
 ```
 
+---
+
 ## Usage
 
-Add `greasemonkey` to your flat config:
+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: {
+        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/require-space-before-meta-key': 'error',
             'greasemonkey/require-user-js-filename': 'error',
             'greasemonkey/valid-field-values': ['error', { versionType: 'semver' }],
             'greasemonkey/valid-grants': ['error', { allowedGrants: [] }]
@@ -44,40 +54,54 @@ export default [
 ]
 ```
 
-**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'`):
+...or use a bundled config:
 
 ```js
+...
 import greasemonkey from 'eslint-plugin-greasemonkey'
 
 export default [
+    // other configs
     {
         files: ['**/*.user.js'],
-        ...greasemonkey.configs.recommended
+        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) | Aligns metadata values to the column after the longest key | ✅ | ✅ |
+| [`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`
+### `meta-spacing` (auto-fixable)
 
-> 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.
+> Aligns metadata values to the column after the longest key.
 
 #### Options
 
@@ -153,6 +177,43 @@ If you intentionally repeat single-value keys.
 
 ---
 
+### `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.
@@ -179,7 +240,7 @@ 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`).
+If you access the granted API through an alias or computed property rather than calling it directly.
 
 <div align="center">
 
@@ -213,7 +274,72 @@ GM_getResourceText('myCSS')
 
 #### When not to use it
 
-If you reference resources indirectly (e.g., building the resource name dynamically).
+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">
 
@@ -229,7 +355,7 @@ If you reference resources indirectly (e.g., building the resource name dynamica
 
 #### Options
 
-- `ignoreLanguages` (string[], default `[]`) – language codes to skip, e.g. `['fr', 'de']`
+- `ignoreLanguages` (default `[]`) – language codes to skip, e.g. `['fr', 'de']`
 
 #### Incorrect code
 
@@ -264,13 +390,48 @@ If you intentionally provide localized names without descriptions (or vice versa
 
 ---
 
+### `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`, `@namespace`, `@version`) and at least one `@match` or `@include`.
+> Requires essential metadata fields (`@name`, `@version` by default) and at least one `@match` or `@include`.
 
 #### Options
 
-- `fields` (string[], default `['name', 'namespace', 'version']`) – override the required field list
+- `fields` (default `['name', 'version']`) – override the required field list
 
 #### Incorrect code
 
@@ -285,7 +446,6 @@ If you intentionally provide localized names without descriptions (or vice versa
 ```js
 // ==UserScript==
 // @name My Script
-// @namespace example.com
 // @version 1.0.0
 // @match https://example.com/*
 // ==/UserScript==
@@ -303,17 +463,17 @@ If you use a subset of metadata fields that doesn't match the convention.
 
 ---
 
-### `require-user-js-filename`
+### `require-space-before-meta-key` (auto-fixable)
 
-> Requires that files containing a userscript metadata block end in `.user.js`.
+> Requires exactly one space between `//` and metadata keys.
 
 #### Incorrect code
 
 ```js
 // ==UserScript==
-// @name My Script
+//@name My Script
+//  @version 1.0.0
 // ==/UserScript==
-// (file: script.js)
 ```
 
 #### Correct code
@@ -321,12 +481,61 @@ If you use a subset of metadata fields that doesn't match the convention.
 ```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==
-// (file: script.user.js)
 ```
 
 #### 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">
@@ -343,7 +552,7 @@ If you intentionally name your userscripts something other than `*.user.js`.
 
 #### Options
 
-- `versionType` (`'semver'` | `'date'`, default `'semver'`) – version format to enforce
+- `versionType` (default `'semver'`) – version format to enforce (`'semver'`, `'date'`)
 
 #### Incorrect code
 
@@ -381,7 +590,7 @@ If you use a custom versioning scheme or URLs that aren't standard.
 
 #### Options
 
-- `allowedGrants` (string[], default `[]`) – additional `@grant` values to allow beyond the built-in list (covering Tampermonkey, Violentmonkey and ScriptCat)
+- `allowedGrants` (default `[]`) – additional `@grant` values to allow beyond the built-in list (covering Tampermonkey, Violentmonkey and ScriptCat)
 
 #### Incorrect code
 
@@ -405,7 +614,7 @@ If you use a custom versioning scheme or URLs that aren't standard.
 
 #### 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.
+If you don't want `@grant` validation at all. For individual uncovered grants, prefer whitelisting via `allowedGrants` over disabling the rule.
 
 <div align="center">
 
@@ -433,15 +642,15 @@ If you don't want `@grant` validation at all. For individual unlisted grants, pr
 [![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>
+## License
 
-<summary>
+[<img height=62 src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-greasemonkey/9e820e5d51/assets/images/logos/mit-license/red-pixelated.png">][epg-license] 
 
-Copyright © 2026 [Adam Lui][adamlui-cb] under the [MIT license](./docs/LICENSE.md).
+<details>
 
-</summary><br>
+<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:
 
@@ -451,6 +660,8 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 </details>
 
+---
+
 ## Related
 
  <!-- eslint-plugin-constructors -->
@@ -463,7 +674,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 > [<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]
+> [**Install**][epc-install] / [Readme][epc-readme] / [Supported rules][epc-rules]
 
 </details>
 
@@ -474,19 +685,19 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 <!-- 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">
 
+<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-cb]: https://codeberg.org/adamlui
 [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-greasemonkey",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
   "type": "module",
   "engines": {
@@ -40,7 +40,7 @@
     "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": "node demo/run.js",
     "bump:patch": "bash utils/bump.sh patch",
     "bump:minor": "bash utils/bump.sh minor",
     "bump:feat": "npm run bump:minor",
@@ -69,7 +69,7 @@
     "@eslint/markdown": "^8.0.3",
     "@stylistic/eslint-plugin": "^5.10.0",
     "eslint": "^10.10.0",
-    "eslint-plugin-constructors": "^1.0.3",
+    "eslint-plugin-constructors": "^1.1.1",
     "eslint-plugin-eslint-plugin": "^7.6.2",
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-n": "^18.3.0",

package/src/apis.js

@@ -0,0 +1,20 @@
+export const gmLegacyAPIs = new Set([ /* eslint-disable no-secrets/no-secrets */
+    'GM_addElement', 'GM_addStyle', 'GM_addValueChangeListener', 'GM_deleteValue', 'GM_download',
+    'GM_getResourceText', 'GM_getResourceURL', 'GM_getTab', 'GM_getTabs', 'GM_getValue', 'GM_getValues',
+    'GM_info', 'GM_listValues', 'GM_log', 'GM_notification', 'GM_openInTab', 'GM_registerMenuCommand',
+    'GM_removeValueChangeListener', 'GM_saveTab', 'GM_setClipboard', 'GM_setValue', 'GM_setValues',
+    'GM_unregisterMenuCommand', 'GM_webRequest', 'GM_xmlhttpRequest'
+]) /* eslint-enable no-secrets/no-secrets */
+
+export const gmModernAPIs = new Set([
+    'GM.addElement', 'GM.addStyle', 'GM.addValueChangeListener', 'GM.deleteValue', 'GM.download',
+    'GM.getResourceText', 'GM.getResourceUrl', 'GM.getValue', 'GM.info', 'GM.listValues', 'GM.log',
+    'GM.notification', 'GM.openInTab', 'GM.registerMenuCommand', 'GM.removeValueChangeListener',
+    'GM.setClipboard', 'GM.setValue', 'GM.unregisterMenuCommand', 'GM.xmlHttpRequest'
+])
+
+export const scAPIs = new Set([
+    'CAT.agent.conversation', 'CAT.agent.dom', 'CAT.agent.mcp', 'CAT.agent.model',
+    'CAT.agent.opfs', 'CAT.agent.skills', 'CAT.agent.task',
+    'CAT_fileStorage', 'CAT_scriptLoaded', 'CAT_userConfig'
+])

package/src/index.js

@@ -1,9 +1,15 @@
 import metaSpacing from './rules/meta-spacing.js'
 import noDuplicateKeys from './rules/no-duplicate-keys.js'
+import noMissingGrants from './rules/no-missing-grants.js'
 import noUnusedGrants from './rules/no-unused-grants.js'
 import noUnusedResources from './rules/no-unused-resources.js'
+import preferMatch from './rules/prefer-match.js'
+import requireHomepagePair from './rules/require-homepage-pair.js'
 import requireMatchingLocalizedFields from './rules/require-matching-localized-fields.js'
+import requireMetaNewline from './rules/require-meta-newline.js'
 import requireRequiredFields from './rules/require-required-fields.js'
+import requireSpaceBeforeMetaKey from './rules/require-space-before-meta-key.js'
+import requireUpdateDownloadPair from './rules/require-update-download-pair.js'
 import requireUserJsFilename from './rules/require-user-js-filename.js'
 import validFieldValues from './rules/valid-field-values.js'
 import validGrants from './rules/valid-grants.js'
@@ -12,10 +18,16 @@ const plugin = {
     rules: {
         'meta-spacing': metaSpacing,
         'no-duplicate-keys': noDuplicateKeys,
+        'no-missing-grants': noMissingGrants,
         'no-unused-grants': noUnusedGrants,
         'no-unused-resources': noUnusedResources,
+        'prefer-match': preferMatch,
+        'require-homepage-pair': requireHomepagePair,
         'require-matching-localized-fields': requireMatchingLocalizedFields,
+        'require-meta-newline': requireMetaNewline,
         'require-required-fields': requireRequiredFields,
+        'require-space-before-meta-key': requireSpaceBeforeMetaKey,
+        'require-update-download-pair': requireUpdateDownloadPair,
         'require-user-js-filename': requireUserJsFilename,
         'valid-field-values': validFieldValues,
         'valid-grants': validGrants
@@ -28,10 +40,34 @@ plugin.configs = {
         rules: {
             'greasemonkey/meta-spacing': 'error',
             '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/require-space-before-meta-key': 'error',
+            'greasemonkey/require-user-js-filename': 'error',
+            'greasemonkey/valid-field-values': 'error',
+            'greasemonkey/valid-grants': 'error'
+        }
+    },
+    strict: {
+        plugins: { greasemonkey: plugin },
+        rules: {
+            'greasemonkey/meta-spacing': 'error',
+            '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-homepage-pair': 'error',
+            'greasemonkey/require-matching-localized-fields': 'error',
+            'greasemonkey/require-meta-newline': 'error',
+            'greasemonkey/require-required-fields': 'error',
+            'greasemonkey/require-space-before-meta-key': 'error',
+            'greasemonkey/require-update-download-pair': 'error',
             'greasemonkey/require-user-js-filename': 'error',
             'greasemonkey/valid-field-values': 'error',
             'greasemonkey/valid-grants': 'error'
@@ -39,4 +75,4 @@ plugin.configs = {
     }
 }
 
-export default plugin
+export { plugin as default, plugin as greasemonkey }

package/src/rules/no-duplicate-keys.js

@@ -1,6 +1,6 @@
 import { extractMetadata } from '../utils.js'
 
-const MULTI_VALUE_KEYS = new Set([
+const multiValKeys = new Set([
     'compatible', 'connect', 'description', 'exclude', 'exclude-match', 'grant',
     'homepageURL', 'include', 'license', 'match', 'require', 'resource', 'supportURL'
 ])
@@ -24,7 +24,7 @@ export default {
                       seen = new Set()
                 for (const entry of metaEntries) {
                     const baseKey = entry.key.split(':')[0]
-                    if (!entry.key.includes(':') && MULTI_VALUE_KEYS.has(baseKey)) continue
+                    if (!entry.key.includes(':') && multiValKeys.has(baseKey)) continue
                     if (seen.has(entry.key))
                         context.report({ node: entry.comment, messageId: 'dupeKey', data: { key: entry.key }})
                     else seen.add(entry.key)

package/src/rules/no-missing-grants.js

@@ -0,0 +1,51 @@
+import { extractMetadata } from '../utils.js'
+import { gmLegacyAPIs, gmModernAPIs, scAPIs } from '../apis.js'
+
+const apis = new Set([...gmLegacyAPIs, ...gmModernAPIs, ...scAPIs]),
+      grantlessAPIs = new Set(['GM_info', 'GM.info']) // always available, no grant required
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow API calls without a matching @grant',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: { missingGrant: 'Missing @grant: "{{api}}"' }
+    },
+
+    create(context) {
+        const usedAPIs = new Map()
+        function record(name, node) { if (apis.has(name) && !usedAPIs.has(name)) usedAPIs.set(name, node) }
+        return {
+            Identifier(node) { record(node.name, node) },
+            MemberExpression(node) {
+                const path = []
+                let current = node
+                while (current.type == 'MemberExpression') {
+                    if (current.property.type != 'Identifier') return
+                    path.unshift(current.property.name)
+                    current = current.object
+                }
+                if (current.type == 'Identifier') {
+                    path.unshift(current.name)
+                    record(path.join('.'), node)
+                }
+            },
+            'Program:exit'() {
+                if (!usedAPIs.size) return
+                const declared = new Set(
+                    extractMetadata(context.sourceCode)
+                        .filter(entry => entry.key == 'grant')
+                        .map(entry => entry.value.trim())
+                )
+                for (const [api, node] of usedAPIs) {
+                    if (grantlessAPIs.has(api) || declared.has(api)) continue
+                    context.report({ node, messageId: 'missingGrant', data: { api }})
+                }
+            }
+        }
+    }
+}

package/src/rules/no-unused-grants.js

@@ -13,18 +13,30 @@ export default {
     },
 
     create(context) {
-        const usedIdentifiers = new Set()
+        const usedGrants = new Set()
         return {
-            Identifier(node) { usedIdentifiers.add(node.name) },
+            Identifier(node) { usedGrants.add(node.name) },
+            MemberExpression(node) {
+                const path = [] ; let current = node
+                while (current.type == 'MemberExpression') {
+                    if (current.property.type != 'Identifier') return
+                    path.unshift(current.property.name)
+                    current = current.object
+                }
+                if (current.type == 'Identifier') {
+                    path.unshift(current.name)
+                    usedGrants.add(path.join('.'))
+                }
+            },
             'Program:exit'() {
                 const sourceCode = context.sourceCode,
                       metaEntries = extractMetadata(sourceCode),
-                      grants = metaEntries.filter(e => e.key == 'grant')
+                      grants = metaEntries.filter(entry => entry.key == 'grant')
                 if (!grants.length) return
                 for (const grant of grants) {
                     const grantName = grant.value.trim()
                     if (['none', 'unsafeWindow'].includes(grantName)) continue
-                    if (!usedIdentifiers.has(grantName))
+                    if (!usedGrants.has(grantName))
                         context.report({ node: grant.comment, messageId: 'unusedGrant', data: { grant: grantName }})
                 }
             }

package/src/rules/no-unused-resources.js

@@ -1,6 +1,7 @@
-import { extractMetadata } from '../utils.js'
+import { extractMetadata, resolveTemplate } from '../utils.js'
 
-const re = { resourceGetter: /GM_getResource(?:Text|URL)\s*\(\s*['"]([^'"]+)['"]\s*\)/g, whitespace: /\s+/ }
+const resourceGetterNames = new Set(['GM_getResourceText', 'GM_getResourceURL']),
+      re = { specialChars: /[.*+?^${}()|[\]\\]/g, whitespace: /\s+/ }
 
 export default {
     meta: {
@@ -15,20 +16,30 @@ export default {
     },
 
     create(context) {
+        const usedResources = new Set(),
+              usedPatterns = []
         return {
-            Program() {
-                const sourceCode = context.sourceCode,
-                      metaEntries = extractMetadata(sourceCode),
-                      resources = metaEntries.filter(e => e.key == 'resource')
+            CallExpression(node) {
+                if (!resourceGetterNames.has(node.callee.name)) return
+                const arg = node.arguments[0]
+                if (arg?.type == 'Literal' && typeof arg.value == 'string')
+                    usedResources.add(arg.value)
+                else if (arg?.type == 'TemplateLiteral') {
+                    const resolved = resolveTemplate(arg)
+                    if (resolved)
+                        for (const name of resolved) usedResources.add(name)
+                    else usedPatterns.push(new RegExp( // eslint-disable-line security/detect-non-literal-regexp
+                        `^${arg.quasis.map(quasi => quasi.value.raw.replace(re.specialChars, '\\$&')).join('.*')}$`))
+                }
+            },
+            'Program:exit'() {
+                const metaEntries = extractMetadata(context.sourceCode),
+                      resources = metaEntries.filter(entry => entry.key == 'resource')
                 if (!resources.length) return
-                const text = sourceCode.getText(),
-                      usedResources = new Set()
-                let match
-                while ((match = re.resourceGetter.exec(text)) !== null) usedResources.add(match[1])
                 for (const res of resources) {
-                    const name = res.value.split(re.whitespace)[0]
-                    if (!usedResources.has(name))
-                        context.report({ node: res.comment, messageId: 'unusedResource', data: { name }})
+                    const name = res.value.trim().split(re.whitespace)[0]
+                    if (usedResources.has(name) || usedPatterns.some(patt => patt.test(name))) continue
+                    context.report({ node: res.comment, messageId: 'unusedResource', data: { name }})
                 }
             }
         }

package/src/rules/prefer-match.js

@@ -0,0 +1,24 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Prefer @match over @include (see https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline)',
+            category: 'Best Practices',
+            recommended: true
+        },
+        schema: [],
+        messages: { preferMatch: 'Use @match instead of @include (deprecated in Chrome MV3)' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                for (const entry of extractMetadata(context.sourceCode))
+                    if (entry.key == 'include')
+                        context.report({ node: entry.comment, messageId: 'preferMatch' })
+            }
+        }
+    }
+}

package/src/rules/require-homepage-pair.js

@@ -0,0 +1,43 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require @homepage and @homepageURL to be used together',
+            category: 'Best Practices',
+            recommended: false
+        },
+        fixable: 'code',
+        schema: [],
+        messages: { missingPair: 'Missing @{{missing}} (required when @{{present}} is used)' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const metaEntries = extractMetadata(context.sourceCode),
+                      homepageEntry = metaEntries.find(entry => entry.key == 'homepage'),
+                      homepageURLEntry = metaEntries.find(entry => entry.key == 'homepageURL')
+                if (homepageEntry && !homepageURLEntry)
+                    context.report({
+                        node: homepageEntry.comment, messageId: 'missingPair',
+                        data: { missing: 'homepageURL', present: 'homepage' },
+                        fix(fixer) {
+                            return fixer.insertTextAfter(homepageEntry.comment,
+                                `\n// @homepageURL ${homepageEntry.value}`)
+                        }
+                    })
+                else if (homepageURLEntry && !homepageEntry)
+                    context.report({
+                        node: homepageURLEntry.comment, messageId: 'missingPair',
+                        data: { missing: 'homepage', present: 'homepageURL' },
+                        fix(fixer) {
+                            return fixer.insertTextAfter(homepageURLEntry.comment,
+                                `\n// @homepage ${homepageURLEntry.value}`)
+                        }
+                    })
+            }
+        }
+    }
+}

package/src/rules/require-matching-localized-fields.js

@@ -14,7 +14,7 @@ export default {
                 ignoreLanguages: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Language codes to ignore (e.g., ["fr", "de"])'
+                    description: 'Language codes to ignore (e.g. ["fr", "de"])'
                 }
             },
             additionalProperties: false
@@ -29,10 +29,10 @@ export default {
         return {
             Program() {
                 const metaEntries = extractMetadata(context.sourceCode),
-                      nameEntries = metaEntries.filter(e => e.key.startsWith('name:')),
-                      descEntries = metaEntries.filter(e => e.key.startsWith('description:')),
-                      nameLangs = new Set(nameEntries.map(e => e.key.split(':')[1])),
-                      descLangs = new Set(descEntries.map(e => e.key.split(':')[1]))
+                      nameEntries = metaEntries.filter(entry => entry.key.startsWith('name:')),
+                      descEntries = metaEntries.filter(entry => entry.key.startsWith('description:')),
+                      nameLangs = new Set(nameEntries.map(entry => entry.key.split(':')[1])),
+                      descLangs = new Set(descEntries.map(entry => entry.key.split(':')[1]))
                 for (const lang of nameLangs)
                     if (!ignoreLanguages.includes(lang) && !descLangs.has(lang))
                         context.report({
@@ -43,7 +43,7 @@ export default {
                 for (const lang of descLangs)
                     if (!ignoreLanguages.includes(lang) && !nameLangs.has(lang))
                         context.report({
-                            node: descEntries.find(e => e.key == `description:${lang}`).comment,
+                            node: descEntries.find(entry => entry.key == `description:${lang}`).comment,
                             messageId: 'missingPair',
                             data: { missing: `name:${lang}`, present: `description:${lang}` }
                         })

package/src/rules/require-meta-newline.js

@@ -0,0 +1,36 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'layout',
+        docs: {
+            description: 'Require a newline between the metadata and code',
+            category: 'Stylistic Issues',
+            recommended: true
+        },
+        fixable: 'whitespace',
+        schema: [],
+        messages: { missingNewline: 'Missing blank line after metadata block' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode,
+                      comments = sourceCode.getAllComments(),
+                      metaEntries = extractMetadata(sourceCode)
+                if (!metaEntries.length) return
+                const closingComment = comments.find(comment => comment.value.trim() == '==/UserScript==')
+                if (!closingComment) return
+                const tokenAfter = sourceCode.getTokenAfter(closingComment)
+                if (!tokenAfter) return
+                if (tokenAfter.loc.start.line - closingComment.loc.end.line < 2)
+                    context.report({
+                        node: closingComment,
+                        messageId: 'missingNewline',
+                        fix(fixer) { return fixer.insertTextAfter(closingComment, '\n') }
+                    })
+            }
+        }
+    }
+}

package/src/rules/require-required-fields.js

@@ -14,7 +14,7 @@ export default {
                 fields: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Required metadata fields (default: name, namespace, version)'
+                    description: 'Required metadata fields (default: name, version)'
                 }
             },
             additionalProperties: false
@@ -25,11 +25,11 @@ export default {
 
     create(context) {
         const options = context.options[0] || {},
-              requiredFields = options.fields || ['name', 'namespace', 'version']
+              requiredFields = options.fields || ['name', 'version']
         return {
             Program(node) {
                 const metaEntries = extractMetadata(context.sourceCode),
-                      keys = new Set(metaEntries.map(e => e.key))
+                      keys = new Set(metaEntries.map(entry => entry.key))
                 for (const field of requiredFields)
                     if (!keys.has(field))
                         context.report({ node, messageId: 'missingField', data: { field }})

package/src/rules/require-space-before-meta-key.js

@@ -0,0 +1,39 @@
+import { extractMetadata } from '../utils.js'
+
+const re = { leadingWhitespace: /^\s*/ }
+
+export default {
+    meta: {
+        type: 'layout',
+        docs: {
+            description: 'Require exactly one space between // and metadata keys',
+            category: 'Stylistic Issues',
+            recommended: true
+        },
+        fixable: 'whitespace',
+        schema: [],
+        messages: { badPrefix: '`{{actual}}` should be `// @{{key}}`' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode,
+                      metaEntries = extractMetadata(sourceCode)
+                for (const entry of metaEntries) {
+                    const commentText = sourceCode.getText(entry.comment),
+                          afterSlashes = commentText.slice(2)
+                    if (afterSlashes.startsWith(' @')) continue
+                    const rest = afterSlashes.replace(re.leadingWhitespace, ''),
+                          keyIdx = commentText.indexOf(`@${entry.key}`),
+                          actual = commentText.slice(0, keyIdx +1 + entry.key.length),
+                          fixedText = `// ${rest}`
+                    context.report({
+                        node: entry.comment, messageId: 'badPrefix', data: { actual, key: entry.key },
+                        fix(fixer) { return fixer.replaceText(entry.comment, fixedText) }
+                    })
+                }
+            }
+        }
+    }
+}

package/src/rules/require-update-download-pair.js

@@ -0,0 +1,32 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require @updateURL and @downloadURL to be used together',
+            category: 'Best Practices',
+            recommended: false
+        },
+        schema: [],
+        messages: { missingPair: 'Missing @{{missing}} (required when @{{present}} is used)' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const metaEntries = extractMetadata(context.sourceCode),
+                      updateEntry = metaEntries.find(entry => entry.key == 'updateURL'),
+                      downloadEntry = metaEntries.find(entry => entry.key == 'downloadURL')
+                if (updateEntry && !downloadEntry)
+                    context.report({
+                        node: updateEntry.comment, messageId: 'missingPair',
+                        data: { missing: 'downloadURL', present: 'updateURL' }})
+                else if (downloadEntry && !updateEntry)
+                    context.report({
+                        node: downloadEntry.comment, messageId: 'missingPair',
+                        data: { missing: 'updateURL', present: 'downloadURL' }})
+            }
+        }
+    }
+}

package/src/rules/require-user-js-filename.js

@@ -9,7 +9,7 @@ export default {
             recommended: true
         },
         schema: [],
-        messages: { requireUserJs: 'Userscript filename should end in ".user.js"' }
+        messages: { requireUserJS: 'Userscript filename should end in ".user.js"' }
     },
 
     create(context) {
@@ -18,7 +18,7 @@ export default {
                 const metaEntries = extractMetadata(context.sourceCode)
                 if (!metaEntries.length) return
                 if (!context.filename.endsWith('.user.js'))
-                    context.report({ node, messageId: 'requireUserJs' })
+                    context.report({ node, messageId: 'requireUserJS' })
             }
         }
     }

package/src/rules/valid-field-values.js

@@ -3,10 +3,11 @@ import { extractMetadata } from '../utils.js'
 const re = { /* eslint-disable security/detect-unsafe-regex */
     semVer: /^\d+\.\d+\.\d+(?:-[\da-z.-]+)?(?:\+[\da-z.-]+)?$/i,
     dateVer: /^\d{4}\.(?:0?[1-9]|1[0-2])\.(?:0?[1-9]|[12]\d|3[01])(?:\.\d+)?$/,
-    urlSuffix: /url$/i,
     whitespace: /\s+/
 } /* eslint-enable security/detect-unsafe-regex */
 
+const urlKeys = ['homepage', 'icon', 'icon64', 'require', 'source', 'website']
+
 export default {
     meta: {
         type: 'problem',
@@ -42,36 +43,33 @@ export default {
     create(context) {
         const options = context.options[0] || {},
               versionType = options.versionType || 'semver',
-              allowedGrants = options.allowedGrants || []
-        const example = versionType == 'semver' ? '1.2.3' : 'YYYY.M.D or YYYY.MM.DD'
+              allowedGrants = options.allowedGrants || [],
+              example = versionType == 'semver' ? '1.2.3' : 'YYYY.M.D or YYYY.MM.DD'
         return {
             Program() {
                 const metaEntries = extractMetadata(context.sourceCode)
                 for (const entry of metaEntries) {
-                    if (entry.key == 'version') {
-                        const isValid = versionType == 'semver' ? re.semVer.test(entry.value)
-                                      : versionType == 'date' ? re.dateVer.test(entry.value)
-                                      : false
-                        if (!isValid)
-                            context.report({
-                                node: entry.comment, messageId: 'invalidVersion', data: { versionType, example }})
-                    }
-                    if (['homepage', 'icon', 'icon64', 'require', 'source', 'website'].includes(entry.key)
-                        || re.urlSuffix.test(entry.key)
-                    )
-                        try { new URL(entry.value) }
+                    if (entry.key == 'grant' && allowedGrants.length && !allowedGrants.includes(entry.value))
+                        context.report({ node: entry.comment, messageId: 'invalidGrant', data: { grant: entry.value }})
+                    else if (entry.key == 'resource') {
+                        const url = entry.value.trim().split(re.whitespace)[1]
+                        if (url) try { new URL(url) }
                         catch {
                             context.report({ node: entry.comment, messageId: 'invalidURL', data: { field: entry.key }})
                         }
-                    if (entry.key == 'resource') {
-                        const url = entry.value.trim().split(re.whitespace)[1]
-                        if (url) try { new URL(url) }
+                    } else if (urlKeys.includes(entry.key) || entry.key.toLowerCase().endsWith('url'))
+                        try { new URL(entry.value) }
                         catch {
                             context.report({ node: entry.comment, messageId: 'invalidURL', data: { field: entry.key }})
                         }
+                    else if (entry.key == 'version') {
+                        const isValid = versionType == 'semver' ? re.semVer.test(entry.value)
+                                      : versionType == 'date' ? re.dateVer.test(entry.value)
+                                      : false
+                        if (!isValid)
+                            context.report({
+                                node: entry.comment, messageId: 'invalidVersion', data: { versionType, example }})
                     }
-                    if (entry.key == 'grant' && allowedGrants.length && !allowedGrants.includes(entry.value))
-                        context.report({ node: entry.comment, messageId: 'invalidGrant', data: { grant: entry.value }})
                 }
             }
         }

package/src/rules/valid-grants.js

@@ -1,31 +1,11 @@
 import { extractMetadata } from '../utils.js'
-
-const gm_legacy_apis = new Set([ /* eslint-disable no-secrets/no-secrets */
-    'GM_addElement', 'GM_addStyle', 'GM_addValueChangeListener', 'GM_deleteValue', 'GM_download',
-    'GM_getResourceText', 'GM_getResourceURL', 'GM_getTab', 'GM_getTabs', 'GM_getValue', 'GM_getValues',
-    'GM_info', 'GM_listValues', 'GM_log', 'GM_notification', 'GM_openInTab', 'GM_registerMenuCommand',
-    'GM_removeValueChangeListener', 'GM_saveTab', 'GM_setClipboard', 'GM_setValue', 'GM_setValues',
-    'GM_unregisterMenuCommand', 'GM_webRequest', 'GM_xmlhttpRequest'
-]) /* eslint-enable no-secrets/no-secrets */
-
-const gm_modern_apis = new Set([
-    'GM.addElement', 'GM.addStyle', 'GM.addValueChangeListener', 'GM.deleteValue', 'GM.download',
-    'GM.getResourceText', 'GM.getResourceUrl', 'GM.getValue', 'GM.info', 'GM.listValues', 'GM.log',
-    'GM.notification', 'GM.openInTab', 'GM.registerMenuCommand', 'GM.removeValueChangeListener',
-    'GM.setClipboard', 'GM.setValue', 'GM.unregisterMenuCommand', 'GM.xmlHttpRequest'
-])
-
-const sc_apis = new Set([
-    'CAT.agent.conversation', 'CAT.agent.dom', 'CAT.agent.mcp', 'CAT.agent.model',
-    'CAT.agent.opfs', 'CAT.agent.skills', 'CAT.agent.task',
-    'CAT_fileStorage', 'CAT_scriptLoaded', 'CAT_userConfig'
-])
+import { gmLegacyAPIs, gmModernAPIs, scAPIs } from '../apis.js'
 
 const specialGrants = new Set([
     'none', 'unsafeWindow', 'window.close', 'window.focus', 'window.onurlchange'
 ])
 
-const grants = new Set([...gm_legacy_apis, ...gm_modern_apis, ...sc_apis, ...specialGrants]),
+const grants = new Set([...gmLegacyAPIs, ...gmModernAPIs, ...scAPIs, ...specialGrants]),
       sortedGrants = new Map(Array.from(grants, grant => [grant.toLowerCase(), grant]))
 
 export default {
@@ -60,18 +40,15 @@ export default {
         return {
             Program() {
                 const metaEntries = extractMetadata(context.sourceCode),
-                      grantEntries = metaEntries.filter(e => e.key == 'grant')
+                      grantEntries = metaEntries.filter(entry => entry.key == 'grant')
                 for (const grant of grantEntries) {
                     const grantName = grant.value.trim()
                     if (grants.has(grantName) || allowedGrants.includes(grantName)) continue
                     const suggestion = sortedGrants.get(grantName.toLowerCase())
-                    if (suggestion)
-                        context.report({
-                            node: grant.comment, messageId: 'wrongCase',
-                            data: { grant: grantName, suggestion }})
-                    else
-                        context.report({
-                            node: grant.comment, messageId: 'invalidGrant', data: { grant: grantName }})
+                    context.report(suggestion
+                        ? { node: grant.comment, messageId: 'wrongCase', data: { grant: grantName, suggestion }}
+                        : { node: grant.comment, messageId: 'invalidGrant', data: { grant: grantName }}
+                    )
                 }
             }
         }

package/src/utils.js

@@ -4,7 +4,7 @@ export function extractMetadata(sourceCode) {
     let inMetaBlock
     for (const comment of comments) {
         const text = comment.value.trim()
-        if (!inMetaBlock && text == '==UserScript==') { inMetaBlock = true ; continue }
+        if (!inMetaBlock && text == '==UserScript==') inMetaBlock = true
         else if (inMetaBlock && text == '==/UserScript==') break
         else if (inMetaBlock && text.startsWith('@')) { // capture entry
             const spaceIdx = text.indexOf(' ')
@@ -17,3 +17,22 @@ export function extractMetadata(sourceCode) {
     }
     return metaEntries
 }
+
+export function resolveTemplate(node) {
+    if (node.type == 'ConditionalExpression') {
+        const branches = [node.consequent, node.alternate].map(resolveTemplate)
+        return branches.every(Boolean) ? branches.flat() : null
+    } else if (node.type == 'Literal' && ['number', 'string'].includes(typeof node.value))
+        return [String(node.value)]
+    else if (node.type == 'TemplateLiteral') // build every combo of quasis + resolved expressions
+        return node.quasis.reduce((combos, quasi, idx) => {
+            if (!combos) return null
+            const withQuasi = combos.map(combo => combo + quasi.value.raw)
+            if (idx >= node.expressions.length) return withQuasi
+            const vals = // eslint-disable-next-line security/detect-object-injection -- AST array indices are bounded
+                resolveTemplate(node.expressions[idx])
+            return vals ? withQuasi.flatMap(combo => vals.map(val => combo + val)) : null
+        }, [''])
+    else
+        return null
+}