eslint-plugin-greasemonkey 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# 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).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "eslint-plugin-greasemonkey",
+  "version": "1.0.0",
+  "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
+  "type": "module",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "author": {
+    "name": "Adam Lui",
+    "email": "adam@kudoai.org",
+    "url": "https://codeberg.org/adamlui"
+  },
+  "homepage": "https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#readme",
+  "license": "MIT",
+  "main": "src/index.js",
+  "files": ["src"],
+  "scripts": {
+    "prepare": "husky",
+    "lint": "eslint . --cache",
+    "lint:all": "eslint .",
+    "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"
+  },
+  "keywords": [
+    "greasemonkey",
+    "tampermonkey",
+    "userscript",
+    "eslint",
+    "eslint-plugin",
+    "metadata"
+  ],
+  "devDependencies": {
+    "@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-import-x": "^4.17.1",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-regexp": "^3.3.0",
+    "globals": "^17.12.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,33 @@
+import metaSpacing from './rules/meta-spacing.js'
+import noUnusedGrants from './rules/no-unused-grants.js'
+import noUnusedResources from './rules/no-unused-resources.js'
+import requireMatchingLocalizedFields from './rules/require-matching-localized-fields.js'
+import requireRequiredFields from './rules/require-required-fields.js'
+import validFieldValues from './rules/valid-field-values.js'
+
+const plugin = {
+    rules: {
+        'meta-spacing': metaSpacing,
+        'require-matching-localized-fields': requireMatchingLocalizedFields,
+        'require-required-fields': requireRequiredFields,
+        'valid-field-values': validFieldValues,
+        'no-unused-resources': noUnusedResources,
+        'no-unused-grants': noUnusedGrants
+    }
+}
+
+plugin.configs = {
+    recommended: {
+        plugins: { greasemonkey: plugin },
+        rules: {
+            'greasemonkey/meta-spacing': 'error',
+            'greasemonkey/require-matching-localized-fields': 'error',
+            'greasemonkey/require-required-fields': 'error',
+            'greasemonkey/valid-field-values': 'error',
+            'greasemonkey/no-unused-resources': 'error',
+            'greasemonkey/no-unused-grants': 'error'
+        }
+    }
+}
+
+export default plugin

package/src/rules/meta-spacing.js

@@ -0,0 +1,47 @@
+import { extractMetadata } from '../utils.js'
+
+const reLeadingWhitespace = /^\s*/
+
+export default {
+    meta: {
+        type: 'layout',
+        docs: {
+            description: 'Align metadata values to the column after the longest key',
+            category: 'Stylistic Issues',
+            recommended: true
+        },
+        fixable: 'whitespace',
+        schema: [{ type: 'number', description: 'Minimum spaces after the longest key (default 3)' }],
+        defaultOptions: [3],
+        messages: { misaligned: 'Metadata values should be aligned at column {{column}}' }
+    },
+
+    create(context) {
+        const minSpaces = context.options[0] ?? 3
+        return {
+            Program() {
+                const sourceCode = context.sourceCode,
+                      metaEntries = extractMetadata(sourceCode)
+                if (!metaEntries.length) return
+                const longestKey = metaEntries.reduce((max, entry) => Math.max(max, entry.key.length), 0),
+                      targetColumn = longestKey + minSpaces +4
+                for (const entry of metaEntries) {
+                    const keyLen = entry.key.length,
+                          commentText = sourceCode.getText(entry.comment),
+                          actualSpaces = commentText.split(entry.key)[1].match(reLeadingWhitespace)[0].length,
+                          desiredSpaces = targetColumn - keyLen -4
+                    if (actualSpaces != desiredSpaces)
+                        context.report({
+                            node: entry.comment, messageId: 'misaligned', data: { column: targetColumn },
+                            fix(fixer) {
+                                const keyIdx = commentText.indexOf(entry.key) + entry.key.length,
+                                      rest = commentText.slice(keyIdx).replace(reLeadingWhitespace, ''),
+                                      fixedText = commentText.slice(0, keyIdx) + ' '.repeat(desiredSpaces) + rest
+                                return fixer.replaceText(entry.comment, fixedText)
+                            }
+                        })
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,36 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Flag @grant entries whose APIs are never used',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            unusedGrant: 'Unused @grant: "{{grant}}". If used indirectly,'
+                       + ' add // eslint-disable-line greasemonkey/no-unused-grants'
+        }
+    },
+
+    create(context) {
+        const usedIdentifiers = new Set()
+        return {
+            Identifier(node) { usedIdentifiers.add(node.name) },
+            'Program:exit'() {
+                const sourceCode = context.sourceCode,
+                      metaEntries = extractMetadata(sourceCode),
+                      grants = metaEntries.filter(e => e.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))
+                        context.report({ node: grant.comment, messageId: 'unusedGrant', data: { grant: grantName }})
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+import { extractMetadata } from '../utils.js'
+
+const reWhitespace = /\s+/
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Flag @resource entries that are never referenced directly',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            unusedResource: 'Unused @resource: "{{name}}". If used indirectly,'
+                          + ' add // eslint-disable-line greasemonkey/no-unused-resources'
+        }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode,
+                      metaEntries = extractMetadata(sourceCode),
+                      resources = metaEntries.filter(e => e.key == 'resource')
+                if (!resources.length) return
+                const text = sourceCode.getText(),
+                      usedResources = new Set(),
+                      regex = /GM_getResource(?:Text|URL)\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+                let match
+                while ((match = regex.exec(text)) !== null) usedResources.add(match[1])
+                for (const res of resources) {
+                    const name = res.value.split(reWhitespace)[0]
+                    if (!usedResources.has(name))
+                        context.report({ node: res.comment, messageId: 'unusedResource', data: { name }})
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,53 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require matching localized name and description fields',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                ignoreLanguages: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Language codes to ignore (e.g., ["fr", "de"])'
+                }
+            },
+            additionalProperties: false
+        }],
+        defaultOptions: [{}],
+        messages: { missingPair: 'Missing matching @{{missing}} for @{{present}}' }
+    },
+
+    create(context) {
+        const options = context.options[0] || {},
+              ignoreLanguages = options.ignoreLanguages || []
+        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]))
+                for (const lang of nameLangs)
+                    if (!ignoreLanguages.includes(lang) && !descLangs.has(lang))
+                        context.report({
+                            node: nameEntries.find(entry => entry.key == `name:${lang}`).comment,
+                            messageId: 'missingPair',
+                            data: { missing: `description:${lang}`, present: `name:${lang}` }
+                        })
+                for (const lang of descLangs)
+                    if (!ignoreLanguages.includes(lang) && !nameLangs.has(lang))
+                        context.report({
+                            node: descEntries.find(e => e.key == `description:${lang}`).comment,
+                            messageId: 'missingPair',
+                            data: { missing: `name:${lang}`, present: `description:${lang}` }
+                        })
+            }
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+import { extractMetadata } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require essential metadata fields',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Required metadata fields (default: name, namespace, version)'
+                }
+            },
+            additionalProperties: false
+        }],
+        defaultOptions: [{}],
+        messages: { missingField: 'Missing required metadata field: @{{field}}' }
+    },
+
+    create(context) {
+        const options = context.options[0] || {},
+              requiredFields = options.fields || ['name', 'namespace', 'version']
+        return {
+            Program(node) {
+                const metaEntries = extractMetadata(context.sourceCode),
+                      keys = new Set(metaEntries.map(e => e.key))
+                for (const field of requiredFields)
+                    if (!keys.has(field))
+                        context.report({ node, messageId: 'missingField', data: { field }})
+                if (!metaEntries.some(entry => ['include', 'match'].includes(entry.key)))
+                    context.report({ node, messageId: 'missingField', data: { field: 'match or include' }})
+            }
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+import { extractMetadata } from '../utils.js'
+
+const RE_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate values of metadata fields',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                reVer: {
+                    type: 'string',
+                    description: 'Regular expression pattern for @version validation (default: ^\\d+\\.\\d+\\.\\d+$)'
+                },
+                allowedGrants: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Allowed @grant values to check against; if empty, no grant validation'
+                }
+            },
+            additionalProperties: false
+        }],
+        defaultOptions: [{}],
+        messages: {
+            invalidVersion: 'Invalid @version: must match pattern "{{pattern}}"',
+            invalidURL: 'Invalid URL for @{{field}}',
+            invalidGrant: 'Unknown @grant: "{{grant}}"'
+        }
+    },
+
+    create(context) {
+        const options = context.options[0] || {},
+              reVer = options.reVer || '^\\d+\\.\\d+\\.\\d+$',
+              allowedGrants = options.allowedGrants || []
+        return {
+            Program() {
+                const metaEntries = extractMetadata(context.sourceCode)
+                for (const entry of metaEntries) {
+                    if (entry.key == 'version') {
+                        if (!RE_SEMVER.test(entry.value) && !(new RegExp(reVer).test(entry.value)))
+                            context.report({
+                                node: entry.comment, messageId: 'invalidVersion', data: { pattern: reVer }})
+                    }
+                    if (['homepage', 'icon', 'updateURL', 'downloadURL', 'supportURL'].includes(entry.key))
+                        try { new URL(entry.value) }
+                        catch {
+                            context.report({ node: entry.comment, messageId: 'invalidURL', data: { field: entry.key }})
+                        }
+                    if (entry.key == 'grant' && allowedGrants.length && !allowedGrants.includes(entry.value))
+                        context.report({ node: entry.comment, messageId: 'invalidGrant', data: { grant: entry.value }})
+                }
+            }
+        }
+    }
+}

package/src/utils.js

@@ -0,0 +1,19 @@
+export function extractMetadata(sourceCode) {
+    const comments = sourceCode.getAllComments(),
+          metaEntries = []
+    let inMetaBlock = false
+    for (const comment of comments) {
+        const text = comment.value.trim()
+        if (!inMetaBlock && text == '==UserScript==') { inMetaBlock = true ; continue }
+        if (inMetaBlock && text == '==/UserScript==') break
+        if (inMetaBlock && text.startsWith('@')) {
+            const spaceIdx = text.indexOf(' ')
+            if (spaceIdx > 1) { // '@' at 0, key starts at 1, need space after key
+                const key = text.slice(1, spaceIdx).trim(),
+                      value = text.slice(spaceIdx +1).trim()
+                metaEntries.push({ key, value, comment, line: comment.loc.start.line })
+            }
+        }
+    }
+    return metaEntries
+}