chore: unifi TraceMap

Author: scagood

lib/eslint-utils.d.ts

@@ -28,11 +28,14 @@ declare module "@eslint-community/eslint-utils" {
         export { ESM };
     }
     type ReferenceType = typeof READ | typeof CALL | typeof CONSTRUCT;
-    type TraceMap<Info extends unknown = boolean> =
-        & { [key: string]: TraceMap; }
-        & Partial<Record<ReferenceType, Info>>;
+    type TraceMap<Info extends unknown> = {
+        [READ]?: Info;
+        [CALL]?: Info;
+        [CONSTRUCT]?: Info;
+        [key: string]: TraceMap<Info>;
+    }
     type RichNode = eslint.Rule.Node | Node;
-    type Reference<Info extends unknown = boolean> = {
+    type Reference<Info extends unknown> = {
         node: RichNode;
         path: string[];
         type: ReferenceType;

lib/rules/no-unsupported-features/node-builtins.js

@@ -16,10 +16,15 @@ const {
     NodeBuiltinModules,
 } = require("../../unsupported-features/node-builtins.js")
 
+/**
+ * @typedef {Object} TraceMap
+ * @property {import('@eslint-community/eslint-utils').TraceMap<boolean>} globals
+ * @property {import('@eslint-community/eslint-utils').TraceMap<boolean>} modules
+ */
 const trackMap = {
     globals: {
         queueMicrotask: {
-            [READ]: { supported: ["12.0.0"], experimental: "11.0.0" },
+            [READ]: { supported: ["12.0.0"], experimental: ["11.0.0"] },
         },
         require: {
             resolve: {

lib/rules/prefer-node-protocol.js

@@ -13,6 +13,14 @@ const mergeVisitorsInPlace = require("../util/merge-visitors-in-place")
 
 const messageId = "preferNodeProtocol"
 
+const supportedRangeForEsm = /** @type {import('semver').Range} */ (
+    getSemverRange("^12.20.0 || >= 14.13.1")
+)
+const supportedRangeForCjs = /** @type {import('semver').Range} */ (
+    getSemverRange("^14.18.0 || >= 16.0.0")
+)
+
+/** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
     meta: {
         docs: {
@@ -37,6 +45,13 @@ module.exports = {
         type: "suggestion",
     },
     create(context) {
+        /**
+         * @param {import('estree').Node} node
+         * @param {object} options
+         * @param {string} options.name
+         * @param {number} options.argumentsLength
+         * @returns {node is import('estree').CallExpression}
+         */
         function isCallExpression(node, { name, argumentsLength }) {
             if (node?.type !== "CallExpression") {
                 return false
@@ -60,40 +75,54 @@ module.exports = {
             return true
         }
 
+        /**
+         * @param {import('estree').Node} node
+         * @returns {node is import('estree').Literal}
+         */
         function isStringLiteral(node) {
             return node?.type === "Literal" && typeof node.type === "string"
         }
 
+        /**
+         * @param {import('estree').Node | undefined} node
+         * @returns {node is import('estree').CallExpression}
+         */
         function isStaticRequire(node) {
             return (
+                node != null &&
                 isCallExpression(node, {
                     name: "require",
                     argumentsLength: 1,
-                }) && isStringLiteral(node.arguments[0])
+                }) &&
+                isStringLiteral(node.arguments[0])
             )
         }
 
+        /**
+         * @param {import('eslint').Rule.RuleContext} context
+         * @param {import('../util/import-target.js').ModuleStyle} moduleStyle
+         * @returns {Boolean}
+         */
         function isEnablingThisRule(context, moduleStyle) {
             const version = getConfiguredNodeVersion(context)
 
-            const supportedVersionForEsm = "^12.20.0 || >= 14.13.1"
             // Only check Node.js version because this rule is meaningless if configured Node.js version doesn't match semver range.
-            if (!version.intersects(getSemverRange(supportedVersionForEsm))) {
+            if (!version.intersects(supportedRangeForEsm)) {
                 return false
             }
 
-            const supportedVersionForCjs = "^14.18.0 || >= 16.0.0"
             // Only check when using `require`
             if (
                 moduleStyle === "require" &&
-                !version.intersects(getSemverRange(supportedVersionForCjs))
+                !version.intersects(supportedRangeForCjs)
             ) {
                 return false
             }
 
             return true
         }
 
+        /** @type {import('../util/import-target.js')[]} */
         const targets = []
         return [
             visitImport(context, { includeCore: true }, importTargets => {
@@ -117,7 +146,7 @@ module.exports = {
                             continue
                         }
 
-                        const { value } = node
+                        const { value } = /** @type {{ value: string }}*/ (node)
                         if (
                             typeof value !== "string" ||
                             value.startsWith("node:") ||
@@ -134,7 +163,8 @@ module.exports = {
                                 moduleName: value,
                             },
                             fix(fixer) {
-                                const firstCharacterIndex = node.range[0] + 1
+                                const firstCharacterIndex =
+                                    (node?.range?.[0] ?? 0) + 1
                                 return fixer.replaceTextRange(
                                     [firstCharacterIndex, firstCharacterIndex],
                                     "node:"

lib/rules/prefer-promises/dns.js

@@ -10,7 +10,7 @@ const {
     ReferenceTracker,
 } = require("@eslint-community/eslint-utils")
 
-/** @type {import('@eslint-community/eslint-utils').TraceMap} */
+/** @type {import('@eslint-community/eslint-utils').TraceMap<boolean>} */
 const trackMap = {
     dns: {
         lookup: { [CALL]: true },

lib/rules/prefer-promises/fs.js

@@ -6,7 +6,7 @@
 
 const { CALL, ReferenceTracker } = require("@eslint-community/eslint-utils")
 
-/** @type {import('@eslint-community/eslint-utils').TraceMap} */
+/** @type {import('@eslint-community/eslint-utils').TraceMap<boolean>} */
 const trackMap = {
     fs: {
         access: { [CALL]: true },

lib/unsupported-features/types.js

@@ -14,8 +14,14 @@
  * @property {string[]} [supported]     The node versions in which stable support was added
  * @property {string[]} [deprecated]    The node versions in which support was removed
  */
+
+/**
+ * @typedef {import('@eslint-community/eslint-utils').TraceMap<SupportInfo>} SupportVersionTree
+ */
 /**
- * @typedef {{ [key in UTIL_SYMBOL]?: SupportInfo } & { [key: string]: SupportVersionTree }} SupportVersionTree
+ * @typedef {Object} SupportVersionTraceMap
+ * @property {SupportVersionTree} globals
+ * @property {SupportVersionTree} modules
  */
 
 module.exports = {}

lib/util/check-prefer-global.js

@@ -7,9 +7,9 @@
 const { ReferenceTracker } = require("@eslint-community/eslint-utils")
 
 /**
- * @typedef {Object} TrackMap
- * @property {import('@eslint-community/eslint-utils').TraceMap} globals
- * @property {import('@eslint-community/eslint-utils').TraceMap} modules
+ * @typedef {Object} TraceMap
+ * @property {import('@eslint-community/eslint-utils').TraceMap<boolean>} globals
+ * @property {import('@eslint-community/eslint-utils').TraceMap<boolean>} modules
  */
 
 /**
@@ -19,7 +19,7 @@ class Verifier {
     /**
      * Initialize this instance.
      * @param {import('eslint').Rule.RuleContext} context The rule context to report.
-     * @param {TrackMap} trackMap The track map.
+     * @param {TraceMap} trackMap The track map.
      */
     constructor(context, trackMap) {
         this.context = context
@@ -72,7 +72,7 @@ class Verifier {
 
 /**
  * @param {import('eslint').Rule.RuleContext} context
- * @param {TrackMap} trackMap  [description]
+ * @param {TraceMap} trackMap  [description]
  * @returns {void}
  */
 module.exports = function checkForPreferGlobal(context, trackMap) {

lib/util/check-unsupported-builtins.js

@@ -10,12 +10,6 @@ const getConfiguredNodeVersion = require("./get-configured-node-version")
 const getSemverRange = require("./get-semver-range")
 const unprefixNodeColon = require("./unprefix-node-colon")
 
-/**
- * @typedef {Object} SupportInfo
- * @property {string[]} supported The stably supported version. If `null` is present, it hasn't been supported yet.
- * @property {string} [experimental] The added version as experimental.
- */
-
 /**
  * Parses the options.
  * @param {import('eslint').Rule.RuleContext} context The rule context.
@@ -34,7 +28,7 @@ function parseOptions(context) {
 
 /**
  * Check if it has been supported.
- * @param {SupportInfo} info The support info.
+ * @param {import('../unsupported-features/types.js').SupportInfo} info The support info.
  * @param {import('semver').Range} configured The configured version range.
  */
 function isSupported({ supported }, configured) {
@@ -61,7 +55,7 @@ function isSupported({ supported }, configured) {
 
 /**
  * Get the formatted text of a given supported version.
- * @param {SupportInfo} info The support info.
+ * @param {import('../unsupported-features/types.js').SupportInfo} info The support info.
  * @returns {string | undefined}
  */
 function supportedVersionToString({ supported }) {
@@ -80,16 +74,10 @@ function supportedVersionToString({ supported }) {
     return `${latest} (backported: ${backportString})`
 }
 
-/**
- * @typedef {Object} TrackMap
- * @property {import('@eslint-community/eslint-utils').TraceMap<SupportInfo>} modules
- * @property {import('@eslint-community/eslint-utils').TraceMap<SupportInfo>} globals
- */
-
 /**
  * Verify the code to report unsupported APIs.
  * @param {import('eslint').Rule.RuleContext} context The rule context.
- * @param {TrackMap} trackMap The map for APIs to report.
+ * @param {import('../unsupported-features/types.js').SupportVersionTraceMap} trackMap The map for APIs to report.
  * @returns {void}
  */
 module.exports.checkUnsupportedBuiltins = function checkUnsupportedBuiltins(

lib/util/extend-trackmap-with-node-prefix.js

@@ -4,10 +4,10 @@ const isBuiltinModule = require("is-builtin-module")
 
 /**
  * Extend trackMap.modules with `node:` prefixed modules
- * @param {import('@eslint-community/eslint-utils').TraceMap} modules Like `{assert: foo}`
- * @returns {import('@eslint-community/eslint-utils').TraceMap} Like `{assert: foo}, "node:assert": foo}`
+ * @param {import('@eslint-community/eslint-utils').TraceMap<boolean>} modules Like `{assert: foo}`
+ * @returns {import('@eslint-community/eslint-utils').TraceMap<boolean>} Like `{assert: foo}, "node:assert": foo}`
  */
-module.exports = function extendTrackMapWithNodePrefix(modules) {
+module.exports = function extendTraceMapWithNodePrefix(modules) {
     const ret = {
         ...modules,
         ...Object.fromEntries(

lib/util/import-target.js

@@ -96,7 +96,7 @@ module.exports = class ImportTarget {
 
         /**
          * The node of a `require()` or a module declaraiton.
-         * @type {import('estree').Node}
+         * @type {import('estree').Node & { parent?: import('estree').Node }}
          */
         this.node = node