eslint/docs/developer-guide/scope-manager-interface.md

   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.