eslint-plugin-greasemonkey 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-greasemonkey",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "ESLint rules for Greasemonkey/Tampermonkey userscripts",
   "type": "module",
   "engines": {
@@ -63,13 +63,13 @@
     "eslint": ">=9.0.0"
   },
   "devDependencies": {
-    "@e18e/eslint-plugin": "^0.8.0",
+    "@e18e/eslint-plugin": "^0.8.1",
     "@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-constructors": "^1.2.0",
+    "eslint-plugin-constructors": "^1.2.2",
     "eslint-plugin-eslint-plugin": "^7.6.2",
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-n": "^18.3.0",

package/src/data/apis.js

@@ -32,5 +32,4 @@ export function supportsAPI({ manager, api }) {
          : api.startsWith('CAT') ? manager == 'scriptcat'
          : tmAPIs.has(api) ? manager == 'tampermonkey'
          : true
-
 }

package/src/data/deprecations.js

@@ -1,3 +1,8 @@
-export default { // val = replacement
-    rules: { 'require-meta-newline': 'require-blank-line-after-meta-block' } // 2026-9-13
+// Delete a line to end support
+
+export const rules = { // old: new
+    'valid-grants': 'no-invalid-grants', // 2026-9-16 announced removal @ v2
+    'require-meta-newline': 'require-blank-line-after-meta-block' // 2026-9-13 announced removal @ v2
 }
+
+export default { rules }

package/src/data/headers.js

@@ -6,17 +6,23 @@ export const universalHeaders = new Set([
 ])
 
 export const managerHeaders = new Map([
-    ['inject-into',     ['violentmonkey']],
-    ['top-level-await', ['violentmonkey']],
-    ['user-agent',      ['tampermonkey']],
-    ['run-in',          ['tampermonkey']],
+    ['run-in',          ['tampermonkey', 'scriptcat']],
+    ['nocompat',        ['tampermonkey']],
     ['sandbox',         ['tampermonkey']],
+    ['user-agent',      ['tampermonkey']],
     ['webRequest',      ['tampermonkey']],
-    ['nocompat',        ['tampermonkey']]
+    ['inject-into',     ['violentmonkey', 'scriptcat']],
+    ['top-level-await', ['violentmonkey']],
+    ['background',      ['scriptcat']],
+    ['crontab',         ['scriptcat']],
+    ['definition',      ['scriptcat']],
+    ['early-start',     ['scriptcat']],
+    ['require-css',     ['scriptcat']],
+    ['storageName',     ['scriptcat']]
 ])
 
 export const localizedHeaders = ['name', 'description', 'antifeature']
-export const managers = ['tampermonkey', 'violentmonkey', 'greasemonkey']
+export const managers = ['tampermonkey', 'violentmonkey', 'greasemonkey', 'scriptcat']
 export const validHeaders = new Map()
 
 validHeaders.set('all', new Set([...universalHeaders, ...managerHeaders.keys()]))

package/src/index.js

@@ -1,8 +1,11 @@
-import aliases from './data/deprecations.js'
+/* eslint-disable security/detect-object-injection -- false positives */
+
+import { rules as oldRules } from './data/deprecations.js'
 
 import metaOrder from './rules/meta-order.js'
 import metaSpacing from './rules/meta-spacing.js'
 import noDuplicateKeys from './rules/no-duplicate-keys.js'
+import noInvalidGrants from './rules/no-invalid-grants.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'
@@ -18,13 +21,15 @@ import requireSRIhashing from './rules/require-sri-hashing.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'
+
+import { initDeprecatedAlias } from './utils.js'
 
 const plugin = {
     rules: {
         'meta-order': metaOrder,
         'meta-spacing': metaSpacing,
         'no-duplicate-keys': noDuplicateKeys,
+        'no-invalid-grants': noInvalidGrants,
         'no-invalid-headers': noInvalidHeaders,
         'no-missing-grants': noMissingGrants,
         'no-unused-grants': noUnusedGrants,
@@ -39,27 +44,15 @@ const plugin = {
         'require-sri-hashing': requireSRIhashing,
         'require-update-download-pair': requireUpdateDownloadPair,
         'require-user-js-filename': requireUserJsFilename,
-        'valid-field-values': validFieldValues,
-        'valid-grants': validGrants
+        'valid-field-values': validFieldValues
     }
 }
 
-const docsURL = 'https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#'
 for (const [ruleId, rule] of Object.entries(plugin.rules))
-    rule.meta.docs.url = docsURL + ruleId
+    rule.meta.docs.url = `https://codeberg.org/adamlui/eslint-plugin-greasemonkey/#${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 */
+for (const entry of Object.entries(oldRules))
+    initDeprecatedAlias(plugin, entry)
 
 plugin.configs = {
     recommended: {
@@ -67,6 +60,7 @@ plugin.configs = {
         rules: {
             'greasemonkey/meta-spacing': 'error',
             'greasemonkey/no-duplicate-keys': 'error',
+            'greasemonkey/no-invalid-grants': 'error',
             'greasemonkey/no-invalid-headers': 'error',
             'greasemonkey/no-missing-grants': 'error',
             'greasemonkey/no-unused-grants': 'error',
@@ -78,24 +72,23 @@ plugin.configs = {
             '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'
+            'greasemonkey/valid-field-values': 'error'
         }
+    },
+    strict: {
+        plugins: { greasemonkey: plugin },
+        rules: Object.fromEntries(Object.keys(plugin.rules).map(ruleId => [`greasemonkey/${ruleId}`, 'error']))
     }
 }
 
-plugin.configs.strict = {
-    plugins: { greasemonkey: plugin },
-    rules: Object.fromEntries(Object.keys(plugin.rules).map(ruleId => [`greasemonkey/${ruleId}`, 'error']))
-}
-
 for (const manager of ['tampermonkey', 'violentmonkey', 'greasemonkey', 'scriptcat'])
-    plugin.configs[manager] = { // eslint-disable-line security/detect-object-injection
+    plugin.configs[manager] = {
         plugins: { greasemonkey: plugin },
         rules: {
             ...plugin.configs.recommended.rules,
+            'greasemonkey/no-invalid-grants': ['error', { target: manager }],
             'greasemonkey/no-invalid-headers': ['error', { target: manager }],
-            'greasemonkey/valid-grants': ['error', { target: manager }]
+            ...(manager == 'tampermonkey' && { 'greasemonkey/require-update-download-pair': 'error' })
         }
     }
 

package/src/rules/meta-order.js

@@ -12,8 +12,8 @@ function findViolation(entries, keys) {
               const key = entry.key.split(':', 1)[0]
               return { entry, key, rank: ranks.get(key) }
           }).filter(item => item.rank !== undefined)
-    for (let i = 1; i < known.length; i++) // eslint-disable-next-line security/detect-object-injection
-        if (known[i - 1].rank > known[i].rank) return [known[i - 1], known[i]]
+    for (let i = 1 ; i < known.length ; i++) // eslint-disable-next-line security/detect-object-injection
+        if (known[i -1].rank > known[i].rank) return [known[i -1], known[i]]
 }
 
 function sortEntries(entries, keys) {
@@ -21,7 +21,7 @@ function sortEntries(entries, keys) {
     return entries.toSorted((a, b) => {
         const aRank = ranks.get(a.key.split(':', 1)[0]),
               bRank = ranks.get(b.key.split(':', 1)[0])
-        return (aRank ?? Infinity) - (bRank ?? Infinity)
+        return ( aRank ?? Infinity ) -( bRank ?? Infinity )
     })
 }
 
@@ -35,16 +35,31 @@ export default {
         },
         fixable: 'code',
         schema: [{
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Metadata keys in preferred order; unspecified keys are ignored'
+            oneOf: [
+                {
+                    type: 'array', items: { type: 'string' },
+                    description: 'Metadata keys in preferred order; unspecified keys are ignored'
+                },
+                {
+                    type: 'object',
+                    properties: {
+                        order: {
+                            type: 'array', items: { type: 'string' },
+                            description: 'Metadata keys in preferred order; unspecified keys are ignored'
+                        }
+                    },
+                    additionalProperties: false,
+                    description: 'Options for metadata key ordering'
+                }
+            ]
         }],
         defaultOptions: [[]],
         messages: { wrongOrder: '@{{first}} should appear before @{{second}}' }
     },
 
     create(context) {
-        const custom = context.options[0] ?? [],
+        const option = context.options[0] ?? [],
+              custom = Array.isArray(option) ? option : option.order ?? [],
               master = custom.length ? defaultOrder.filter(key => !custom.includes(key)) : defaultOrder
         return {
             Program() {

package/src/rules/meta-spacing.js

@@ -11,13 +11,32 @@ export default {
             recommended: true
         },
         fixable: 'whitespace',
-        schema: [{ type: 'number', description: 'Minimum spaces after the longest key (default 3)' }],
+        schema: [{
+            oneOf: [
+                {
+                    type: 'number',
+                    description: 'Minimum spaces after the longest key (default 3)'
+                },
+                {
+                    type: 'object',
+                    properties: {
+                        spaces: {
+                            type: 'number',
+                            description: 'Minimum spaces after the longest key (default 3)'
+                        }
+                    },
+                    additionalProperties: false,
+                    description: 'Options for metadata spacing'
+                }
+            ]
+        }],
         defaultOptions: [3],
         messages: { misaligned: 'Metadata values should be aligned at column {{column}}' }
     },
 
     create(context) {
-        const minSpaces = context.options[0] ?? 3
+        const option = context.options[0] ?? 3,
+              minSpaces = typeof option == 'number' ? option : option.spaces ?? 3
         return {
             Program() {
                 const sourceCode = context.sourceCode,

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

@@ -15,6 +15,10 @@ export default {
                     type: 'array',
                     items: { type: 'string' },
                     description: 'Required metadata fields (default: name, version)'
+                },
+                requireMatchOrInclude: {
+                    type: 'boolean',
+                    description: 'Require a match or include metadata field (default: true)'
                 }
             },
             additionalProperties: false
@@ -25,7 +29,8 @@ export default {
 
     create(context) {
         const options = context.options[0] || {},
-              requiredFields = options.fields || ['name', 'version']
+              requiredFields = options.fields || ['name', 'version'],
+              requireMatchOrInclude = options.requireMatchOrInclude ?? true
         return {
             Program(node) {
                 const metaEntries = extractMetadata(context.sourceCode),
@@ -33,7 +38,7 @@ export default {
                 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)))
+                if (requireMatchOrInclude && !['include', 'match'].some(field => keys.has(field)))
                     context.report({ node, messageId: 'missingField', data: { field: 'match or include' }})
             }
         }

package/src/rules/require-sri-hashing.js

@@ -46,7 +46,7 @@ export default {
                             node: entry.comment, messageId: 'invalidHash',
                             data: {
                                 key: entry.key,
-                                detected: match ? ` Detected ${match[1].toLowerCase()};` : '',
+                                detected: match ? ` Detected ${match[1].toLowerCase()}.` : '',
                                 expected: algorithm
                             }
                         })

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

@@ -28,6 +28,14 @@ export default {
                     type: 'array',
                     items: { type: 'string' },
                     description: 'Allowed @grant values to check against; if empty, no grant validation'
+                },
+                allowFutureDate: {
+                    type: 'boolean',
+                    description: 'Allow @version dates later than the current date (default: false)'
+                },
+                timezone: {
+                    type: 'string',
+                    description: 'IANA timezone for determining the current date (when omitted, only year and month are checked)'
                 }
             },
             additionalProperties: false
@@ -35,6 +43,7 @@ export default {
         defaultOptions: [{}],
         messages: {
             invalidVersion: 'Invalid @version: must be a valid {{versionType}} (expected format: {{example}})',
+            futureVersion: 'Invalid @version: date cannot be in the future',
             invalidURL: 'Invalid URL for @{{field}}',
             invalidGrant: 'Unknown @grant: "{{grant}}"'
         }
@@ -44,7 +53,15 @@ export default {
         const options = context.options[0] || {},
               versionType = options.versionType || 'semver',
               allowedGrants = options.allowedGrants || [],
+              allowFutureDate = options.allowFutureDate ?? false,
+              timezone = options.timezone,
               example = versionType == 'semver' ? '1.2.3' : 'YYYY.M.D or YYYY.MM.DD'
+        const now = timezone
+            ? Object.fromEntries(new Intl.DateTimeFormat('en', {
+                timeZone: timezone, year: 'numeric', month: 'numeric', day: 'numeric'
+            }).formatToParts().filter(({ type }) => ['year', 'month', 'day'].includes(type))
+                .map(({ type, value }) => [type, Number(value)]))
+            : { year: new Date().getUTCFullYear(), month: new Date().getUTCMonth() +1 }
         return {
             Program() {
                 const metaEntries = extractMetadata(context.sourceCode)
@@ -66,9 +83,15 @@ export default {
                         const isValid = versionType == 'semver' ? re.semVer.test(entry.value)
                                       : versionType == 'date' ? re.dateVer.test(entry.value)
                                       : false
+                        const [year, month, day] = versionType == 'date' ? entry.value.split('.').map(Number) : []
                         if (!isValid)
                             context.report({
                                 node: entry.comment, messageId: 'invalidVersion', data: { versionType, example }})
+                        else if (versionType == 'date' && !allowFutureDate && (
+                            year > now.year || year == now.year && month > now.month
+                                || timezone && year == now.year && month == now.month && day > now.day
+                        ))
+                            context.report({ node: entry.comment, messageId: 'futureVersion' })
                     }
                 }
             }

package/src/utils.js

@@ -1,3 +1,5 @@
+const re = { whitespace: /\s/ }
+
 export function extractMetadata(sourceCode) {
     const comments = sourceCode.getAllComments(),
           metaEntries = []
@@ -7,17 +9,55 @@ export function extractMetadata(sourceCode) {
         if (!inMetaBlock && text == '==UserScript==') inMetaBlock = true
         else if (inMetaBlock && text == '==/UserScript==') break
         else if (inMetaBlock && text.startsWith('@')) { // capture entry
-            const spaceIdx = text.indexOf(' ')
-            if (spaceIdx > 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 })
-            }
+            const spaceIdx = text.search(re.whitespace),
+                  key = spaceIdx == -1 ? text.slice(1).trim() : text.slice(1, spaceIdx).trim(),
+                  value = spaceIdx == -1 ? '' : text.slice(spaceIdx +1).trim()
+            if (key) metaEntries.push({ key, value, comment, line: comment.loc.start.line })
         }
     }
     return metaEntries
 }
 
+export function initDeprecatedAlias(plugin, [oldName, alias]) { /* eslint-disable security/detect-object-injection */
+    const entries = typeof alias == 'string' ? [[alias, null]] // old: new
+        : Array.isArray(alias) ? alias.flatMap(entry =>
+            typeof entry == 'string' ? [[entry, null]] : Object.entries(entry)) // old: [new, ...]
+        : Object.entries(alias) // old: { new: { old-option: new-option }}
+    const newNames = entries.filter(([name]) => name != oldName).map(([name]) => name),
+          newRule = plugin.rules[newNames[0] || oldName]
+    plugin.rules[oldName] = {
+        ...newRule,
+        meta: {
+            ...newRule.meta,
+            schema: typeof alias == 'string' ? newRule.meta.schema : [{ type: 'object' }],
+            docs: { ...newRule.meta.docs, recommended: false },
+            deprecated: {
+                message: `Use ${newNames.map(name => `\`${name}\``).join(', ')} instead.`,
+                replacedBy: newNames.map(name => ({ rule: { name }}))
+            }
+        },
+        create(context) {
+            const oldOptions = context.options[0]
+            return Object.assign({}, ...entries.map(([name, mapping]) => {
+                const newRule = plugin.rules[name]
+                const options = mapping ? {
+                    ...oldOptions,
+                    ...Object.fromEntries(Object.entries(mapping).map(([oldKey, newKey]) => // old: new
+                        [newKey, oldOptions?.[oldKey] ?? (newKey == 'reverseDefault' ? true : newKey)]))
+                } : oldOptions
+                const aliasContext = new Proxy({}, {
+                    get(_, property) {
+                        if (property == 'options') return [options]
+                        const val = context[property]
+                        return typeof val == 'function' ? val.bind(context) : val
+                    }
+                })
+                return newRule.create(aliasContext)
+            }))
+        }
+    }
+} /* eslint-enable security/detect-object-injection */
+
 export function resolveTemplate(node) {
     if (node.type == 'ConditionalExpression') {
         const branches = [node.consequent, node.alternate].map(resolveTemplate)