eslint-plugin-greasemonkey 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-greasemonkey",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
   "type": "module",
   "engines": {
@@ -35,12 +35,12 @@
   "types": "src/index.d.ts",
   "scripts": {
     "prepare": "husky",
-    "lint": "eslint . --cache",
-    "lint:all": "eslint .",
-    "lint:fix": "eslint . --fix --cache",
-    "lint:fix-all": "eslint . --fix",
+    "lint": "eslint . --cache && yamllint .",
+    "lint:all": "eslint . && yamllint .",
+    "lint:fix": "eslint . --fix --cache && yamllint .",
+    "lint:fix-all": "eslint . --fix && yamllint .",
     "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.2.0",
     "eslint-plugin-eslint-plugin": "^7.6.2",
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-n": "^18.3.0",
@@ -79,6 +79,7 @@
     "eslint-plugin-regexp": "^3.3.0",
     "eslint-plugin-security": "^4.0.1",
     "globals": "^17.12.0",
-    "husky": "^9.1.7"
+    "husky": "^9.1.7",
+    "yamllint-js": "^0.2.4"
   }
 }

package/src/data/apis.js

@@ -0,0 +1,35 @@
+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.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'
+])
+
+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'
+])
+
+const tmAPIs = new Set([
+    'GM_getTab', 'GM_getTabs', 'GM_saveTab', 'GM_webRequest',
+    'GM.getTab', 'GM.getTabs', 'GM.saveTab', 'GM.webRequest'
+])
+
+export const allAPIs = new Set([...gmLegacyAPIs, ...gmModernAPIs, ...scAPIs])
+
+export function isAPIValidFor(api, manager) {
+    if (!allAPIs.has(api)) return false
+    if (api.startsWith('CAT')) return manager == 'scriptcat'
+    if (tmAPIs.has(api)) return manager == 'tampermonkey'
+    return true
+}

package/src/data/deprecations.js

@@ -0,0 +1,3 @@
+export default { // val = replacement
+    rules: { 'require-meta-newline': 'require-blank-line-after-meta-block' }
+}

package/src/data/headers.js

@@ -0,0 +1,30 @@
+export const universalHeaders = new Set([
+    'antifeature', 'author', 'compatible', 'connect', 'contributionAmount', 'contributionURL', 'copyright',
+    'defaulticon', 'description', 'downloadURL', 'exclude', 'exclude-match', 'grant', 'homepage', 'homepageURL',
+    'icon', 'icon64', 'include', 'license', 'match', 'name', 'namespace', 'noframes', 'require', 'resource',
+    'run-at', 'source', 'supportURL', 'unwrap', 'updateURL', 'version', 'website'
+])
+
+export const managerHeaders = new Map([
+    ['inject-into',     ['violentmonkey']],
+    ['top-level-await', ['violentmonkey']],
+    ['user-agent',      ['tampermonkey']],
+    ['run-in',          ['tampermonkey']],
+    ['sandbox',         ['tampermonkey']],
+    ['webRequest',      ['tampermonkey']],
+    ['nocompat',        ['tampermonkey']],
+    ['domain',          ['scriptish']]
+])
+
+export const localizedHeaders = ['name', 'description', 'antifeature']
+export const managers = ['tampermonkey', 'violentmonkey', 'greasemonkey', 'scriptish']
+export const validHeaders = new Map()
+
+validHeaders.set('all', new Set([...universalHeaders, ...managerHeaders.keys()]))
+
+for (const manager of managers) {
+    const specific = [...managerHeaders]
+        .filter(([, supportedBy]) => supportedBy.includes(manager))
+        .map(([header]) => header)
+    validHeaders.set(manager, new Set([...universalHeaders, ...specific]))
+}

package/src/index.js

@@ -1,9 +1,19 @@
+import aliases from './data/deprecations.js'
+
 import metaSpacing from './rules/meta-spacing.js'
 import noDuplicateKeys from './rules/no-duplicate-keys.js'
+import noInvalidHeaders from './rules/no-invalid-headers.js'
+import noMissingGrants from './rules/no-missing-grants.js'
+import noMissingResources from './rules/no-missing-resources.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 requireBlankLineAfterMetaBlock from './rules/require-blank-line-after-meta-block.js'
+import requireHomepagePair from './rules/require-homepage-pair.js'
 import requireMatchingLocalizedFields from './rules/require-matching-localized-fields.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,26 +22,79 @@ const plugin = {
     rules: {
         'meta-spacing': metaSpacing,
         'no-duplicate-keys': noDuplicateKeys,
+        'no-invalid-headers': noInvalidHeaders,
+        'no-missing-grants': noMissingGrants,
         'no-unused-grants': noUnusedGrants,
+        'no-missing-resources': noMissingResources,
         'no-unused-resources': noUnusedResources,
+        'prefer-match': preferMatch,
+        'require-blank-line-after-meta-block': requireBlankLineAfterMetaBlock,
+        'require-homepage-pair': requireHomepagePair,
         'require-matching-localized-fields': requireMatchingLocalizedFields,
         '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
     }
 }
 
