eslint-plugin-chrome-extensions 1.0.1 → 2.1.0

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

@@ -1,15 +1,40 @@
-import { apiPermissionMap } from '../data/apis.js'
-import { readManifest, getChromeAPIcalls } from '../utils.js'
+import fs from 'node:fs'
+import path from 'node:path'
+import { apiPermissionMap, findPermission } from '../data/apis.js'
+import { findExtensionRoot, getFilename, readManifest } from '../utils.js'
 
-const mappedPermissions = new Set(apiPermissionMap.values())
+const re = { manifestFilename: /manifest\.json$/ }
+
+function collectUsedAPIs(manifest, root) {
+    const files = new Set()
+    if (manifest.background?.service_worker) files.add(manifest.background.service_worker)
+    for (const script of manifest.background?.scripts || []) files.add(script)
+    for (const contentScript of manifest.content_scripts || [])
+        for (const file of contentScript.js || []) files.add(file)
+    if (manifest.action?.default_popup) files.add(manifest.action.default_popup)
+    if (manifest.options_ui?.page) files.add(manifest.options_ui.page)
+    if (manifest.devtools_page) files.add(manifest.devtools_page)
+    const re = { /* eslint-disable-next-line security/detect-unsafe-regex */
+        chromeAPI: /\bchrome\.\w+(?:\.\w+)*/g }
+    const used = new Set()
+    for (const file of files) {
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename
+            const src = fs.readFileSync(path.resolve(root, file), 'utf8')
+            for (const match of src.matchAll(re.chromeAPI)) used.add(match[0])
+        } catch {} // eslint-disable-line no-empty
+    }
+    return used
+}
 
 export default {
     meta: {
-        type: 'suggestion',
+        type: 'problem',
         docs: {
-            description: 'Flag manifest permissions whose APIs are never used in this file',
-            category: 'Best Practices',
-            recommended: true
+            description: 'Flag manifest permissions whose APIs are never used',
+            category: 'Possible Errors',
+            recommended: false,
+            manifest: true
         },
         schema: [],
         messages: {
@@ -18,20 +43,40 @@ export default {
     },
 
     create(context) {
+        if (!re.manifestFilename.test(getFilename(context))) return {}
         const manifest = readManifest(context) ; if (!manifest) return {}
+        const root = findExtensionRoot(context) ; if (!root) return {}
+        const usedAPIs = collectUsedAPIs(manifest, root)
+        const permissionNodes = new Map()
+        function isUsed(permission) {
+            let known = false
+            for (const [, perm] of apiPermissionMap)
+                if (perm == permission) { known = true ; break }
+            if (!known) return true // custom permission → not our business
+            for (const api of usedAPIs)
+                if (findPermission(api) == permission) return true
+            return false
+        }
         return {
-            'Program:exit'() {
-                const declared = manifest.permissions || [] ; if (!declared.length) return
-                const calls = getChromeAPIcalls(context.sourceCode)
-                const used = new Set()
-                for (const api of calls)
-                    for (const [prefix, permission] of apiPermissionMap)
-                        if (api == prefix || api.startsWith(`${prefix}.`)) { used.add(permission) ; break }
-                for (const permission of declared) {
-                    if (!mappedPermissions.has(permission)) continue
-                    if (used.has(permission)) continue
-                    context.report({ loc: { line: 1, column: 0 },
-                        messageId: 'unusedPermission', data: { permission }})
+            '*'(node) {
+                const keyNode = node.name || node.key ; if (!keyNode) return
+                const keyName = keyNode.value ?? keyNode.name
+                if (keyName != 'permissions' && keyName != 'optional_permissions') return
+                const arrNode = node.value ; if (arrNode?.type != 'Array') return
+                const elements = arrNode.elements || arrNode.items || []
+                for (const el of elements) {
+                    const valueNode = el.value || el
+                    const perm = valueNode?.value
+                    if (typeof perm != 'string') continue
+                    if (!permissionNodes.has(perm)) permissionNodes.set(perm, [])
+                    permissionNodes.get(perm).push(valueNode)
+                }
+            },
+            'Document:exit'() {
+                for (const [permission, nodes] of permissionNodes) {
+                    if (isUsed(permission)) continue
+                    for (const n of nodes)
+                        context.report({ node: n, messageId: 'unusedPermission', data: { permission }})
                 }
             }
         }

package/src/rules/require-mv3.js

@@ -1,4 +1,6 @@
-import { readManifest } from '../utils.js'
+import { getFilename, readManifest } from '../utils.js'
+
+const re = { manifestFilename: /manifest\.json$/ }
 
 export default {
     meta: {
@@ -6,15 +8,31 @@ export default {
         docs: {
             description: 'Require manifest_version 3',
             category: 'Possible Errors',
-            recommended: true
+            recommended: false,
+            manifest: true
         },
         schema: [],
         messages: {
-            notMV3: 'manifest.json must declare `"manifest_version": 3` (MV2 rejected by the Chrome Web Store).'
+            notMV3: 'manifest.json must declare `"manifest_version": 3`.'
         }
     },
 
     create(context) {
+        if (re.manifestFilename.test(getFilename(context))) { // lint it directly
+            let foundVersion = null, versionNode = null
+            return {
+                '*'(node) {
+                    const keyNode = node.name || node.key ; if (!keyNode) return
+                    if ((keyNode.value ?? keyNode.name) != 'manifest_version') return
+                    foundVersion = node.value?.value
+                    versionNode = node.value || keyNode
+                },
+                '*:exit'(node) {
+                    if (node.type != 'Document' || foundVersion == 3) return
+                    context.report({ node: versionNode || node, messageId: 'notMV3' })
+                }
+            }
+        }
         const manifest = readManifest(context) ; if (!manifest || manifest.manifest_version == 3) return {}
         return { Program(node) { context.report({ node, messageId: 'notMV3' }) }}
     }

package/src/rules/valid-manifest-icons.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { findExtensionRoot, getFilename } from '../utils.js'
+
+const re = { manifestFilename: /manifest\.json$/, svg: /\.svg$/i },
+      sizes = { recommended: ['16', '32', '48', '128'], required: '128' }
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate manifest icons: sizes, existing files, no SVG',
+            category: 'Possible Errors',
+            recommended: false,
+            manifest: true
+        },
+        defaultOptions: [{
+            requireRecommendedSizes: true,
+            checkIconExists: true,
+            noSVG: true
+        }],
+        schema: [{
+            type: 'object',
+            properties: {
+                requireRecommendedSizes: {
+                    type: 'boolean',
+                    description: 'Require all recommended sizes (16, 32, 48, 128)'
+                },
+                checkIconExists: {
+                    type: 'boolean',
+                    description: 'Flag icon paths that do not resolve to a file'
+                },
+                noSVG: {
+                    type: 'boolean',
+                    description: 'Flag SVG icon paths (unsupported by Chrome)'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            missingSize: 'Recommended icon size "{{size}}" is missing (16, 32, 48, 128).',
+            missingRequiredSize: 'Icons must include a 128x128 icon.',
+            missingFile: 'Icon file "{{file}}" does not exist in the extension root.',
+            svgNotSupported: 'SVG icons are not supported by Chrome. Use PNG instead.'
+        }
+    },
+
+    create(context) {
+        if (!re.manifestFilename.test(getFilename(context))) return {}
+        const opts = context.options[0] || {},
+              requireRecommended = opts.requireRecommendedSizes !== false,
+              checkFiles = opts.checkIconExists !== false,
+              checkSVG = opts.noSVG !== false
+        const root = checkFiles ? findExtensionRoot(context) : null
+        return {
+            '*'(node) {
+                const keyNode = node.name || node.key ; if (!keyNode) return
+                const keyName = keyNode.value ?? keyNode.name ; if (keyName != 'icons') return
+                const iconsObj = node.value ; if (iconsObj?.type != 'Object') return
+                const members = iconsObj.members || iconsObj.properties || []
+                const declaredSizes = new Set()
+                for (const member of members) {
+                    const sizeNode = member.name || member.key,
+                          size = sizeNode?.value ?? sizeNode?.name,
+                          fileNode = member.value,
+                          file = fileNode?.value
+                    if (typeof size == 'string') declaredSizes.add(size)
+                    if (typeof file != 'string') continue
+                    if (checkSVG && re.svg.test(file))
+                        context.report({ node: fileNode, messageId: 'svgNotSupported' })
+                    else if (checkFiles && root // eslint-disable-next-line security/detect-non-literal-fs-filename
+                        && !fs.existsSync(path.resolve(root, file))
+                    ) context.report({ node: fileNode, messageId: 'missingFile', data: { file }})
+                }
+                if (requireRecommended) {
+                    for (const size of sizes.recommended)
+                        if (!declaredSizes.has(size))
+                            context.report({ node: iconsObj, messageId: 'missingSize', data: { size }})
+                } else if (!declaredSizes.has(sizes.required))
+                    context.report({ node: iconsObj, messageId: 'missingRequiredSize' })
+            }
+        }
+    }
+}

package/src/rules/valid-mv3-schema.js

@@ -1,5 +1,8 @@
-import { mv2OnlyKeys, forbiddenCSPDirectives } from '../data/manifest.js'
-import { readManifest } from '../utils.js'
+import { mv2OnlyKeys, forbiddenCSPdirectives } from '../data/manifest.js'
+
+import { getFilename, readManifest } from '../utils.js'
+
+const re = { manifestFilename: /manifest\.json$/ }
 
 export default {
     meta: {
@@ -7,17 +10,63 @@ export default {
         docs: {
             description: 'Validate manifest against the MV3 schema',
             category: 'Possible Errors',
-            recommended: true
+            recommended: false,
+            manifest: true
         },
         schema: [],
         messages: {
-            mv2Key: '`{{key}}` is not allowed in MV3 - {{reason}}.',
+            mv2Key: '`{{key}}` is not allowed in MV3. {{reason}}.',
             unsafeCSP: 'MV3 CSP must not include `{{directive}}`.',
             wrongCSPType: '`content_security_policy` must be an object in MV3, not a string.'
         }
     },
 
     create(context) {
+        if (re.manifestFilename.test(getFilename(context))) { // lint it directly
+            const ancestors = [], pendingReports = []
+            let isMV3 = false
+            const keyOf = n => {
+                const k = n?.name || n?.key
+                return k?.value ?? k?.name
+            }
+            return {
+                '*'(node) {
+                    const keyName = keyOf(node)
+                    if (keyName) {
+                        const isTopLevel = ancestors.length == 2
+                            && ancestors[0].type == 'Document'
+                            && ancestors[1].type == 'Object'
+                        const inBackground = ancestors.some(a => keyOf(a) == 'background')
+                        const inCSP = ancestors.some(a => keyOf(a) == 'content_security_policy')
+                        if (keyName == 'manifest_version' && node.value?.value == 3) isMV3 = true
+                        if (isTopLevel && mv2OnlyKeys.has(keyName))
+                            pendingReports.push({ node, messageId: 'mv2Key',
+                                data: { key: keyName, reason: 'MV2-only key' }})
+                        if (inBackground && keyName == 'scripts')
+                            pendingReports.push({ node, messageId: 'mv2Key',
+                                data: { key: 'background.scripts', reason: 'use background.service_worker' }})
+                        if (inBackground && keyName == 'persistent')
+                            pendingReports.push({ node, messageId: 'mv2Key',
+                                data: { key: 'background.persistent', reason: 'MV3 service workers are never persistent' }})
+                        if (isTopLevel && keyName == 'content_security_policy' && node.value?.type == 'String')
+                            pendingReports.push({ node: node.value, messageId: 'wrongCSPType' })
+                        if (inCSP && keyName == 'extension_pages' && typeof node.value?.value == 'string')
+                            for (const directive of forbiddenCSPdirectives)
+                                if (node.value.value.includes(directive))
+                                    pendingReports.push({ node: node.value, messageId: 'unsafeCSP',
+                                        data: { directive }})
+                    }
+                    ancestors.push(node)
+                },
+                '*:exit'(node) {
+                    ancestors.pop()
+                    if (node.type == 'Document') {
+                        if (!isMV3) return
+                        for (const r of pendingReports) context.report(r)
+                    }
+                }
+            }
+        }
         const manifest = readManifest(context) ; if (!manifest || manifest.manifest_version != 3) return {}
         return {
             Program(node) {
@@ -35,7 +84,7 @@ export default {
                     context.report({ node, messageId: 'wrongCSPType' })
                 const cspPages = csp?.extension_pages
                 if (typeof cspPages == 'string')
-                    for (const directive of forbiddenCSPDirectives)
+                    for (const directive of forbiddenCSPdirectives)
                         if (cspPages.includes(directive))
                             context.report({ node, messageId: 'unsafeCSP', data: { directive }})
             }

package/src/rules/valid-service-worker.js

@@ -12,7 +12,7 @@ export default {
         schema: [],
         messages: {
             listenerNotTopLevel: '`chrome.*.addListener()` must be registered at module top level so it attaches on service worker wake-up.',
-            keepaliveTimer: 'Sub-30s `{{fn}}` will not keep the MV3 service worker alive - use `chrome.alarms` instead.',
+            keepaliveTimer: 'Sub-30s `{{fn}}` will not keep the MV3 service worker alive. Use `chrome.alarms` instead.',
             domInSW: '`{{global}}` is not available in a service worker.'
         }
     },

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

@@ -0,0 +1,95 @@
+import { getFilename, readManifest } from '../utils.js'
+
+const re = { /* eslint-disable security/detect-unsafe-regex */
+    chromeParts: /^\d+(?:\.\d+){0,3}$/,
+    date: /^\d{4}\.(?:0?[1-9]|1[0-2])\.(?:0?[1-9]|[12]\d|3[01])(?:\.\d+)?$/,
+    manifestFilename: /manifest\.json$/,
+    semver: /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/
+} /* eslint-enable security/detect-unsafe-regex */
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate the manifest version field format',
+            category: 'Possible Errors',
+            recommended: false,
+            manifest: true
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                versionType: {
+                    type: 'string',
+                    enum: ['chrome', 'semver', 'date'],
+                    description: 'Version format to enforce (default: chrome)'
+                },
+                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
+        }],
+        defaultOptions: [{}],
+        messages: {
+            invalidVersion: 'Invalid manifest `version`: must be a valid {{versionType}} version (expected format: {{example}}).',
+            futureVersion: 'Invalid manifest `version`: date cannot be in the future.'
+        }
+    },
+
+    create(context) {
+        const options = context.options[0] || {},
+              versionType = options.versionType || 'chrome',
+              allowFutureDate = options.allowFutureDate ?? false,
+              timezone = options.timezone,
+              example = versionType == 'semver' ? '1.2.3'
+                      : versionType == 'date' ? 'YYYY.M.D or YYYY.M.D.N'
+                      : '1.2.3 or 1.2.3.4'
+        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 }
+        function validate(node, version) {
+            if (typeof version != 'string') return
+            const parts = version.split('.')
+            if (!re.chromeParts.test(version) || parts.some(part => Number(part) > 65535))
+                return context.report({ node, messageId: 'invalidVersion', data: { versionType, example }})
+            if (versionType == 'semver') {
+                if (!re.semver.test(version))
+                    context.report({ node, messageId: 'invalidVersion', data: { versionType, example }})
+            } else if (versionType == 'date') {
+                if (!re.date.test(version))
+                    context.report({ node, messageId: 'invalidVersion', data: { versionType, example }})
+                else {
+                    const [year, month, day] = parts.map(Number)
+                    if (!allowFutureDate && (
+                           year > now.year
+                        || year == now.year && month > now.month
+                        || timezone && year == now.year && month == now.month && day > now.day
+                    )) context.report({ node, messageId: 'futureVersion' })
+                }
+            }
+        }
+        if (re.manifestFilename.test(getFilename(context))) // lint it directly
+            return {
+                '*'(node) {
+                    const keyNode = node.name || node.key ; if (!keyNode) return
+                    const keyName = keyNode.value ?? keyNode.name ; if (keyName != 'version') return
+                    const valueNode = node.value ; if (valueNode?.type != 'String') return
+                    validate(valueNode, valueNode.value)
+                }
+            }
+        return {
+            Program(node) {
+                validate(node, readManifest(context)?.version)
+            }
+        }
+    }
+}

package/src/utils.js

@@ -4,13 +4,34 @@ import path from 'node:path'
 const re = { chromeAPI: /\bchrome(?:\.\w+)+/g }, // eslint-disable-line security/detect-unsafe-regex
       manifestCache = new Map()
 
+export function bundleRules(rules, predicate, pluginName, removals = []) {
+    return Object.fromEntries(Object.entries(rules)
+        .filter(([ruleId, rule]) => predicate(rule) || removals.includes(ruleId))
+        .map(([ruleId]) => [`${pluginName}/${ruleId}`, 'error']))
+}
+
+export function deprecatedFrom(bundles, bundleName) {
+    const ruleIds = []
+    for (const [ruleId, [bundle]] of Object.entries(bundles))
+        if (bundle === bundleName) ruleIds.push(ruleId)
+    return ruleIds
+}
+
+export function initBundleDeprecation(plugin, [ruleId, [bundleName, note]], pluginName) {
+    if (!process.env.DEBUG_MODE) return
+    if (plugin.rules[ruleId]) // eslint-disable-line security/detect-object-injection
+        console.warn(`[${pluginName}] '${ruleId}' will be removed from '${
+            bundleName}' in a future major release${note ? ` (${note})` : ''}`)
+}
+
 export function findExtensionRoot(context) {
     let dir = path.dirname(getFilename(context))
-    const root = path.parse(dir).root
-    while (dir != root) {
+    while (dir) {
         // eslint-disable-next-line security/detect-non-literal-fs-filename
         if (fs.existsSync(path.join(dir, 'manifest.json'))) return dir
-        dir = path.dirname(dir)
+        const parent = path.dirname(dir)
+        if (parent == dir) break // reached filesystem root or a stuck relative "."
+        dir = parent
     }
     return null
 }