eslint-plugin-n 17.18.0 → 17.19.0

package/README.md

@@ -156,6 +156,7 @@ For [Shareable Configs](https://eslint.org/docs/latest/developer-guide/shareable
 | [no-restricted-import](docs/rules/no-restricted-import.md)                                   | disallow specified modules when loaded by `import` declarations             |      |    |    |
 | [no-restricted-require](docs/rules/no-restricted-require.md)                                 | disallow specified modules when loaded by `require`                         |      |    |    |
 | [no-sync](docs/rules/no-sync.md)                                                             | disallow synchronous methods                                                |      |    |    |
+| [no-top-level-await](docs/rules/no-top-level-await.md)                                       | disallow top-level `await` in published modules                             |      |    |    |
 | [no-unpublished-bin](docs/rules/no-unpublished-bin.md)                                       | disallow `bin` files that npm ignores                                       | 🟢 ✅ |    |    |
 | [no-unpublished-import](docs/rules/no-unpublished-import.md)                                 | disallow `import` declarations which import private modules                 | 🟢 ✅ |    |    |
 | [no-unpublished-require](docs/rules/no-unpublished-require.md)                               | disallow `require()` expressions which import private modules               | 🟢 ✅ |    |    |

package/lib/index.js

@@ -34,6 +34,7 @@ const base = {
         "no-restricted-import": require("./rules/no-restricted-import"),
         "no-restricted-require": require("./rules/no-restricted-require"),
         "no-sync": require("./rules/no-sync"),
+        "no-top-level-await": require("./rules/no-top-level-await"),
         "no-unpublished-bin": require("./rules/no-unpublished-bin"),
         "no-unpublished-import": require("./rules/no-unpublished-import"),
         "no-unpublished-require": require("./rules/no-unpublished-require"),

package/lib/rules/no-sync.js

@@ -4,6 +4,22 @@
  */
 "use strict"
 
+let typeMatchesSpecifier =
+    /** @type {import('ts-declaration-location').default | undefined} */
+    (undefined)
+
+try {
+    typeMatchesSpecifier =
+        /** @type {import('ts-declaration-location').default} */ (
+            /** @type {unknown} */ (require("ts-declaration-location"))
+        )
+
+    // eslint-disable-next-line no-empty -- Deliberately left empty.
+} catch {}
+const getTypeOfNode = require("../util/get-type-of-node")
+const getParserServices = require("../util/get-parser-services")
+const getFullTypeName = require("../util/get-full-type-name")
+
 const selectors = [
     // fs.readFileSync()
     // readFileSync.call(null, 'path')
@@ -16,7 +32,7 @@ const selectors = [
  * @typedef {[
  *   {
  *     allowAtRootLevel?: boolean
- *     ignores?: string[]
+ *     ignores?: (string | { from: "file"; path?: string; name?: string[]; } | { from: "package"; package?: string; name?: string[]; } | { from: "lib"; name?: string[]; })[]
  *   }?
  * ]} RuleOptions
  */
@@ -40,7 +56,56 @@ module.exports = {
                     },
                     ignores: {
                         type: "array",
-                        items: { type: "string" },
+                        items: {
+                            oneOf: [
+                                { type: "string" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        from: { const: "file" },
+                                        path: {
+                                            type: "string",
+                                        },
+                                        name: {
+                                            type: "array",
+                                            items: {
+                                                type: "string",
+                                            },
+                                        },
+                                    },
+                                    additionalProperties: false,
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        from: { const: "lib" },
+                                        name: {
+                                            type: "array",
+                                            items: {
+                                                type: "string",
+                                            },
+                                        },
+                                    },
+                                    additionalProperties: false,
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        from: { const: "package" },
+                                        package: {
+                                            type: "string",
+                                        },
+                                        name: {
+                                            type: "array",
+                                            items: {
+                                                type: "string",
+                                            },
+                                        },
+                                    },
+                                    additionalProperties: false,
+                                },
+                            ],
+                        },
                         default: [],
                     },
                 },
