feat: add types to ESLint Scope (#709)

* feat: add types to ESLint Scope

* fallback to `.d.cts` types

* add missing scopes

* add deprecations

* fixes

* fix tests

* more fixes

* type check source files

* make sure to use the latest versions of type dependencies

* explain unused imports

* remove dependency on `eslint` types

* Apply suggestions from code review

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Update packages/eslint-scope/lib/index.d.cts

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* update readme file

* update `type` parameter of `Scope` constructor

* Update packages/eslint-scope/lib/index.d.cts

* apply `mocha` globals to `*.test.*` files only

* move `@types/espree` to `devDependencies`

* stricter settings in `packages/eslint-scope/tests/types/tsconfig.json`

* remove redundant `exactOptionalPropertyTypes`

* add `@types/estree` dependency

* Apply suggestions from code review

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* inline `VisitorKeys` type

* optional `Reference` fields

* add `Variable` static properties

* add `Reference` static properties

* add `JSXIdentifier`

* add `attach()` and `detach()` to `ScopeManager`

* add `version`

* add JSDoc for `version`

* stricter return types for `isArgumentsMaterialized()` and `isThisMaterialized()`

* add `Referencer`

* Update packages/eslint-scope/tests/types/cjs-import.test.cts

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* build types before `lint:types`

* apply review suggestions

* Update packages/eslint-scope/lib/index.d.cts

Co-authored-by: 루밀LuMir <rpfos@naver.com>

* Update packages/eslint-scope/lib/scope.js

Co-authored-by: Michaël De Boey <info@michaeldeboey.be>

* use `unknown` in `updateDeeply()`

* update ESLint and re-enable tests

* remove `@types/espree` dependency

---------

Co-authored-by: 루밀LuMir <rpfos@naver.com>
Co-authored-by: Michaël De Boey <info@michaeldeboey.be>

Author: 3 people

.github/workflows/ci.yml

@@ -45,3 +45,18 @@ jobs:
       run: npm run build
     - name: Run tests
       run: npm run test
+  are-the-types-wrong:
+    name: Are the types wrong?
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'lts/*'
+      - name: Install dependencies
+        run: npm install
+      - name: Build types
+        run: npm run build:types
+      - name: Are the types wrong?
+        run: npm run lint:types

eslint.config.js

@@ -2,7 +2,9 @@ import { defineConfig, globalIgnores } from "eslint/config";
 import eslintConfigESLint from "eslint-config-eslint";
 import eslintConfigESLintFormatting from "eslint-config-eslint/formatting";
 import eslintPluginChaiFriendly from "eslint-plugin-chai-friendly";
+import * as expectType from "eslint-plugin-expect-type";
 import globals from "globals";
+import tsParser from "@typescript-eslint/parser";
 
 export default defineConfig([
     globalIgnores([
@@ -11,23 +13,20 @@ export default defineConfig([
         "**/coverage/",
         "packages/espree/tools/create-test-example.js"
     ]),
-    eslintConfigESLint,
-    eslintConfigESLintFormatting,
     {
-        files: ["packages/*/tests/lib/**"],
+        files: ["**/*.{,c}js"],
+        extends: [eslintConfigESLint, eslintConfigESLintFormatting]
+    },
+    {
+        files: ["packages/*/tests/**/*.test.{,c}js"],
         languageOptions: {
             globals: {
                 ...globals.mocha
             }
         }
     },
     {
-        files: ["packages/eslint-scope/tests/**"],
-        languageOptions: {
-            globals: {
-                ...globals.mocha
-            }
-        },
+        files: ["packages/eslint-scope/tests/**/*.{,c}js"],
         plugins: {
             "chai-friendly": eslintPluginChaiFriendly
         },
@@ -68,6 +67,21 @@ export default defineConfig([
             }
         }
     },
+    {
+        files: ["packages/eslint-scope/tests/types/*.{,c}ts"],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                project: ["packages/eslint-scope/tests/types/tsconfig.json"]
+            }
+        },
+        plugins: {
+            "expect-type": expectType
+        },
+        rules: {
+            "expect-type/expect": "error"
+        }
+    },
     {
         files: ["**/tools/**"],
         rules: {

package.json

@@ -5,8 +5,10 @@
   "scripts": {
     "test": "npm test --workspaces --if-present",
     "build": "npm run build --workspaces --if-present",
+    "build:types": "npm run build:types --workspaces --if-present",
     "lint": "eslint",
-    "lint:fix": "eslint --fix"
+    "lint:fix": "eslint --fix",
+    "lint:types": "npm run lint:types --workspaces --if-present"
   },
   "workspaces": [
     "packages/*"
@@ -15,15 +17,17 @@
     "pre-commit": "lint-staged"
   },
   "lint-staged": {
-    "*.{js,cjs}": [
+    "*.{js,cjs,ts,cts}": [
       "eslint --fix"
     ]
   },
   "devDependencies": {
+    "@typescript-eslint/parser": "^8.49.0",
     "c8": "^10.1.3",
     "eslint": "^9.35.0",
     "eslint-config-eslint": "^13.0.0",
     "eslint-plugin-chai-friendly": "^1.0.0",
+    "eslint-plugin-expect-type": "^0.6.2",
     "globals": "^17.0.0",
     "lint-staged": "^16.0.0",
     "mocha": "^11.1.0",

packages/eslint-scope/README.md

@@ -37,6 +37,7 @@ In order to analyze scope, you'll need to have an [ESTree](https://github.com/es
   * `sourceType` (default: `"script"`) - The type of JavaScript file to evaluate. Change to `"module"` for ECMAScript module code.
   * `childVisitorKeys` (default: `null`) - An object with visitor key information (like [`eslint-visitor-keys`](https://github.com/eslint/js/tree/main/packages/eslint-visitor-keys)). Without this, `eslint-scope` finds child nodes to visit algorithmically. Providing this option is a performance enhancement.
   * `fallback` (default: `"iteration"`) - The strategy to use when `childVisitorKeys` is not specified. May be a function.
+  * `optimistic` (default: `false`) - Set to `true` to enable optimistic scope analysis.
   * `jsx` (default: `false`) - Enables the tracking of JSX components as variable references.
 
 Example:
@@ -100,7 +101,7 @@ The `ScopeManager` class is at the core of eslint-scope and is returned when you
   - `inner` - Optional boolean. When `true`, returns the innermost scope, otherwise returns the outermost scope. Default is `false`.
   - Returns: The acquired scope or `null` if no scope is found.
 
-- **`acquireAll(node)`**
+- **`acquireAll(node)` (Deprecated)**
   Acquires all scopes for a given node.
   - `node` - The AST node to acquire scopes from.
   - Returns: An array of scopes or `undefined` if none are found.
@@ -120,27 +121,29 @@ The `ScopeManager` class is at the core of eslint-scope and is returned when you
   Determines if the global return statement should be allowed.
   - Returns: `true` if the global return is enabled.
 
-- **`isModule()`**
+- **`isModule()` (Deprecated)**
   Checks if the code should be handled as an ECMAScript module.
   - Returns: `true` if the sourceType is "module".
 
-- **`isImpliedStrict()`**
+- **`isImpliedStrict()` (Deprecated)**
   Checks if implied strict mode is enabled.
   - Returns: `true` if implied strict mode is enabled.
 
-- **`isStrictModeSupported()`**
+- **`isStrictModeSupported()` (Deprecated)**
   Checks if strict mode is supported based on ECMAScript version.
   - Returns: `true` if the ECMAScript version supports strict mode.
 
 ### Scope Objects
 
 Scopes returned by the ScopeManager methods have the following properties:
 
-- `type` - The type of scope (e.g., "function", "block", "global").
+- `type` - The type of scope (e.g., `"function"`, `"block"`, `"global"`).
+- `isStrict` - `true` if this scope is in strict mode.
 - `variables` - Array of variables declared in this scope.
 - `set` - A Map of variable names to Variable objects for variables declared in this scope.
 - `references` - Array of references in this scope.
 - `through` - Array of references in this scope and its child scopes that aren't resolved in this scope or its child scopes.
+- `functionExpressionScope` - `true` if this is a `"function-expression-name"` scope.
 - `variableScope` - Reference to the closest variable scope.
 - `upper` - Reference to the parent scope.
 - `childScopes` - Array of child scopes.

packages/eslint-scope/lib/definition.js

@@ -24,8 +24,12 @@
 
 import Variable from "./variable.js";
 
+/** @import * as types from "eslint-scope" */
+
+// Cannot implement `types.Definition` directly because it contains a union.
 /**
  * @constructor Definition
+ * @implements {Omit<types.Definition, never>}
  */
 class Definition {
     constructor(type, name, node, parent, index, kind) {