eslint-rule-forge 0.5.0 → 0.5.1

package/README.md

@@ -129,20 +129,20 @@ The range and the text of a node leave out the parentheses written around it.
 
 ## Imports and bindings
 
-| Helper                  | What it gives                                                                                        |
-| :---------------------- | :--------------------------------------------------------------------------------------------------- |
-| `getImportDeclarations` | every `import … from '<module>'` in the file, not only the first                                     |
-| `getNamedImports`       | the export names those declarations import                                                           |
-| `getImportedLocalName`  | the local name an export is imported as (`'y'` for `import { x as y }`)                              |
-| `importedNameOf`        | the export name an import specifier imports (`'x'` for `import { x as y }`)                          |
-| `buildCalleeResolver`   | which export a callee calls, through aliases, namespace imports and type wrappers                    |
-| `bindValueImports`      | the local names to write for exports, and the edits binding them as values (in the existing import)  |
-| `buildNamedImportFix`   | a fix inserting a new `import { … } from '<module>';` after the directive prologue                   |
-| `addTypeImports`        | the edits importing types: into an `import type { … }`, else as `type X` into another import         |
-| `addToImportBraces`     | a fix adding specifiers to a declaration's braces, empty ones included, or `undefined` without any   |
-| `hasForeignBinding`     | whether a name, at a node, is bound to something other than the module's import (a fix must give up) |
-| `isLocallyBound`        | whether a name, at a node, is declared in the file rather than a global or a standard-library type   |
-| `hasCommentWithin`      | whether a comment inside a node lies in ranges a fix would delete (the fix must give up)             |
+| Helper                  | What it gives                                                                                                                                   |
+| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getImportDeclarations` | every `import … from '<module>'` in the file, not only the first                                                                                |
+| `getNamedImports`       | the export names those declarations import                                                                                                      |
+| `getImportedLocalName`  | the local name an export is imported as (`'y'` for `import { x as y }`)                                                                         |
+| `importedNameOf`        | the export name an import specifier imports (`'x'` for `import { x as y }`)                                                                     |
+| `buildCalleeResolver`   | which export a callee calls, through aliases, namespace imports and type wrappers                                                               |
+| `bindValueImports`      | the local names to write for exports, and the edits binding them as values (in the existing import)                                             |
+| `buildNamedImportFix`   | a fix inserting a new `import { … } from '<module>';` after the directive prologue                                                              |
+| `addTypeImports`        | the edits importing types: into an `import type { … }`, else as `type X` into another import                                                    |
+| `addToImportBraces`     | a fix adding specifiers to a declaration's braces, empty ones included, or `undefined` without any                                              |
+| `hasForeignBinding`     | whether a name, at a node, is bound to something other than the module's import (a fix must give up); a nested type-only binding does not count |
+| `isLocallyBound`        | whether a name, at a node, is declared in the file rather than a global or a standard-library type                                              |
+| `hasCommentWithin`      | whether a comment inside a node lies in ranges a fix would delete (the fix must give up)                                                        |
 
 ```ts
 import type { TSESLint } from '@typescript-eslint/utils';

package/dist/bindings.d.mts

@@ -1,4 +1,4 @@
-import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import { TSESLint, type TSESTree } from '@typescript-eslint/utils';
 /**
  * Whether `name`, read at `node`, resolves to something this file writes down —
  * a declaration, a parameter, an import — rather than to a global or a
@@ -16,7 +16,13 @@ export declare const isLocallyBound: (sourceCode: TSESLint.SourceCode, node: TSE
  * has to give up then, because the name would refer to that binding instead.
  *
  * The innermost binding decides: an import from `moduleName` at the top of the
- * file does not help a name a function shadows around `node`.
+ * file does not help a name a function shadows around `node`. A binding with no
+ * value meaning inside the file — a type parameter, a local type alias or
+ * interface — is passed over, since a type does not shadow a value or the head
+ * of a qualified name. At the top of the file it still counts: the import a fix
+ * adds there conflicts with it when the export has a type meaning too. A fix
+ * that writes the name alone in a type position, where such a binding does
+ * capture it, has to check for one itself.
  */
 export declare const hasForeignBinding: (sourceCode: TSESLint.SourceCode, node: TSESTree.Node, name: string, moduleName: string) => boolean;
 //# sourceMappingURL=bindings.d.mts.map

package/dist/bindings.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.d.mts","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAIlC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,eACb,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,KACX,OAIF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAChB,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,cACA,MAAM,KACjB,OAIF,CAAC"}
+{"version":3,"file":"bindings.d.mts","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EAGL,QAAQ,EACR,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAIlC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,eACb,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,KACX,OAIF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,eAChB,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,cACA,MAAM,KACjB,OAIF,CAAC"}

package/dist/bindings.mjs

@@ -1,4 +1,4 @@
-import { AST_NODE_TYPES, ASTUtils, } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES, ASTUtils, TSESLint, } from '@typescript-eslint/utils';
 
 
 
