Skip to main content

@typescript-eslint/scope-manager

npm: @typescript-eslint/scope-manager v8.49.0

A fork of eslint-scope, enhanced to support TypeScript functionality. ✨

A "scope analyser" traverses an AST and builds a model of how variables (and in our case, types) are defined and consumed by the source code. This form of static analysis allows you to understand and trace variables throughout the program, allowing you to access powerful information about a program without needing to drop into the much, much heavier type information.

API​

analyze(tree, options)​

Analyses a given AST and returns the resulting ScopeManager.

interface AnalyzeOptions {
  /**
   * Known visitor keys.
   */
  childVisitorKeys?: Record<string, string[]> | null;

  /**
   * Whether the whole script is executed under node.js environment.
   * When enabled, the scope manager adds a function scope immediately following the global scope.
   * Defaults to `false`.
   */
  globalReturn?: boolean;

  /**
   * Implied strict mode.
   * Defaults to `false`.
   */
  impliedStrict?: boolean;

  /**
   * The identifier that's used for JSX Element creation (after transpilation).
   * This should not be a member expression - just the root identifier (i.e. use "React" instead of "React.createElement").
   * Defaults to `"React"`.
   */
  jsxPragma?: string;

  /**
   * The identifier that's used for JSX fragment elements (after transpilation).
   * If `null`, assumes transpilation will always use a member on `jsxFactory` (i.e. React.Fragment).
   * This should not be a member expression - just the root identifier (i.e. use "h" instead of "h.Fragment").
   * Defaults to `null`.
   */
  jsxFragmentName?: string | null;

  /**
   * The lib used by the project.
   * This automatically defines a type variable for any types provided by the configured TS libs.
   * For more information, see https://www.typescriptlang.org/tsconfig#lib
   *
   * Defaults to ['esnext'].
   */
  lib?: Lib[];

  /**
   * The source type of the script.
   */
  sourceType?: 'script' | 'module';

  /**
   * Whether to resolve references to global `var`/function declarations when `sourceType` is `script`.
   *
   * - Defaults to `false` (matches ESLint 8/9 behavior): global `var`/function references stay in `through`.
   * - Set to `true` to opt into ESLint 10 behavior: script-mode global `var`/function references are resolved before rules run.
   *
   * This is mainly relevant for ESLint 10 users; ESLint 8/9 users don’t need to change anything.
   */
  resolveGlobalVarsInScript?: boolean;
  // Injected globals are value-only by default; type references will not bind unless the variable is marked type-capable.

  /**
   * Emit design-type metadata for decorated declarations in source.
   * Defaults to `false`.
   */
  emitDecoratorMetadata?: boolean;
}

Example usage:

import { analyze } from '@typescript-eslint/scope-manager';
import { parse } from '@typescript-eslint/typescript-estree';

const code = `const hello: string = 'world';`;
const ast = parse(code, {
  // note that scope-manager requires ranges on the AST
  range: true,
});
const scope = analyze(ast, {
  sourceType: 'module',
});

// ESLint 10 script-mode global resolution (opt-in):
// const scopeScript = analyze(astScript, {
//   sourceType: 'script',
//   resolveGlobalVarsInScript: true, // resolve global var/function refs before rules run
// });
// Note: ESLint 8/9 users should leave `resolveGlobalVarsInScript` unset (default false).
// ESLint 10 users should set it to true to match ESLint 10's script-mode contract.

// Changelog note: addGlobals + resolveGlobalVarsInScript support ESLint 10. ESLint 8/9 users need no change; ESLint 10 users should opt in for script mode.

References​