eslint-plugin-n 18.0.1 → 18.1.0

package/README.md

@@ -10,7 +10,7 @@ Additional ESLint rules for Node.js
 
 ## 🎨 Playground
 
-[online-playground](https://eslint-online-playground.netlify.app/#eNp1jzEOwjAMRa9SeWFpYS8rOwtiIQxRalWBxIniFIFQ747bCASV2BK/Lz//J3AyG7xrHx2uLwwtWB9DytXKW2ZLfVP+q60iqGGN7CzlZCQbSNJPRVWlAO8ZqWMFbXWS3xxqE5rgvcyxU1BLKrqht9TS5oec67Kj0PcO+gI6MaZ9zDYUPEtnrfH6iIkFTHMFTmfkLLZ3gsOQDB4eEUvAh25w8p74qGiUTlGbq+6n9t+NOrztME4nkrG40M79/hgLbEqbZnHXRzu+APYwfks=)
+[online-playground](https://eslint-online-playground.netlify.app/#eNptjzFuwzAMRa8icGqB2NndtbcoOxgybaiVSUGSgxSG717KUoAMWSiReJ//c4cU7ZXu4xo89T8JBrDCSbTxsryFKJZS6olv7x/IcAFK3nHuFZrdUgVuDRKzYTNHWQ02pAt+Wxx3jKBKZLqf1ETzuPlsvpCN2UsxppJpMLsuOS51GDdPZVQ7o3v5ytK1RJ0mQhiKW4wSESp2lEfLdw0bRvs7LuUuYQ167kLIf4GqdpVJXRBOS4SJbp8UiCdi6ygVptk/jqoyP2ZK+m9JX1z8TLVIBxz/MqF45g==)
 
 ## 💿 Install & Usage
 
@@ -34,8 +34,10 @@ import node from "eslint-plugin-n"
 import {defineConfig} from "eslint/config"
 
 export default defineConfig([
-    plugins: {n: node},
-    extends: ["n/recommended-module"],
+    {
+        plugins: {n: node},
+        extends: ["n/recommended-module"],
+    }
 ])
 ```
 
@@ -46,10 +48,12 @@ import node from "eslint-plugin-n"
 import {defineConfig} from "eslint/config"
 
 export default defineConfig([
-    plugins: {n: node},
-    rules: {
-        "n/no-unsupported-features/es-builtins": "error",
-    },
+    {
+        plugins: {n: node},
+        rules: {
+            "n/no-unsupported-features/es-builtins": "error",
+        },
+    }
 ])
 ```
 
@@ -73,9 +77,10 @@ The rules get the supported Node.js version range from the following, falling ba
 1. Rule configuration `version`
 2. ESLint [shared setting](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings) `node.version`
 3. `package.json` [`engines`] field
-4. `>=16.0.0`
+4. `package.json` [`devEngines.runtime`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines) field (when `name` is `"node"`)
+5. `>=16.0.0`
 
-If you omit the [engines] field, this rule chooses `>=16.0.0` as the configured Node.js version since `16` is the maintained lts (see also [Node.js Release Working Group](https://github.com/nodejs/Release#readme)).
+If you omit both the [engines] field and the `devEngines.runtime` field (with `name` set to `"node"`), this rule chooses `>=16.0.0` as the configured Node.js version since `16` is the maintained lts (see also [Node.js Release Working Group](https://github.com/nodejs/Release#readme)).
 
 For Node.js packages, using the [`engines`] field is recommended because it's the official way to indicate support:
 
@@ -188,8 +193,10 @@ import node from "eslint-plugin-n"
 import {defineConfig} from "eslint/config"
 
 export default defineConfig([
-    plugins: {n: node},
-    extends: ["n/mixed-esm-and-cjs"],
+    {
+        plugins: {n: node},
+        extends: ["n/mixed-esm-and-cjs"],
+    },
 ])
 ```
 

package/lib/util/check-extraneous.js

@@ -3,9 +3,220 @@
  * See LICENSE file in root directory for full license.
  */
 
+import path from "node:path"
+import globrex from "globrex"
+import { Cache } from "./cache.js"
 import { getAllowModules } from "./get-allow-modules.js"
 import { getPackageJson } from "./get-package-json.js"
 
+const workspacePackageJsonsCache = new Cache()
+const workspacePatternMatcherCache = new Cache()
+
+/**
+ * @param {unknown} workspaces - The package.json workspaces value.
+ * @returns {string[]} Workspace package patterns.
+ */
+function getWorkspacePatterns(workspaces) {
+    if (Array.isArray(workspaces)) {
+        return workspaces.map(String)
+    }
+
+    if (
+        workspaces != null &&
+        typeof workspaces === "object" &&
+        "packages" in workspaces &&
+        Array.isArray(workspaces.packages)
+    ) {
+        return workspaces.packages.map(String)
+    }
+
+    return []
+}
+
+/**
+ * @param {string} pattern - A package.json workspace pattern.
+ * @returns {string} A pattern comparable to path.posix-style relative paths.
+ */
+function normalizeWorkspacePattern(pattern) {
+    return pattern
+        .replace(/\\/gu, "/")
+        .replace(/^\.\//u, "")
+        .replace(/\/+$/u, "")
+}
+
+/**
+ * @param {string} relativePath - A relative package directory path.
+ * @param {string[]} patterns - Workspace package patterns.
+ * @returns {boolean} Whether the path is included by the patterns.
+ */
+function matchesWorkspacePattern(relativePath, patterns) {
+    let matched = false
+
+    for (const rawPattern of patterns) {
+        const negated = rawPattern.startsWith("!")
+        const pattern = normalizeWorkspacePattern(
+            negated ? rawPattern.slice(1) : rawPattern
+        )
+
+        if (pattern === "") {
+            continue
+        }
+
+        if (getWorkspacePatternMatcher(pattern).test(relativePath)) {
+            if (negated) {
+                return false
+            }
+
+            matched = true
+        }
+    }
+
+    return matched
+}
+
+/**
+ * @param {string} pattern - A normalized package.json workspace pattern.
+ * @returns {RegExp} A matcher for package paths.
+ */
+function getWorkspacePatternMatcher(pattern) {
+    let matcher = workspacePatternMatcherCache.get(pattern)
+
+    if (matcher == null) {
+        matcher = globrex(pattern, {
+            extended: true,
+            globstar: true,
+        }).regex
+        workspacePatternMatcherCache.set(pattern, matcher)
+    }
+
+    return matcher
+}
+
+/**
+ * @param {string} dir - A directory path.
+ * @returns {import('type-fest').JsonObject|null} The package.json in the directory, if present.
+ */
+function getPackageJsonInDirectory(dir) {
+    const packageInfo = getPackageJson(path.join(dir, "__placeholder__.js"))
+    const filePath = path.join(dir, "package.json")
+
+    return packageInfo != null && packageInfo.filePath === filePath
+        ? packageInfo
+        : null
+}
+
+/**
+ * @param {import('type-fest').JsonObject} packageInfo - A package.json object.
+ * @param {import('type-fest').JsonObject} workspacePackageInfo - An ancestor package.json object.
+ * @returns {boolean} Whether the package is in the ancestor's workspace.
+ */
+function isWorkspacePackage(packageInfo, workspacePackageInfo) {
+    if (
+        typeof packageInfo.filePath !== "string" ||
+        typeof workspacePackageInfo.filePath !== "string"
+    ) {
+        return false
+    }
+
+    const packageDir = path.dirname(packageInfo.filePath)
+    const workspaceDir = path.dirname(workspacePackageInfo.filePath)
+    const relativePath = path
+        .relative(workspaceDir, packageDir)
+        .replace(/\\/gu, "/")
+
+    if (
+        relativePath === "" ||
+        relativePath === ".." ||
+        relativePath.startsWith("../") ||
+        path.isAbsolute(relativePath)
+    ) {
+        return false
+    }
+
+    return matchesWorkspacePattern(
+        relativePath,
+        getWorkspacePatterns(workspacePackageInfo.workspaces)
+    )
+}
+
+/**
+ * @param {import('type-fest').JsonObject} packageInfo - A package.json object.
+ * @returns {import('type-fest').JsonObject[]} Matching workspace root package.json objects.
+ */
+function getWorkspacePackageJsons(packageInfo) {
+    if (typeof packageInfo.filePath !== "string") {
+        return []
+    }
+
+    const cached = workspacePackageJsonsCache.get(packageInfo.filePath)
+    if (cached != null) {
+        return cached
+    }
+
+    const workspacePackageJsons = []
+    let dir = path.resolve(path.dirname(packageInfo.filePath), "..")
+    let prevDir = ""
+
+    do {
+        const workspacePackageInfo = getPackageJsonInDirectory(dir)
+
+        if (
+            workspacePackageInfo != null &&
+            isWorkspacePackage(packageInfo, workspacePackageInfo)
+        ) {
+            workspacePackageJsons.push(workspacePackageInfo)
+            break
+        }
+
+        prevDir = dir
+        dir = path.resolve(dir, "..")
+    } while (dir !== prevDir)
+
+    workspacePackageJsonsCache.set(packageInfo.filePath, workspacePackageJsons)
+    return workspacePackageJsons
+}
+
+/**
+ * @param {import('type-fest').JsonObject} packageInfo - A package.json object.
+ * @returns {string[]} Package and dependency names.
+ */
+function getPackageNames(packageInfo) {
+    return (
+        typeof packageInfo.name === "string" ? [packageInfo.name] : []
+    ).concat(
+        getDependencyNames(packageInfo.dependencies),
+        getDependencyNames(packageInfo.devDependencies),
+        getDependencyNames(packageInfo.peerDependencies),
+        getDependencyNames(packageInfo.optionalDependencies)
+    )
+}
+
+/**
+ * @param {unknown} dependencies - A package.json dependency object.
+ * @returns {string[]} Dependency names.
+ */
+function getDependencyNames(dependencies) {
+    return dependencies != null &&
+        typeof dependencies === "object" &&
+        Array.isArray(dependencies) === false
+        ? Object.keys(dependencies)
+        : []
+}
+
+/**
+ * Get the matching DefinitelyTyped package name for a module.
+ * @param {string} moduleName - An npm module name.
+ * @returns {string}
+ */
+function getTypesPackageName(moduleName) {
+    if (moduleName.startsWith("@")) {
+        const [scope, name] = moduleName.slice(1).split("/")
+        return `@types/${scope}__${name}`
+    }
+
+    return `@types/${moduleName}`
+}
+
 /**
  * Checks whether or not each requirement target is published via package.json.
  *
@@ -24,11 +235,8 @@ export function checkExtraneous(context, filePath, targets) {
 
     const allowed = new Set(getAllowModules(context))
     const dependencies = new Set(
-        [packageInfo.name].concat(
-            Object.keys(packageInfo.dependencies || {}),
-            Object.keys(packageInfo.devDependencies || {}),
-            Object.keys(packageInfo.peerDependencies || {}),
-            Object.keys(packageInfo.optionalDependencies || {})
+        getPackageNames(packageInfo).concat(
+            getWorkspacePackageJsons(packageInfo).flatMap(getPackageNames)
         )
     )
 
@@ -37,6 +245,10 @@ export function checkExtraneous(context, filePath, targets) {
             target.moduleName != null &&
             target.filePath != null &&
             !dependencies.has(target.moduleName) &&
+            !(
+                target.moduleStyle === "type" &&
+                dependencies.has(getTypesPackageName(target.moduleName))
+            ) &&
             !allowed.has(target.moduleName) &&
             // https://github.com/eslint-community/eslint-plugin-n/issues/379
             !target.hasTSAlias()

package/lib/util/get-configured-node-version.js

@@ -27,6 +27,9 @@ function getVersionRange(option) {
 /**
  * @typedef {{ [EngineName in 'npm' | 'node' | string]?: string }} Engines
  */
+/**
+ * @typedef {{ name?: string, version?: string, onFail?: string }} DevEngineEntry
+ */
 /**
  * Get the `engines.node` field of package.json.
  * @param {import('eslint').Rule.RuleContext} context The path to the current linting file.
@@ -45,12 +48,48 @@ function getEnginesNode(context) {
     }
 }
 
+/**
+ * Get the `devEngines.runtime` (`name: "node"`) version from package.json.
+ * `devEngines.runtime` may be a single object or an array of objects.
+ * See https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines
+ * @param {import('eslint').Rule.RuleContext} context The path to the current linting file.
+ * @returns {import("semver").Range | undefined} The range object of the matching `devEngines.runtime.version`.
+ */
+function getDevEnginesNode(context) {
+    const filename = context.filename
+    const info = getPackageJson(filename)
+    if (
+        info?.devEngines == null ||
+        typeof info.devEngines !== "object" ||
+        Array.isArray(info.devEngines) ||
+        !("runtime" in info.devEngines) ||
+        info.devEngines.runtime == null
+    ) {
+        return
+    }
+    const runtime = info.devEngines.runtime
+    const entries = /** @type {DevEngineEntry[]} */ (
+        Array.isArray(runtime) ? runtime : [runtime]
+    )
+    for (const entry of entries) {
+        if (
+            entry != null &&
+            typeof entry === "object" &&
+            entry.name === "node" &&
+            typeof entry.version === "string"
+        ) {
+            return getSemverRange(entry.version)
+        }
+    }
+}
+
 /**
  * Gets version configuration.
  *
  * 1. Parse a given version then return it if it's valid.
  * 2. Look package.json up and parse `engines.node` then return it if it's valid.
- * 3. Return `>=16.0.0`.
+ * 3. Look package.json up and parse `devEngines.runtime` (`name: "node"`) then return it if it's valid.
+ * 4. Return `>=16.0.0`.
  *
  * @param {import('eslint').Rule.RuleContext} context The version range text.
  * This will be used to look package.json up if `version` is not a valid version range.
@@ -64,6 +103,7 @@ export function getConfiguredNodeVersion(context) {
             /** @type {VersionOption} */ (context.settings?.node)
         ) ??
         getEnginesNode(context) ??
+        getDevEnginesNode(context) ??
         fallbackRange
     )
 }

package/lib/util/get-npmignore.js

@@ -102,7 +102,7 @@ function parseWhiteList(files) {
     for (const file of files) {
         if (typeof file === "string" && file) {
             const body = path.posix
-                .normalize(file.replace(/^!/u, ""))
+                .normalize(file.replace(/^[!/]/u, ""))
                 .replace(/\/+$/u, "")
 
             if (file.startsWith("!")) {

package/lib/util/get-package-json.js

@@ -12,8 +12,6 @@ const cache = new Cache()
 /**
  * Reads the `package.json` data in a given path.
  *
- * Don't cache the data.
- *
  * @param {string} dir - The path to a directory to read.
  * @returns {import('type-fest').JsonObject|null} The read `package.json` data, or null.
  */

package/lib/util/import-target.js

@@ -232,6 +232,15 @@ export class ImportTarget {
                     : "import"
             }
 
+            if (
+                (node.parent.type === "ExportAllDeclaration" ||
+                    node.parent.type === "ExportNamedDeclaration") &&
+                "exportKind" in node.parent &&
+                node.parent.exportKind === "type"
+            ) {
+                return "type"
+            }
+
             node = node.parent
         } while (node.parent)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-n",
-    "version": "18.0.1",
+    "version": "18.1.0",
     "description": "Additional ESLint's rules for Node.js",
     "engines": {
         "node": "^20.19.0 || ^22.13.0 || >=24"