@@ -65,15 +130,70 @@ module.exports = {
              * @returns {void}
              */
             [selector.join(",")](node) {
-                if (ignores.includes(node.name)) {
-                    return
+                const parserServices = getParserServices(context)
+
+                /**
+                 * @type {import('typescript').Type | undefined | null}
+                 */
+                let type = undefined
+
+                /**
+                 * @type {string | undefined | null}
+                 */
+                let fullName = undefined
+
+                for (const ignore of ignores) {
+                    if (typeof ignore === "string") {
+                        if (ignore === node.name) {
+                            return
+                        }
+
+                        continue
+                    }
+
+                    if (
+                        parserServices === null ||
+                        parserServices.program === null
+                    ) {
+                        throw new Error(
+                            'TypeScript parser services not available. Rule "n/no-sync" is configured to use "ignores" option with a non-string value. This requires TypeScript parser services to be available.'
+                        )
+                    }
+
+                    if (typeMatchesSpecifier === undefined) {
+                        throw new Error(
+                            'ts-declaration-location not available. Rule "n/no-sync" is configured to use "ignores" option with a non-string value. This requires ts-declaration-location to be available.'
+                        )
+                    }
+
+                    type =
+                        type === undefined
+                            ? getTypeOfNode(node, parserServices)
+                            : type
+
+                    fullName =
+                        fullName === undefined
+                            ? getFullTypeName(type)
+                            : fullName
+
+                    if (
+                        typeMatchesSpecifier(
+                            parserServices.program,
+                            ignore,
+                            type
+                        ) &&
+                        (ignore.name === undefined ||
+                            ignore.name.includes(fullName ?? node.name))
+                    ) {
+                        return
+                    }
                 }
 
                 context.report({
                     node: node.parent,
                     messageId: "noSync",
                     data: {
-                        propertyName: node.name,
+                        propertyName: fullName ?? node.name,
                     },
                 })
             },

package/lib/rules/no-top-level-await.js

@@ -0,0 +1,132 @@
+/**
+ * @author Yosuke Ota <https://github.com/ota-meshi>
+ * See LICENSE file in root directory for full license.
+ */
+"use strict"
+
+const path = require("path")
+const { getSourceCode } = require("../util/eslint-compat")
+const getConvertPath = require("../util/get-convert-path")
+const { getPackageJson } = require("../util/get-package-json")
+const { isBinFile } = require("../util/is-bin-file")
+const getNpmignore = require("../util/get-npmignore")
+
+const HASHBANG_ENV = "#!/usr/bin/env"
+
+/**
+ * @typedef {[
+ *   {
+ *     ignoreBin?:boolean
+ *     convertPath?: import('../util/get-convert-path').ConvertPath;
+ *   }?
+ * ]} RuleOptions
+ */
+
+/**
+ * Checks whether the code has a hashbang comment or not.
+ * @param {import('./rule-module').PluginRuleContext<{RuleOptions: RuleOptions}>} context
+ */
+function hasHashbang(context) {
+    const sourceCode = getSourceCode(context)
+    return Boolean(sourceCode.text.startsWith(HASHBANG_ENV))
+}
+
+/** @param {import('./rule-module').PluginRuleContext<{RuleOptions: RuleOptions}>} context */
+function ignore(context) {
+    const options = context.options[0] || {}
+    const ignoreBin = options.ignoreBin ?? false
+    if (ignoreBin && hasHashbang(context)) {
+        // If the code has a hashbang comment, it is considered an executable file.
+        return true
+    }
+
+    const filePath = context.filename ?? context.getFilename()
+    if (filePath === "<input>") {
+        // The file path is "<input>" (not specified), so it will be ignored.
+        return true
+    }
+    const originalAbsolutePath = path.resolve(filePath)
+
+    // Find package.json
+    const packageJson = getPackageJson(originalAbsolutePath)
+    if (typeof packageJson?.filePath !== "string") {
+        // The file is not in a package, so it will be ignored.
+        return true
+    }
+
+    // Convert by convertPath option
+    const packageDirectory = path.dirname(packageJson.filePath)
+    const convertedRelativePath = getConvertPath(context)(
+        path
+            .relative(packageDirectory, originalAbsolutePath)
+            .replace(/\\/gu, "/")
+    )
+    const convertedAbsolutePath = path.resolve(
+        packageDirectory,
+        convertedRelativePath
+    )
+
+    if (
+        ignoreBin &&
+        isBinFile(convertedAbsolutePath, packageJson.bin, packageDirectory)
+    ) {
+        // The file is defined in the `bin` field of `package.json`
+        return true
+    }
+
+    // Check ignored or not
+    const npmignore = getNpmignore(convertedAbsolutePath)
+    if (npmignore.match(convertedRelativePath)) {
+        // The file is unpublished file, so it will be ignored.
+        return true
+    }
+
+    return false
+}
+
+/** @type {import('./rule-module').RuleModule<{RuleOptions: RuleOptions}>} */
+module.exports = {
+    meta: {
+        docs: {
+            description: "disallow top-level `await` in published modules",
+            recommended: false,
+            url: "https://github.com/eslint-community/eslint-plugin-n/blob/HEAD/docs/rules/no-top-level-await.md",
+        },
+        fixable: null,
+        messages: {
+            forbidden: "Top-level `await` is forbidden in published modules.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    ignoreBin: { type: "boolean" },
+                    convertPath: getConvertPath.schema,
+                },
+                additionalProperties: false,
+            },
+        ],
+        type: "problem",
+    },
+    create(context) {
+        if (ignore(context)) {
+            return {}
+        }
+        let functionDepth = 0
+        return {
+            ":function"() {
+                functionDepth++
+            },
+            ":function:exit"() {
+                functionDepth--
+            },
+            "AwaitExpression, ForOfStatement[await=true]"(node) {
+                if (functionDepth > 0) {
+                    // not top-level
+                    return
+                }
+                context.report({ node, messageId: "forbidden" })
+            },
+        }
+    },
+}

