eslint-plugin-greasemonkey 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-greasemonkey",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
   "type": "module",
   "engines": {
@@ -35,10 +35,10 @@
   "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": "node demo/run.js",
     "bump:patch": "bash utils/bump.sh patch",
@@ -69,7 +69,7 @@
     "@eslint/markdown": "^8.0.3",
     "@stylistic/eslint-plugin": "^5.10.0",
     "eslint": "^10.10.0",
-    "eslint-plugin-constructors": "^1.1.1",
+    "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/{apis.js → data/apis.js}

@@ -8,9 +8,10 @@ export const gmLegacyAPIs = new Set([ /* eslint-disable 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'
+    '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([
@@ -18,3 +19,17 @@ export const scAPIs = new Set([
     '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,12 +1,16 @@
+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 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'
@@ -18,13 +22,15 @@ 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-meta-newline': requireMetaNewline,
         'require-required-fields': requireRequiredFields,
         'require-space-before-meta-key': requireSpaceBeforeMetaKey,
         'require-update-download-pair': requireUpdateDownloadPair,
@@ -34,18 +40,37 @@ const plugin = {
     }
 }
 
+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-meta-newline': 'error',
             'greasemonkey/require-required-fields': 'error',
             'greasemonkey/require-space-before-meta-key': 'error',
             'greasemonkey/require-user-js-filename': 'error',
@@ -58,13 +83,15 @@ plugin.configs = {
         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-meta-newline': 'error',
             'greasemonkey/require-required-fields': 'error',
             'greasemonkey/require-space-before-meta-key': 'error',
             'greasemonkey/require-update-download-pair': 'error',

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

@@ -1,5 +1,5 @@
 import { extractMetadata } from '../utils.js'
-import { gmLegacyAPIs, gmModernAPIs, scAPIs } from '../apis.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

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/{require-meta-newline.js → require-blank-line-after-meta-block.js}

@@ -1,16 +1,14 @@
-import { extractMetadata } from '../utils.js'
-
 export default {
     meta: {
         type: 'layout',
         docs: {
-            description: 'Require a newline between the metadata and code',
+            description: 'Require a blank line between the metadata and code',
             category: 'Stylistic Issues',
             recommended: true
         },
         fixable: 'whitespace',
         schema: [],
-        messages: { missingNewline: 'Missing blank line after metadata block' }
+        messages: { missingBlankLine: 'Missing blank line after metadata block' }
     },
 
     create(context) {
@@ -18,16 +16,15 @@ export default {
             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
+                      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: 'missingNewline',
+                        messageId: 'missingBlankLine',
                         fix(fixer) { return fixer.insertTextAfter(closingComment, '\n') }
                     })
             }

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

@@ -33,8 +33,8 @@ export default {
                         node: homepageURLEntry.comment, messageId: 'missingPair',
                         data: { missing: 'homepage', present: 'homepageURL' },
                         fix(fixer) {
-                            return fixer.insertTextAfter(homepageURLEntry.comment,
-                                `\n// @homepage ${homepageURLEntry.value}`)
+                            return fixer.insertTextBefore(homepageURLEntry.comment,
+                                `// @homepage ${homepageURLEntry.value}\n`)
                         }
                     })
             }

package/src/rules/valid-grants.js

@@ -1,12 +1,10 @@
 import { extractMetadata } from '../utils.js'
-import { gmLegacyAPIs, gmModernAPIs, scAPIs } from '../apis.js'
+import { allAPIs, isAPIValidFor } from '../data/apis.js'
 
-const specialGrants = new Set([
-    'none', 'unsafeWindow', 'window.close', 'window.focus', 'window.onurlchange'
-])
-
-const grants = new Set([...gmLegacyAPIs, ...gmModernAPIs, ...scAPIs, ...specialGrants]),
-      sortedGrants = new Map(Array.from(grants, grant => [grant.toLowerCase(), grant]))
+const managers = ['tampermonkey', 'violentmonkey', 'greasemonkey', 'scriptcat'],
+      specialGrants = new Set(['none', 'unsafeWindow', 'window.close', 'window.focus', 'window.onurlchange']),
+      allGrants = new Set([...allAPIs, ...specialGrants]),
+      sortedGrants = new Map(Array.from(allGrants, grant => [grant.toLowerCase(), grant]))
 
 export default {
     meta: {
@@ -19,6 +17,13 @@ export default {
         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 grants to validate against (default: all)'
+                },
                 allowedGrants: {
                     type: 'array',
                     items: { type: 'string' },
@@ -30,12 +35,15 @@ export default {
         defaultOptions: [{}],
         messages: {
             invalidGrant: 'Invalid @grant: "{{grant}}"',
+            unsupportedGrant: '"@{{grant}}" is not supported by {{target}} (only by {{supporting}})',
             wrongCase: 'Invalid @grant: "{{grant}}" (did you mean "{{suggestion}}"?)'
         }
     },
 
     create(context) {
         const options = context.options[0] || {},
+              rawTarget = options.target ?? 'all',
+              targets = Array.isArray(rawTarget) ? rawTarget : [rawTarget],
               allowedGrants = options.allowedGrants || []
         return {
             Program() {
@@ -43,12 +51,21 @@ export default {
                       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())
-                    context.report(suggestion
-                        ? { node: grant.comment, messageId: 'wrongCase', data: { grant: grantName, suggestion }}
-                        : { node: grant.comment, messageId: 'invalidGrant', data: { grant: grantName }}
-                    )
+                    if (specialGrants.has(grantName) || allowedGrants.includes(grantName)) continue
+                    else if (!allGrants.has(grantName)) {
+                        const suggestion = sortedGrants.get(grantName.toLowerCase())
+                        if (suggestion && suggestion != grantName)
+                            context.report({ node: grant.comment, messageId: 'wrongCase',
+                                data: { grant: grantName, suggestion }})
+                        else
+                            context.report({ node: grant.comment, messageId: 'invalidGrant',
+                                data: { grant: grantName }})
+                        continue
+                    } else if (!targets.includes('all') && !targets.some(m => isAPIValidFor(grantName, m))) {
+                        const supporting = managers.filter(manager => isAPIValidFor(grantName, manager ))
+                        context.report({ node: grant.comment, messageId: 'unsupportedGrant',
+                            data: { grant: grantName, target: targets.join(', '), supporting: supporting.join(', ') }})
+                    }
                 }
             }
         }