astronomical
v1.0.1
Published
offers a way to query a Javascript AST to find specific patterns using a syntax somewhat similar to XPath.
Downloads
25,833
Readme
ASTronomical
astronomical
offers a way to query a JavaScript AST to find specific patterns using a syntax somewhat similar to XPath.
astronomical
was inspired by astq, but offers some features that did not seem possible in astq
and also has some limits compared to astq
.
Goals:
- Should try to traverse the AST only once when resolving the Query
- Should allow filtering of nodes
- Allow running multiple queries at the same time without traversing the AST multiple times
Example
The following pattern:
//AssignmentExpression[
/MemberExpression[
/:property/:name == "migrateVersion" &&
/$:object == ../../../../:params
]
]/:right/:value
tries to find the following code snippet and returns the string value assigned to the migrateVersion
property:
...
function( jQuery, window ) {
...
jQuery.migrateVersion = "3.4.1";
...
}
...
Find an AssignmentExpression at arbitrary depth, which directly contains a MemberExpression where the property name is "migrateVersion" and the object is bound to a parameter of the surrounding function, an return the assigned value.
Grammar
/<node type>
- find a child node of the given type//<node type>
- find a descendant of the given type/:<name>
- find an attribute of the current node with the given name//:<name>
- find an attribute of the current node with the given name regardless of whether it's on the current node or on a descendant/$:<name>
- find the binding of an Identifier/$$:<name>
- return the binding or the attribute if binding cannot be resolved (helpful if a variable is sometimes directly assigned and sometimes not)[]
- apply a filter to the node&&
,||
- logical conditions of a filter==
- comparison in filter../
- go to parent in filter (use with care, as this causes extra traversal)/*
- wildcard type child//*
- wildcard type descendant'<some value>'
,"<some value>"
- a string literal/fn:first(selector)
- returns the first result from all matches/fn:concat(...selectors...)
- concatenates results. If an argument has more than one value, those will be concatenated first./fn:join(selector, ",")
- concatenates the results of a selector with the given separator
API
query(code: string, query: string) : Result[]
- Runs the given query on the given code in the form of an already parsed AST or a string (which is parsed assourceType: "unambiguous"
), and returns the result.multiQuery<T extends Record<string, string>>(code: string, namedQueries: T) : Record<keyof T, Result[]>
- Runs the given set of named queries on the given code in the form of an already parsed AST or a string (which is parsed assourceType: "unambiguous"
), and returns a map of named results (one result array per named query).
where Result
is Babel.Node | string | number | boolean;
Example code
import { query } from "astronomical";
import * as fs from "fs";
const contents = fs.readFileSync("some-file.js");
const result = query(
contents,
`//FunctionDeclaration/:id/:name`
);
console.log("Function names", result);