[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"`, `"class-field-initializer"`, `"class-static-block"`, `"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 nearest ancestor whose `type` is one of `"class-field-initializer"`, `"class-static-block"`, `"function"`, `"global"`, or `"module"`. For the aforementioned scopes this is a self-reference.

> This represents the lowest enclosing function or top-level scope. Class field initializers and class static blocks are implicit functions. Historically, this was the scope which hosts variables that are defined by `var` declarations, and thus the name `variableScope`.

#### 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`
609c276f	80	* Description: The type of this scope. This is one of `"block"`, `"catch"`, `"class"`, `"class-field-initializer"`, `"class-static-block"`, `"for"`, `"function"`, `"function-expression-name"`, `"global"`, `"module"`, `"switch"`, `"with"`.
eb39fafa DC	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`
609c276f TL	100	* Description: The nearest ancestor whose `type` is one of `"class-field-initializer"`, `"class-static-block"`, `"function"`, `"global"`, or `"module"`. For the aforementioned scopes this is a self-reference.
	101
	102	> This represents the lowest enclosing function or top-level scope. Class field initializers and class static blocks are implicit functions. Historically, this was the scope which hosts variables that are defined by `var` declarations, and thus the name `variableScope`.
eb39fafa DC	103
	104	#### block
	105
	106	* Type: `ASTNode`
	107	* Description: The AST node which created this scope.
	108
	109	#### variables
	110
	111	* Type: `Variable[]`
	112	* Description: The array of all variables which are defined on this scope. This does not include variables which are defined in child scopes.
	113
	114	#### set
	115
	116	* Type: `Map<string, Variable>`
	117	* Description: The map from variable names to variable objects.
	118
	119	> I hope to rename `set` field or replace by a method.
	120
	121	#### references
	122
	123	* Type: `Reference[]`
	124	* Description: The array of all references on this scope. This does not include references in child scopes.
	125
	126	#### through
	127
	128	* Type: `Reference[]`
	129	* Description: The array of references which could not be resolved in this scope.
	130
	131	#### functionExpressionScope
	132
	133	* Type: `boolean`
	134	* Description: `true` if this scope is `"function-expression-name"` scope.
	135
	136	> I hope to deprecate `functionExpressionScope` field as replacing by `scope.type === "function-expression-name"`.
	137
	138	### Deprecated members
	139
	140	Those members are defined but not used in ESLint.
	141
	142	#### taints
	143
	144	* Type: `Map<string, boolean>`
	145	* Description: The map from variable names to `tainted` flag.
	146
	147	#### dynamic
	148
	149	* Type: `boolean`
	150	* Description: `true` if this scope is dynamic. I.e., the type of this scope is `"global"` or `"with"`.
	151
	152	#### directCallToEvalScope
	153
	154	* Type: `boolean`
	155	* Description: `true` if this scope contains `eval()` invocations.
	156
	157	#### thisFound
	158
	159	* Type: `boolean`
	160	* Description: `true` if this scope contains `this`.
	161
	162	#### resolve(node)
	163
	164	* Parameters:
	165	* `node` (`ASTNode`) ... An AST node to get their reference object. The type of the node must be `"Identifier"`.
	166	* Return type: `Reference \| null`
167	* Description: Returns `this.references.find(r => r.identifier === node)`.
168
169	#### isStatic()
170
171	* Parameters:
172	* Return type: `boolean`
173	* Description: Returns `!this.dynamic`.
174
175	#### isArgumentsMaterialized()
176
177	* Parameters:
178	* Return type: `boolean`
179	* Description: `true` if this is a `"function"` scope which has used `arguments` variable.
180
181	#### isThisMaterialized()
182
183	* Parameters:
184	* Return type: `boolean`
185	* Description: Returns `this.thisFound`.
186
187	#### isUsedName(name)
188
189	* Parameters:
190	* `name` (`string`) ... The name to check.
191	* Return type: `boolean`
192	* Description: `true` if a given name is used in variable names or reference names.
193
194	----
195
196	## Variable interface
197
198	`Variable` object is variable's information.
199
200	### Fields
201
202	#### name
203
204	* Type: `string`
205	* Description: The name of this variable.
206
207	#### identifiers
208
209	* Type: `ASTNode[]`
210	* Description: The array of `Identifier` nodes which define this variable. If this variable is redeclared, this array includes two or more nodes.
211
212	> I hope to deprecate `identifiers` field as replacing by `defs[].name` field.
213
214	#### references
215
216	* Type: `Reference[]`
217	* Description: The array of the references of this variable.
218
219	#### defs
220
221	* Type: `Definition[]`
222	* Description: The array of the definitions of this variable.
223
224	### Deprecated members
225
226	Those members are defined but not used in ESLint.
227
228	#### tainted
229
230	* Type: `boolean`
231	* Description: The `tainted` flag. (always `false`)
232
233	#### stack
234
235	* Type: `boolean`
236	* Description: The `stack` flag. (I'm not sure what this means.)
237
238	----
239
240	## Reference interface
241
242	`Reference` object is reference's information.
243
244	### Fields
245
246	#### identifier
247
248	* Type: `ASTNode`
249	* Description: The `Identifier` node of this reference.
250
251	#### from
252
253	* Type: `Scope`
254	* Description: The `Scope` object that this reference is on.
255
256	#### resolved
257
258	* Type: `Variable \| null`
259	* Description: The `Variable` object that this reference refers. If such variable was not defined, this is `null`.
260
261	#### writeExpr
262
263	* Type: `ASTNode \| null`
264	* Description: The ASTNode object which is right-hand side.
265
266	#### init
267
268	* Type: `boolean`
269	* Description: `true` if this writing reference is a variable initializer or a default value.
270
271	### Methods
272
273	#### isWrite()
274
275	* Parameters:
276	* Return type: `boolean`
277	* Description: `true` if this reference is writing.
278
279	#### isRead()
280
281	* Parameters:
282	* Return type: `boolean`
283	* Description: `true` if this reference is reading.
284
285	#### isWriteOnly()
286
287	* Parameters:
288	* Return type: `boolean`
289	* Description: `true` if this reference is writing but not reading.
290
291	#### isReadOnly()
292
293	* Parameters:
294	* Return type: `boolean`
295	* Description: `true` if this reference is reading but not writing.
296
297	#### isReadWrite()
298
299	* Parameters:
300	* Return type: `boolean`
301	* Description: `true` if this reference is reading and writing.
302
303	### Deprecated members
304
305	Those members are defined but not used in ESLint.
306
307	#### tainted
308
309	* Type: `boolean`
310	* Description: The `tainted` flag. (always `false`)
311
312	#### flag
313
314	* Type: `number`
315	* Description: `1` is reading, `2` is writing, `3` is reading/writing.
316
317	#### partial
318
319	* Type: `boolean`
320	* Description: The `partial` flag.
321
322	#### isStatic()
323
324	* Parameters:
325	* Return type: `boolean`
326	* Description: `true` if this reference is resolved statically.
327
328	----
329
330	## Definition interface
331
332	`Definition` object is variable definition's information.
333
334	### Fields
335
336	#### type
337
338	* Type: `string`
339	* Description: The type of this definition. One of `"CatchClause"`, `"ClassName"`, `"FunctionName"`, `"ImplicitGlobalVariable"`, `"ImportBinding"`, `"Parameter"`, and `"Variable"`.
340
341	#### name
342
343	* Type: `ASTNode`
344	* Description: The `Identifier` node of this definition.
345
346	#### node
347
348	* Type: `ASTNode`
349	* Description: The enclosing node of the name.
350
351	\| type \| node \|
352	\|:---------------------------\|:-----\|
353	\| `"CatchClause"` \| `CatchClause`
354	\| `"ClassName"` \| `ClassDeclaration` or `ClassExpression`
355	\| `"FunctionName"` \| `FunctionDeclaration` or `FunctionExpression`
356	\| `"ImplicitGlobalVariable"` \| `Program`
357	\| `"ImportBinding"` \| `ImportSpecifier`, `ImportDefaultSpecifier`, or `ImportNamespaceSpecifier`
358	\| `"Parameter"` \| `FunctionDeclaration`, `FunctionExpression`, or `ArrowFunctionExpression`
359	\| `"Variable"` \| `VariableDeclarator`
360
361	#### parent
362
363	* Type: `ASTNode \| undefined \| null`
364	* Description: The enclosing statement node of the name.
365
366	\| type \| parent \|
367	\|:---------------------------\|:-------\|
368	\| `"CatchClause"` \| `null`
369	\| `"ClassName"` \| `null`
370	\| `"FunctionName"` \| `null`
371	\| `"ImplicitGlobalVariable"` \| `null`
372	\| `"ImportBinding"` \| `ImportDeclaration`
373	\| `"Parameter"` \| `null`
374	\| `"Variable"` \| `VariableDeclaration`
375
376	### Deprecated members
377
378	Those members are defined but not used in ESLint.
379
380	#### index
381
382	* Type: `number \| undefined \| null`
383	* Description: The index in the declaration statement.
384
385	#### kind
386
387	* Type: `string \| undefined \| null`
388	* Description: The kind of the declaration statement.