[pve-eslint.git] / eslint / docs / developer-guide / scope-manager-interface.md

# ScopeManager

This document was written based on the implementation of [eslint-scope](https://github.com/eslint/eslint-scope), a fork of [escope](https://github.com/estools/escope), and deprecates some members ESLint is not using.

----

## ScopeManager interface

`ScopeManager` object has all variable scopes.

### Fields

#### scopes

* **Type:** `Scope[]`
* **Description:** All scopes.

#### globalScope

* **Type:** `Scope`
* **Description:** The root scope.

### Methods

#### acquire(node, inner = false)

* **Parameters:**
    * `node` (`ASTNode`) ... An AST node to get their scope.
    * `inner` (`boolean`) ... If the node has multiple scope, this returns the outermost scope normally. If `inner` is `true` then this returns the innermost scope. Default is `false`.
* **Return type:** `Scope | null`
* **Description:** Get the scope of a given AST node. The gotten scope's `block` property is the node. This method never returns `function-expression-name` scope. If the node does not have their scope, this returns `null`.

#### getDeclaredVariables(node)

* **Parameters:**
    * `node` (`ASTNode`) ... An AST node to get their variables.
* **Return type:** `Variable[]`
* **Description:** Get the variables that a given AST node defines. The gotten variables' `def[].node`/`def[].parent` property is the node. If the node does not define any variable, this returns an empty array.

### Deprecated members

Those members are defined but not used in ESLint.

#### isModule()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this program is module.

#### isImpliedStrict()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this program is strict mode implicitly. I.e., `options.impliedStrict === true`.

#### isStrictModeSupported()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this program supports strict mode. I.e., `options.ecmaVersion >= 5`.

#### acquireAll(node)

* **Parameters:**
    * `node` (`ASTNode`) ... An AST node to get their scope.
* **Return type:** `Scope[] | null`
* **Description:** Get the scopes of a given AST node. The gotten scopes' `block` property is the node. If the node does not have their scope, this returns `null`.

----

## Scope interface

`Scope` object has all variables and references in the scope.

### Fields

#### type

* **Type:** `string`
* **Description:** The type of this scope. This is one of `"block"`, `"catch"`, `"class"`, `"for"`, `"function"`, `"function-expression-name"`, `"global"`, `"module"`, `"switch"`, `"with"`

#### isStrict

* **Type:** `boolean`
* **Description:** `true` if this scope is strict mode.

#### upper

* **Type:** `Scope | null`
* **Description:** The parent scope. If this is the global scope then this property is `null`.

#### childScopes

* **Type:** `Scope[]`
* **Description:** The array of child scopes. This does not include grandchild scopes.

#### variableScope

* **Type:** `Scope`
* **Description:** The scope which hosts variables which are defined by `var` declarations.

#### block

* **Type:** `ASTNode`
* **Description:** The AST node which created this scope.

#### variables

* **Type:** `Variable[]`
* **Description:** The array of all variables which are defined on this scope. This does not include variables which are defined in child scopes.

#### set

* **Type:** `Map<string, Variable>`
* **Description:** The map from variable names to variable objects.

> I hope to rename `set` field or replace by a method.

#### references

* **Type:** `Reference[]`
* **Description:** The array of all references on this scope. This does not include references in child scopes.

#### through

* **Type:** `Reference[]`
* **Description:** The array of references which could not be resolved in this scope.

#### functionExpressionScope

* **Type:** `boolean`
* **Description:** `true` if this scope is `"function-expression-name"` scope.

> I hope to deprecate `functionExpressionScope` field as replacing by `scope.type === "function-expression-name"`.

### Deprecated members

Those members are defined but not used in ESLint.

#### taints

* **Type:** `Map<string, boolean>`
* **Description:** The map from variable names to `tainted` flag.

#### dynamic

* **Type:** `boolean`
* **Description:** `true` if this scope is dynamic. I.e., the type of this scope is `"global"` or `"with"`.

#### directCallToEvalScope

* **Type:** `boolean`
* **Description:** `true` if this scope contains `eval()` invocations.

#### thisFound

* **Type:** `boolean`
* **Description:** `true` if this scope contains `this`.

#### resolve(node)

* **Parameters:**
    * `node` (`ASTNode`) ... An AST node to get their reference object. The type of the node must be `"Identifier"`.
* **Return type:** `Reference | null`
* **Description:** Returns `this.references.find(r => r.identifier === node)`.

#### isStatic()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** Returns `!this.dynamic`.

#### isArgumentsMaterialized()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this is a `"function"` scope which has used `arguments` variable.

#### isThisMaterialized()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** Returns `this.thisFound`.

#### isUsedName(name)

* **Parameters:**
    * `name` (`string`) ... The name to check.
* **Return type:** `boolean`
* **Description:** `true` if a given name is used in variable names or reference names.

----

## Variable interface

`Variable` object is variable's information.

### Fields

#### name

* **Type:** `string`
* **Description:** The name of this variable.

#### identifiers

* **Type:** `ASTNode[]`
* **Description:** The array of `Identifier` nodes which define this variable. If this variable is redeclared, this array includes two or more nodes.

> I hope to deprecate `identifiers` field as replacing by `defs[].name` field.

#### references

* **Type:** `Reference[]`
* **Description:** The array of the references of this variable.

#### defs

* **Type:** `Definition[]`
* **Description:** The array of the definitions of this variable.

### Deprecated members

Those members are defined but not used in ESLint.

#### tainted

* **Type:** `boolean`
* **Description:** The `tainted` flag. (always `false`)

#### stack

* **Type:** `boolean`
* **Description:** The `stack` flag. (I'm not sure what this means.)

----

## Reference interface

`Reference` object is reference's information.

### Fields

#### identifier

* **Type:** `ASTNode`
* **Description:** The `Identifier` node of this reference.

#### from

* **Type:** `Scope`
* **Description:** The `Scope` object that this reference is on.

#### resolved

* **Type:** `Variable | null`
* **Description:** The `Variable` object that this reference refers. If such variable was not defined, this is `null`.

#### writeExpr

* **Type:** `ASTNode | null`
* **Description:** The ASTNode object which is right-hand side.

#### init

* **Type:** `boolean`
* **Description:** `true` if this writing reference is a variable initializer or a default value.

### Methods

#### isWrite()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is writing.

#### isRead()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is reading.

#### isWriteOnly()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is writing but not reading.

#### isReadOnly()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is reading but not writing.

#### isReadWrite()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is reading and writing.

### Deprecated members

Those members are defined but not used in ESLint.

#### tainted

* **Type:** `boolean`
* **Description:** The `tainted` flag. (always `false`)

#### flag

* **Type:** `number`
* **Description:** `1` is reading, `2` is writing, `3` is reading/writing.

#### partial

* **Type:** `boolean`
* **Description:** The `partial` flag.

#### isStatic()

* **Parameters:**
* **Return type:** `boolean`
* **Description:** `true` if this reference is resolved statically.

----

## Definition interface

`Definition` object is variable definition's information.

### Fields

#### type

* **Type:** `string`
* **Description:** The type of this definition. One of `"CatchClause"`, `"ClassName"`, `"FunctionName"`, `"ImplicitGlobalVariable"`, `"ImportBinding"`, `"Parameter"`, and `"Variable"`.

#### name

* **Type:** `ASTNode`
* **Description:** The `Identifier` node of this definition.

#### node

* **Type:** `ASTNode`
* **Description:** The enclosing node of the name.

| type                       | node |
|:---------------------------|:-----|
| `"CatchClause"`            | `CatchClause`
| `"ClassName"`              | `ClassDeclaration` or `ClassExpression`
| `"FunctionName"`           | `FunctionDeclaration` or `FunctionExpression`
| `"ImplicitGlobalVariable"` | `Program`
| `"ImportBinding"`          | `ImportSpecifier`, `ImportDefaultSpecifier`, or `ImportNamespaceSpecifier`
| `"Parameter"`              | `FunctionDeclaration`, `FunctionExpression`, or `ArrowFunctionExpression`
| `"Variable"`               | `VariableDeclarator`

#### parent

* **Type:** `ASTNode | undefined | null`
* **Description:** The enclosing statement node of the name.

| type                       | parent |
|:---------------------------|:-------|
| `"CatchClause"`            | `null`
| `"ClassName"`              | `null`
| `"FunctionName"`           | `null`
| `"ImplicitGlobalVariable"` | `null`
| `"ImportBinding"`          | `ImportDeclaration`
| `"Parameter"`              | `null`
| `"Variable"`               | `VariableDeclaration`

### Deprecated members

Those members are defined but not used in ESLint.

#### index

* **Type:** `number | undefined | null`
* **Description:** The index in the declaration statement.

#### kind

* **Type:** `string | undefined | null`
* **Description:** The kind of the declaration statement.
Commit	Line	Data
eb39fafa DC	1	# ScopeManager
	2
	3	This document was written based on the implementation of [eslint-scope](https://github.com/eslint/eslint-scope), a fork of [escope](https://github.com/estools/escope), and deprecates some members ESLint is not using.
	4
	5	----
	6
	7	## ScopeManager interface
	8
	9	`ScopeManager` object has all variable scopes.
	10
	11	### Fields
	12
	13	#### scopes
	14
	15	* Type: `Scope[]`
	16	* Description: All scopes.
	17
	18	#### globalScope
	19
	20	* Type: `Scope`
	21	* Description: The root scope.
	22
	23	### Methods
	24
	25	#### acquire(node, inner = false)
	26
	27	* Parameters:
	28	* `node` (`ASTNode`) ... An AST node to get their scope.
	29	* `inner` (`boolean`) ... If the node has multiple scope, this returns the outermost scope normally. If `inner` is `true` then this returns the innermost scope. Default is `false`.
	30	* Return type: `Scope \| null`
	31	* Description: Get the scope of a given AST node. The gotten scope's `block` property is the node. This method never returns `function-expression-name` scope. If the node does not have their scope, this returns `null`.
	32
	33	#### getDeclaredVariables(node)
	34
	35	* Parameters:
	36	* `node` (`ASTNode`) ... An AST node to get their variables.
	37	* Return type: `Variable[]`
	38	* Description: Get the variables that a given AST node defines. The gotten variables' `def[].node`/`def[].parent` property is the node. If the node does not define any variable, this returns an empty array.
	39
	40	### Deprecated members
	41
	42	Those members are defined but not used in ESLint.
	43
	44	#### isModule()
	45
	46	* Parameters:
	47	* Return type: `boolean`
	48	* Description: `true` if this program is module.
	49
	50	#### isImpliedStrict()
	51
	52	* Parameters:
	53	* Return type: `boolean`
	54	* Description: `true` if this program is strict mode implicitly. I.e., `options.impliedStrict === true`.
	55
	56	#### isStrictModeSupported()
	57
	58	* Parameters:
	59	* Return type: `boolean`
	60	* Description: `true` if this program supports strict mode. I.e., `options.ecmaVersion >= 5`.
	61
	62	#### acquireAll(node)
	63
	64	* Parameters:
65	* `node` (`ASTNode`) ... An AST node to get their scope.
66	* Return type: `Scope[] \| null`
67	* Description: Get the scopes of a given AST node. The gotten scopes' `block` property is the node. If the node does not have their scope, this returns `null`.
68
69	----
70
71	## Scope interface
72
73	`Scope` object has all variables and references in the scope.
74
75	### Fields
76
77	#### type
78
79	* Type: `string`
80	* Description: The type of this scope. This is one of `"block"`, `"catch"`, `"class"`, `"for"`, `"function"`, `"function-expression-name"`, `"global"`, `"module"`, `"switch"`, `"with"`
81
82	#### isStrict
83
84	* Type: `boolean`
85	* Description: `true` if this scope is strict mode.
86
87	#### upper
88
89	* Type: `Scope \| null`
90	* Description: The parent scope. If this is the global scope then this property is `null`.
91
92	#### childScopes
93
94	* Type: `Scope[]`
95	* Description: The array of child scopes. This does not include grandchild scopes.
96
97	#### variableScope
98
99	* Type: `Scope`
100	* Description: The scope which hosts variables which are defined by `var` declarations.
101
102	#### block
103
104	* Type: `ASTNode`
105	* Description: The AST node which created this scope.
106
107	#### variables
108
109	* Type: `Variable[]`
110	* Description: The array of all variables which are defined on this scope. This does not include variables which are defined in child scopes.
111
112	#### set
113
114	* Type: `Map<string, Variable>`
115	* Description: The map from variable names to variable objects.
116
117	> I hope to rename `set` field or replace by a method.
118
119	#### references
120
121	* Type: `Reference[]`
122	* Description: The array of all references on this scope. This does not include references in child scopes.
123
124	#### through
125
126	* Type: `Reference[]`
127	* Description: The array of references which could not be resolved in this scope.
128
129	#### functionExpressionScope
130
131	* Type: `boolean`
132	* Description: `true` if this scope is `"function-expression-name"` scope.
133
134	> I hope to deprecate `functionExpressionScope` field as replacing by `scope.type === "function-expression-name"`.
135
136	### Deprecated members
137
138	Those members are defined but not used in ESLint.
139
140	#### taints
141
142	* Type: `Map<string, boolean>`
143	* Description: The map from variable names to `tainted` flag.
144
145	#### dynamic
146
147	* Type: `boolean`
148	* Description: `true` if this scope is dynamic. I.e., the type of this scope is `"global"` or `"with"`.
149
150	#### directCallToEvalScope
151
152	* Type: `boolean`
153	* Description: `true` if this scope contains `eval()` invocations.
154
155	#### thisFound
156
157	* Type: `boolean`
158	* Description: `true` if this scope contains `this`.
159
160	#### resolve(node)
161
162	* Parameters:
163	* `node` (`ASTNode`) ... An AST node to get their reference object. The type of the node must be `"Identifier"`.
164	* Return type: `Reference \| null`
165	* Description: Returns `this.references.find(r => r.identifier === node)`.
166
167	#### isStatic()
168
169	* Parameters:
170	* Return type: `boolean`
171	* Description: Returns `!this.dynamic`.
172
173	#### isArgumentsMaterialized()
174
175	* Parameters:
176	* Return type: `boolean`
177	* Description: `true` if this is a `"function"` scope which has used `arguments` variable.
178
179	#### isThisMaterialized()
180
181	* Parameters:
182	* Return type: `boolean`
183	* Description: Returns `this.thisFound`.
184
185	#### isUsedName(name)
186
187	* Parameters:
188	* `name` (`string`) ... The name to check.
189	* Return type: `boolean`
190	* Description: `true` if a given name is used in variable names or reference names.
191
192	----
193
194	## Variable interface
195
196	`Variable` object is variable's information.
197
198	### Fields
199
200	#### name
201
202	* Type: `string`
203	* Description: The name of this variable.
204
205	#### identifiers
206
207	* Type: `ASTNode[]`
208	* Description: The array of `Identifier` nodes which define this variable. If this variable is redeclared, this array includes two or more nodes.
209
210	> I hope to deprecate `identifiers` field as replacing by `defs[].name` field.
211
212	#### references
213
214	* Type: `Reference[]`
215	* Description: The array of the references of this variable.
216
217	#### defs
218
219	* Type: `Definition[]`
220	* Description: The array of the definitions of this variable.
221
222	### Deprecated members
223
224	Those members are defined but not used in ESLint.
225
226	#### tainted
227
228	* Type: `boolean`
229	* Description: The `tainted` flag. (always `false`)
230
231	#### stack
232
233	* Type: `boolean`
234	* Description: The `stack` flag. (I'm not sure what this means.)
235
236	----
237
238	## Reference interface
239
240	`Reference` object is reference's information.
241
242	### Fields
243
244	#### identifier
245
246	* Type: `ASTNode`
247	* Description: The `Identifier` node of this reference.
248
249	#### from
250
251	* Type: `Scope`
252	* Description: The `Scope` object that this reference is on.
253
254	#### resolved
255
256	* Type: `Variable \| null`
257	* Description: The `Variable` object that this reference refers. If such variable was not defined, this is `null`.
258
259	#### writeExpr
260
261	* Type: `ASTNode \| null`
262	* Description: The ASTNode object which is right-hand side.
263
264	#### init
265
266	* Type: `boolean`
267	* Description: `true` if this writing reference is a variable initializer or a default value.
268
269	### Methods
270
271	#### isWrite()
272
273	* Parameters:
274	* Return type: `boolean`
275	* Description: `true` if this reference is writing.
276
277	#### isRead()
278
279	* Parameters:
280	* Return type: `boolean`
281	* Description: `true` if this reference is reading.
282
283	#### isWriteOnly()
284
285	* Parameters:
286	* Return type: `boolean`
287	* Description: `true` if this reference is writing but not reading.
288
289	#### isReadOnly()
290
291	* Parameters:
292	* Return type: `boolean`
293	* Description: `true` if this reference is reading but not writing.
294
295	#### isReadWrite()
296
297	* Parameters:
298	* Return type: `boolean`
299	* Description: `true` if this reference is reading and writing.
300
301	### Deprecated members
302
303	Those members are defined but not used in ESLint.
304
305	#### tainted
306
307	* Type: `boolean`
308	* Description: The `tainted` flag. (always `false`)
309
310	#### flag
311
312	* Type: `number`
313	* Description: `1` is reading, `2` is writing, `3` is reading/writing.
314
315	#### partial
316
317	* Type: `boolean`
318	* Description: The `partial` flag.
319
320	#### isStatic()
321
322	* Parameters:
323	* Return type: `boolean`
324	* Description: `true` if this reference is resolved statically.
325
326	----
327
328	## Definition interface
329
330	`Definition` object is variable definition's information.
331
332	### Fields
333
334	#### type
335
336	* Type: `string`
337	* Description: The type of this definition. One of `"CatchClause"`, `"ClassName"`, `"FunctionName"`, `"ImplicitGlobalVariable"`, `"ImportBinding"`, `"Parameter"`, and `"Variable"`.
338
339	#### name
340
341	* Type: `ASTNode`
342	* Description: The `Identifier` node of this definition.
343
344	#### node
345
346	* Type: `ASTNode`
347	* Description: The enclosing node of the name.
348
349	\| type \| node \|
350	\|:---------------------------\|:-----\|
351	\| `"CatchClause"` \| `CatchClause`
352	\| `"ClassName"` \| `ClassDeclaration` or `ClassExpression`
353	\| `"FunctionName"` \| `FunctionDeclaration` or `FunctionExpression`
354	\| `"ImplicitGlobalVariable"` \| `Program`
355	\| `"ImportBinding"` \| `ImportSpecifier`, `ImportDefaultSpecifier`, or `ImportNamespaceSpecifier`
356	\| `"Parameter"` \| `FunctionDeclaration`, `FunctionExpression`, or `ArrowFunctionExpression`
357	\| `"Variable"` \| `VariableDeclarator`
358
359	#### parent
360
361	* Type: `ASTNode \| undefined \| null`
362	* Description: The enclosing statement node of the name.
363
364	\| type \| parent \|
365	\|:---------------------------\|:-------\|
366	\| `"CatchClause"` \| `null`
367	\| `"ClassName"` \| `null`
368	\| `"FunctionName"` \| `null`
369	\| `"ImplicitGlobalVariable"` \| `null`
370	\| `"ImportBinding"` \| `ImportDeclaration`
371	\| `"Parameter"` \| `null`
372	\| `"Variable"` \| `VariableDeclaration`
373
374	### Deprecated members
375
376	Those members are defined but not used in ESLint.
377
378	#### index
379
380	* Type: `number \| undefined \| null`
381	* Description: The index in the declaration statement.
382
383	#### kind
384
385	* Type: `string \| undefined \| null`
386	* Description: The kind of the declaration statement.