eslint-plugin-greasemonkey 1.2.0 → 1.4.0

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-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,32 +1,10 @@
 import { extractMetadata } from '../utils.js'
+import { allAPIs, isAPIValidFor } from '../data/apis.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'
-])
-
-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]),
-      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: {
@@ -39,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' },
@@ -50,28 +35,37 @@ 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() {
                 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 }})
+                    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(', ') }})
+                    }
                 }
             }
         }

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
+}