package/lib/util/get-full-type-name.js

@@ -0,0 +1,47 @@
+"use strict"
+
+const ts = (() => {
+    try {
+        // eslint-disable-next-line n/no-unpublished-require
+        return require("typescript")
+    } catch {
+        return null
+    }
+})()
+
+/**
+ * @param {import('typescript').Type | null} type
+ * @returns {string | null}
+ */
+module.exports = function getFullTypeName(type) {
+    if (ts === null || type === null) {
+        return null
+    }
+
+    /**
+     * @type {string[]}
+     */
+    let nameParts = []
+    let currentSymbol = type.getSymbol()
+    while (currentSymbol !== undefined) {
+        if (
+            currentSymbol.valueDeclaration?.kind === ts.SyntaxKind.SourceFile ||
+            currentSymbol.valueDeclaration?.kind ===
+                ts.SyntaxKind.ModuleDeclaration
+        ) {
+            break
+        }
+
+        nameParts.unshift(currentSymbol.getName())
+        currentSymbol =
+            /** @type {import('typescript').Symbol & {parent: import('typescript').Symbol | undefined}} */ (
+                currentSymbol
+            ).parent
+    }
+
+    if (nameParts.length === 0) {
+        return null
+    }
+
+    return nameParts.join(".")
+}

package/lib/util/get-parser-services.js

@@ -0,0 +1,24 @@
+"use strict"
+
+const {
+    getParserServices: getParserServicesFromTsEslint,
+} = require("@typescript-eslint/utils/eslint-utils")
+
+/**
+ * Get the TypeScript parser services.
+ * If TypeScript isn't present, returns `null`.
+ *
+ * @param {import('eslint').Rule.RuleContext} context - rule context
+ * @returns {import('@typescript-eslint/parser').ParserServices | null}
+ */
+module.exports = function getParserServices(context) {
+    // Not using tseslint parser?
+    if (
+        context.sourceCode.parserServices?.esTreeNodeToTSNodeMap == null ||
+        context.sourceCode.parserServices.tsNodeToESTreeNodeMap == null
+    ) {
+        return null
+    }
+
+    return getParserServicesFromTsEslint(/** @type {any} */ (context), true)
+}

package/lib/util/get-type-of-node.js

@@ -0,0 +1,21 @@
+"use strict"
+
+/**
+ * Get the type of a node.
+ * If TypeScript isn't present, returns `null`.
+ *
+ * @param {import('estree').Node} node - A node
+ * @param {import('@typescript-eslint/parser').ParserServices} parserServices - A parserServices
+ * @returns {import('typescript').Type | null}
+ */
+module.exports = function getTypeOfNode(node, parserServices) {
+    const { esTreeNodeToTSNodeMap, program } = parserServices
+    if (program === null) {
+        return null
+    }
+    const tsNode = esTreeNodeToTSNodeMap.get(/** @type {any} */ (node))
+    const checker = program.getTypeChecker()
+    const nodeType = checker.getTypeAtLocation(tsNode)
+    const constrained = checker.getBaseConstraintOfType(nodeType)
+    return constrained ?? nodeType
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-n",
-    "version": "17.18.0",
+    "version": "17.19.0",
     "description": "Additional ESLint's rules for Node.js",
     "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -18,21 +18,23 @@
     },
     "dependencies": {
         "@eslint-community/eslint-utils": "^4.5.0",
+        "@typescript-eslint/utils": "^8.26.1",
         "enhanced-resolve": "^5.17.1",
         "eslint-plugin-es-x": "^7.8.0",
         "get-tsconfig": "^4.8.1",
         "globals": "^15.11.0",
         "ignore": "^5.3.2",
         "minimatch": "^9.0.5",
-        "semver": "^7.6.3"
+        "semver": "^7.6.3",
+        "ts-declaration-location": "^1.0.6"
     },
     "devDependencies": {
         "@eslint/js": "^9.14.0",
         "@types/eslint": "^9.6.1",
         "@types/estree": "^1.0.6",
         "@types/node": "^20.17.5",
-        "@typescript-eslint/parser": "^8.12.2",
-        "@typescript-eslint/typescript-estree": "^8.12.2",
+        "@typescript-eslint/parser": "^8.26.1",
+        "@typescript-eslint/typescript-estree": "^8.26.1",
         "eslint": "^9.14.0",
         "eslint-config-prettier": "^9.1.0",
         "eslint-doc-generator": "^1.7.1",
@@ -120,4 +122,4 @@
     "imports": {
         "#test-helpers": "./tests/test-helpers.js"
     }
-}
+}