0
# Core Analysis
1

2
The core analysis functionality provides the main entry point for analyzing AST nodes and generating comprehensive scope information with TypeScript awareness.
3

4
## Capabilities
5

6
### Analyze Function
7

8
The primary function that takes a TypeScript ESTree AST node and optional configuration options, then returns a ScopeManager instance containing complete scope analysis.
9

10
```typescript { .api }
11
/**
12
 * Takes an AST and returns the analyzed scopes.
13
 * @param tree - The TypeScript ESTree AST node to analyze
14
 * @param providedOptions - Optional configuration for the analysis
15
 * @returns ScopeManager instance with complete scope information
16
 */
17
function analyze(
18
  tree: TSESTree.Node,
19
  providedOptions?: AnalyzeOptions
20
): ScopeManager;
21
```
22

23
### Analysis Options
24

25
Configuration interface for customizing the scope analysis behavior.
26

27
```typescript { .api }
28
interface AnalyzeOptions {
29
  /**
30
   * Known visitor keys for AST traversal.
31
   */
32
  childVisitorKeys?: Record<string, string[]>;
33

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

41
  /**
42
   * Implied strict mode.
43
   * Defaults to false.
44
   */
45
  impliedStrict?: boolean;
46

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

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

62
  /**
63
   * The lib used by the project.
64
   * This automatically defines a type variable for any types provided by the configured TS libs.
65
   * Defaults to ['esnext'] when options are provided, ['es2018'] when no options are provided.
66
   * 
67
   * @see https://www.typescriptlang.org/tsconfig#lib
68
   */
69
  lib?: Lib[];
70

71
  /**
72
   * The source type of the script.
73
   * Can be 'script' or 'module'.
74
   */
75
  sourceType?: SourceType;
76

77
  // TODO - remove this in v10
78
  /**
79
   * @deprecated This option never did what it was intended for and will be removed in a future major release.
80
   */
81
  emitDecoratorMetadata?: boolean;
82
}
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import { analyze } from "@typescript-eslint/scope-manager";
89
import type { TSESTree } from "@typescript-eslint/types";
90

91
// Basic analysis with default options
92
const scopeManager = analyze(astNode);
93

94
// Analysis with custom options
95
const scopeManager = analyze(astNode, {
96
  globalReturn: true,
97
  impliedStrict: true,
98
  jsxPragma: 'h',
99
  jsxFragmentName: 'Fragment',
100
  lib: ['es2020', 'dom'],
101
  sourceType: 'module'
102
});
103

104
// Node.js environment analysis
105
const scopeManager = analyze(astNode, {
106
  globalReturn: true,
107
  sourceType: 'script',
108
  lib: ['es2020', 'node']
109
});
110

111
// React JSX analysis
112
const scopeManager = analyze(astNode, {
113
  jsxPragma: 'React',
114
  jsxFragmentName: null, // Uses React.Fragment
115
  lib: ['es2020', 'dom'],
116
  sourceType: 'module'
117
});
118
```
119

120
### Default Options
121

122
The analyze function uses these default values when options are not specified:
123

124
```typescript { .api }
125
const DEFAULT_OPTIONS: Required<AnalyzeOptions> = {
126
  childVisitorKeys: visitorKeys, // from @typescript-eslint/visitor-keys
127
  emitDecoratorMetadata: false, // deprecated
128
  globalReturn: false,
129
  impliedStrict: false,
130
  jsxFragmentName: null,
131
  jsxPragma: 'React',
132
  lib: ['es2018'],
133
  sourceType: 'script'
134
};
135
```
136

137
### Integration with TypeScript AST
138

139
The analyze function works with TypeScript ESTree AST nodes from `@typescript-eslint/types`:
140

141
```typescript
142
import { parse } from "@typescript-eslint/parser";
143
import { analyze } from "@typescript-eslint/scope-manager";
144

145
// Parse TypeScript code
146
const code = `
147
interface User {
148
  name: string;
149
  age: number;
150
}
151

152
function createUser(name: string, age: number): User {
153
  return { name, age };
154
}
155
`;
156

157
const ast = parse(code, {
158
  loc: true,
159
  range: true,
160
});
161

162
// Analyze the parsed AST
163
const scopeManager = analyze(ast, {
164
  sourceType: 'module',
165
  lib: ['es2020']
166
});
167

168
// Access analysis results
169
console.log(`Found ${scopeManager.scopes.length} scopes`);
170
console.log(`Global variables: ${scopeManager.globalScope?.variables.length}`);
171
```
172

173
### Error Handling
174

175
The analyze function may throw errors for invalid AST nodes or configuration:
176

177
- Invalid AST structure will cause traversal errors
178
- Unsupported lib values will be ignored with a warning
179
- Malformed visitor keys will cause traversal issues
180

181
Always ensure your AST is properly formed using a compatible parser like `@typescript-eslint/parser`.