scope-analyzer

scope-analyzer

simple scope analysis for javascript ASTs. tracks scopes and collects references to variables.

Caveats and/or todos:

• May be missing edge cases.
• Things like label:s are not considered at all, but ideally in the future they will!

Install

npm install scope-analyzer

Usage

Note: AST nodes passed to scope-analyzer functions are expected to reference the parent node on a node.parent property. Nodes from falafel or transform-ast have a .parent property, but others may not. You can use estree-assign-parent to quickly assign a parent property to all nodes in an AST.

var scan = require('scope-analyzer')

var ast = parse('...')
// Initialize node module variables
scan.createScope(ast, ['module', 'exports', '__dirname', '__filename'])
scan.crawl(ast)

var binding = scan.getBinding(ast, 'exports')
binding.getReferences().forEach(function (reference) {
  // Assume for the sake of the example that all references to `exports` are assignments like
  // `exports.xyz = abc`
  console.log('found export:', reference.parent.property.name)
})

API

crawl(ast)

Walk the ast and analyze all scopes. This will immediately allow you to use the get* methods on any node in the tree.

clear(ast)

Clear scope information in all nodes of the AST.

visitScope(node)

Visit a node to check if it initialises any scopes. For example, a function declaration will initialise a new scope to hold bindings for its parameters. Use this if you are already walking the AST manually, and if you don't need the scope information during this walk.

visitBinding(node)

Visit a node to check if it is a reference to an existing binding. If it is, the reference is added to the parent scope. Use this if you are already walking the AST manually.

createScope(node, bindings)

Initialise a new scope at the given node. bindings is an array of variable names. This can be useful to make the scope analyzer aware of preexisting global variables. In that case, call createScope on the root node with the names of globals:

var ast = parse('xyz')
scopeAnalyzer.createScope(ast, ['HTMLElement', 'Notification', ...])

deleteScope(node)

Delete the scope initialised by node.

scope(node)

Get the Scope initialised by the given node.

getBinding(node)

Get the Binding referenced by the Identifier node.

Scope

scope.has(name)

Check if this scope defines name.

scope.getBinding(name)

Get the Binding named name that is declared by this scope.

scope.getReferences(name)

Get a list of all nodes referencing the name binding that is declared by this scope.

scope.getUndeclaredNames()

Get a list of all names that were used in this scope, but not defined anywhere in the AST.

scope.forEach(cb(binding, name))

Loop over all bindings declared by this scope.

scope.forEachAvailable(cb(binding, name))

Loop over all bindings available to this scope, declared in this scope or any parent scope.

Binding

binding.definition

The node that defined this binding. If this binding was not declared in the AST, binding.definition will be undefined.

binding.getReferences()

Return an array of nodes that reference this binding.

binding.isReferenced()

Check if the binding is referenced, i.e., if there are any identifier Nodes (other than binding.definition) referencing this binding.

binding.remove(node)

Remove a reference to this binding. Use this when you are replacing the node referencing the binding with something else.

License

Apache-2.0

Changelog

2.1.2 / 2021-10-05

• make .parent and [kScope] properties non-enumerable, fixing compatibility with recast. anecdotally a 20-30% performance regression.

  you can pin to 2.1.1 if you need the 20% and don't need safe traversal of node properties.