@@ -22,14 +22,45 @@ export const isLocallyBound = (sourceCode, node, name) => {
 
 
 
+
+
+
+
+
+
 export const hasForeignBinding = (sourceCode, node, name, moduleName) => {
-    const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+    const variable = findShadowingVariable(sourceCode.getScope(node), name);
     return variable?.defs.some((def) => !isImportFrom(def, moduleName)) ?? false;
 };
 
 
 
 
+
+const isTypeOnly = (variable) => variable.defs.length > 0 &&
+    variable.defs.every((def) => def.type === TSESLint.Scope.DefinitionType.Type);
+
+
+
+
+const isTopLevel = (scope) => scope.block.type === AST_NODE_TYPES.Program;
+
+
+
+
+
+const findShadowingVariable = (scope, name) => {
+    const variable = scope.set.get(name);
+    return variable !== undefined && (!isTypeOnly(variable) || isTopLevel(scope))
+        ? variable
+        : scope.upper === null
+            ? undefined
+            : findShadowingVariable(scope.upper, name);
+};
+
+
+
+
 const isImportFrom = (def, moduleName) => (def.node.type === AST_NODE_TYPES.ImportSpecifier ||
     def.node.type === AST_NODE_TYPES.ImportDefaultSpecifier ||
     def.node.type === AST_NODE_TYPES.ImportNamespaceSpecifier) &&

package/dist/bindings.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.mjs","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,QAAQ,GAGT,MAAM,0BAA0B,CAAC;AAElC,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACH,EAAE;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACZ,UAAkB,EACT,EAAE;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,IAAI,KAAK,CAAC;AAC/E,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,YAAY,GAAG,CACnB,GAA8B,EAC9B,UAAkB,EACT,EAAE,CACX,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;IAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,sBAAsB;IACvD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,wBAAwB,CAAC;IAC5D,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,iBAAiB;IACzD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,UAAU,CAAC"}
+{"version":3,"file":"bindings.mjs","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,QAAQ,EACR,QAAQ,GAET,MAAM,0BAA0B,CAAC;AAElC,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACH,EAAE;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACZ,UAAkB,EACT,EAAE;IACX,MAAM,QAAQ,GAAG,qBAAqB,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,IAAI,KAAK,CAAC;AAC/E,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,QAAiC,EAAW,EAAE,CAChE,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,KAA2B,EAAW,EAAE,CAC1D,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO,CAAC;AAE9C;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,CAC5B,KAA2B,EAC3B,IAAY,EACyB,EAAE;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAErC,OAAO,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QAC3E,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI;YACpB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,YAAY,GAAG,CACnB,GAA8B,EAC9B,UAAkB,EACT,EAAE,CACX,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;IAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,sBAAsB;IACvD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,wBAAwB,CAAC;IAC5D,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,iBAAiB;IACzD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,UAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-rule-forge",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "private": false,
   "description": "Helpers for writing typescript-eslint rules that see through type wrappers and parentheses, and resolve what a file imports.",
   "keywords": [
@@ -41,14 +41,14 @@
     "@typescript-eslint/rule-tester": "8.72.0",
     "dedent": "1.7.2",
     "eslint": "10.13.0",
-    "eslint-config-typed": "7.3.0",
-    "eslint-plugin-ts-fortress": "1.3.12",
-    "eslint-plugin-ts-type-forge": "0.8.17",
+    "eslint-config-typed": "7.4.0",
+    "eslint-plugin-ts-fortress": "1.3.13",
+    "eslint-plugin-ts-type-forge": "0.8.18",
     "prettier": "3.9.10",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
-    "ts-data-forge": "14.10.1",
-    "ts-repo-utils": "10.7.1"
+    "ts-data-forge": "14.11.0",
+    "ts-repo-utils": "10.7.2"
   },
   "peerDependencies": {
     "eslint": ">=9.0.0",

package/src/bindings.mts

@@ -1,7 +1,7 @@
 import {
   AST_NODE_TYPES,
   ASTUtils,
-  type TSESLint,
+  TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
 
@@ -33,7 +33,13 @@ export const isLocallyBound = (
  * has to give up then, because the name would refer to that binding instead.
  *
  * The innermost binding decides: an import from `moduleName` at the top of the
- * file does not help a name a function shadows around `node`.
+ * file does not help a name a function shadows around `node`. A binding with no
+ * value meaning inside the file — a type parameter, a local type alias or
+ * interface — is passed over, since a type does not shadow a value or the head
+ * of a qualified name. At the top of the file it still counts: the import a fix
+ * adds there conflicts with it when the export has a type meaning too. A fix
+ * that writes the name alone in a type position, where such a binding does
+ * capture it, has to check for one itself.
  */
 export const hasForeignBinding = (
   sourceCode: TSESLint.SourceCode,
@@ -41,11 +47,45 @@ export const hasForeignBinding = (
   name: string,
   moduleName: string,
 ): boolean => {
-  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+  const variable = findShadowingVariable(sourceCode.getScope(node), name);
 
   return variable?.defs.some((def) => !isImportFrom(def, moduleName)) ?? false;
 };
 
+/**
+ * Whether every definition of `variable` is a type parameter, type alias or
+ * interface. Read from `def.type` rather than `isValueVariable`, which ESLint's
+ * own scope manager, used with its default parser, does not have.
+ */
+const isTypeOnly = (variable: TSESLint.Scope.Variable): boolean =>
+  variable.defs.length > 0 &&
+  variable.defs.every((def) => def.type === TSESLint.Scope.DefinitionType.Type);
+
+/**
+ * Whether `scope` is the file's own, where an added import lands: the module or
+ * global scope, or the function scope a CommonJS file wraps around them.
+ */
+const isTopLevel = (scope: TSESLint.Scope.Scope): boolean =>
+  scope.block.type === AST_NODE_TYPES.Program;
+
+/**
+ * The innermost variable named `name` from `scope` outwards that a value of
+ * that name written in `scope` would meet: one with a value meaning, or any at
+ * the top of the file.
+ */
+const findShadowingVariable = (
+  scope: TSESLint.Scope.Scope,
+  name: string,
+): TSESLint.Scope.Variable | undefined => {
+  const variable = scope.set.get(name);
+
+  return variable !== undefined && (!isTypeOnly(variable) || isTopLevel(scope))
+    ? variable
+    : scope.upper === null
+      ? undefined
+      : findShadowingVariable(scope.upper, name);
+};
+
 /**
  * Whether `def` is a binding an `import … from '<moduleName>'` declaration
  * introduces.