+const docsURL = 'https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#'
+for (const [ruleId, rule] of Object.entries(plugin.rules))
+    rule.meta.docs.url = docsURL + ruleId
+
+// Generate deprecated aliases
+for (const [oldName, newName] of Object.entries(aliases.rules)) { /* eslint-disable security/detect-object-injection */
+    const newRule = plugin.rules[newName]
+    plugin.rules[oldName] = {
+        ...newRule,
+        meta: {
+            ...newRule.meta,
+            docs: { ...newRule.meta.docs, recommended: false },
+            deprecated: { message: `Use \`${newName}\` instead.`, replacedBy: [{ rule: { name: newName }}] }
+        }
+    }
+} /* eslint-enable security/detect-object-injection */
+
 plugin.configs = {
     recommended: {
         plugins: { greasemonkey: plugin },
         rules: {
             'greasemonkey/meta-spacing': 'error',
             'greasemonkey/no-duplicate-keys': 'error',
+            'greasemonkey/no-invalid-headers': 'error',
+            'greasemonkey/no-missing-grants': 'error',
+            'greasemonkey/no-unused-grants': 'error',
+            'greasemonkey/no-missing-resources': 'error',
+            'greasemonkey/no-unused-resources': 'error',
+            'greasemonkey/prefer-match': 'error',
+            'greasemonkey/require-blank-line-after-meta-block': 'error',
+            'greasemonkey/require-matching-localized-fields': '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-invalid-headers': 'error',
+            'greasemonkey/no-missing-grants': 'error',
             'greasemonkey/no-unused-grants': 'error',
+            'greasemonkey/no-missing-resources': 'error',
             'greasemonkey/no-unused-resources': 'error',
+            'greasemonkey/prefer-match': 'error',
+            'greasemonkey/require-blank-line-after-meta-block': 'error',
+            'greasemonkey/require-homepage-pair': 'error',
             'greasemonkey/require-matching-localized-fields': '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 +102,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-invalid-headers.js

@@ -0,0 +1,80 @@
+import { extractMetadata } from '../utils.js'
+import { managerHeaders, managers, localizedHeaders, validHeaders } from '../data/headers.js'
+
+function parseAllowedPattern(entry) {
+    if (typeof entry != 'string' || !entry.startsWith('/')) return null
+    const lastSlash = entry.lastIndexOf('/')
+    if (lastSlash == 0) return null
+    try { /* eslint-disable-next-line security/detect-non-literal-regexp */
+        return new RegExp(entry.slice(1, lastSlash), entry.slice(lastSlash +1))
+    } catch { return null }
+}
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow invalid metadata headers',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                target: {
+                    anyOf: [
+                        { type: 'string', enum: ['all', ...managers] },
+                        { type: 'array', items: { type: 'string', enum: managers }, minItems: 1, uniqueItems: true }
+                    ],
+                    description: 'Manager(s) whose headers to validate against (default: all)'
+                },
+                allowedHeaders: {
+                    anyOf: [{ type: 'string' }, { type: 'array' }, {}],
+                    description: 'Additional headers: string, RegExp, or array mixing both'
+                }
+            },
+            additionalProperties: false
+        }],
+        defaultOptions: [{ allowedHeaders: [] }],
+        messages: {
+            invalidHeader: 'Invalid header: "@{{header}}"',
+            unsupportedHeader: '"@{{header}}" is not supported by {{target}} (only by {{supporting}})'
+        }
+    },
+
+    create(context) {
+        const options = context.options[0] || {},
+              rawTarget = options.target ?? 'all',
+              targets = Array.isArray(rawTarget) ? rawTarget : [rawTarget],
+              rawAllowed = options.allowedHeaders ?? [],
+              allowedList = Array.isArray(rawAllowed) ? rawAllowed : [rawAllowed],
+              allowedExact = new Set(),
+              allowedRegexes = [],
+              validSet = targets.includes('all') ? validHeaders.get('all')
+                       : new Set(targets.flatMap(target => [...validHeaders.get(target)]))
+        for (const entry of allowedList) {
+            if (entry instanceof RegExp) allowedRegexes.push(entry)
+            else if (typeof entry == 'string') {
+                const parsed = parseAllowedPattern(entry)
+                if (parsed) allowedRegexes.push(parsed)
+                else allowedExact.add(entry)
+            }
+        }
+        return {
+            Program() {
+                const metaEntries = extractMetadata(context.sourceCode)
+                for (const entry of metaEntries) {
+                    if (allowedExact.has(entry.key)) continue
+                    if (allowedRegexes.some(re => re.test(entry.key))) continue
+                    if (localizedHeaders.includes(entry.key.split(':')[0])) continue
+                    if (validSet.has(entry.key)) continue
+                    const supporting = managerHeaders.get(entry.key)
+                    if (supporting)
+                        context.report({ node: entry.comment, messageId: 'unsupportedHeader',
+                            data: { header: entry.key, target: targets.join(', '), supporting: supporting.join(', ') }})
+                    else context.report({ node: entry.comment, messageId: 'invalidHeader', data: { header: entry.key }})
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,51 @@
+import { extractMetadata } from '../utils.js'
+import { gmLegacyAPIs, gmModernAPIs, scAPIs } from '../data/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-missing-resources.js

@@ -0,0 +1,61 @@
+import { extractMetadata, resolveTemplate } from '../utils.js'
+
+const resourceGetterNames = new Set(['GM_getResourceText', 'GM_getResourceURL']),
+      re = { specialChars: /[.*+?^${}()|[\]\\]/g, whitespace: /\s+/ }
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow @resource references without a matching declaration',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            missingResource: 'Missing @resource: "{{name}}"',
+            noMatchingResource: 'No declared @resource matches `{{pattern}}`'
+        }
+    },
+
+    create(context) {
+        const usedRefs = []
+        function record(node, arg) {
+            if (arg?.type == 'Literal' && typeof arg.value == 'string')
+                usedRefs.push({ names: [arg.value], pattern: null, node })
+            else if (arg?.type == 'TemplateLiteral') {
+                const resolved = resolveTemplate(arg)
+                if (resolved) usedRefs.push({ names: resolved, pattern: null, node })
+                else usedRefs.push({
+                    names: null,
+                    pattern: new RegExp( // eslint-disable-line security/detect-non-literal-regexp
+                        `^${arg.quasis.map(q => q.value.raw.replace(re.specialChars, '\\$&')).join('.*')}$`),
+                    node
+                })
+            }
+        }
+        return {
+            CallExpression(node) {
+                if (!resourceGetterNames.has(node.callee.name)) return
+                record(node, node.arguments[0])
+            },
+            'Program:exit'() {
+                if (!usedRefs.length) return
+                const declared = new Set(
+                    extractMetadata(context.sourceCode)
+                        .filter(entry => entry.key == 'resource')
+                        .map(entry => entry.value.trim().split(re.whitespace)[0])
+                )
+                for (const ref of usedRefs) {
+                    if (ref.names) {
+                        for (const name of ref.names)
+                            if (!declared.has(name))
+                                context.report({ node: ref.node, messageId: 'missingResource', data: { name }})
+                    } else if (![...declared].some(name => ref.pattern.test(name)))
+                        context.report({
+                            node: ref.node, messageId: 'noMatchingResource', data: { pattern: ref.pattern.source }})
+                }
+            }
+        }
+    }
+}

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-blank-line-after-meta-block.js

@@ -0,0 +1,33 @@
+export default {
+    meta: {
+        type: 'layout',
+        docs: {
+            description: 'Require a blank line between the metadata and code',
+            category: 'Stylistic Issues',
+            recommended: true
+        },
+        fixable: 'whitespace',
+        schema: [],
+        messages: { missingBlankLine: 'Missing blank line after metadata block' }
+    },
+
+    create(context) {
+        return {
+            Program() {
+                const sourceCode = context.sourceCode,
+                      comments = sourceCode.getAllComments(),
+                      hasOpening = comments.some(comment => comment.value.trim() == '==UserScript=='),
+                      closingComment = comments.find(comment => comment.value.trim() == '==/UserScript==')
+                if (!hasOpening || !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: 'missingBlankLine',
+                        fix(fixer) { return fixer.insertTextAfter(closingComment, '\n') }
+                    })
+            }
+        }
+    }
+}

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.insertTextBefore(homepageURLEntry.comment,
+                                `// @homepage ${homepageURLEntry.value}\n`)
+                        }
+                    })
+            }
+        }
+    }
+}