ast-scout v1.0.5
ast-scout
Search abstract syntax tree (Babylon AST) and report mathing paths.
Installation
npm i ast-scout --save
Usage
This is a tool to search AST for objects on basis of a string of code. AstScout can be useful for collecting info from your codebase.
From the scout's search definition ast-scout creates internally (with help of Babel) a visitor object tree where each visitor is, if required from the provided match definitions, decorated with additional logic to report back specific AST paths.
example
const findPaths = require('ast-scout').findPaths;
const traverse = require('@babel/traverse').default;
const generate = require('@babel/generator').default;
const parser = require('@babel/parser');
const code = `
import { bla } from 'common/utils';
function foo() {
bla('Hello world!');
}
function foo2() {
bla('Hello earth!');
}
function foo3() {
bla(KEY_VALUE);
}
`;
const babelConfig = {
sourceType: 'unambiguous',
plugins: ['jsx', 'decorators-legacy', 'classProperties', 'objectRestSpread'],
}
const ast = parser.parse(code, babelConfig);
const scout = {
search: 'bla()',
match: [{
search: 'bla',
marked: true,
}]
};
traverse(ast, {
Program: function programVisitor(path) {
const { searchPaths, matchPaths } = findPaths(path, scout, babelConfig);
console.log('searchPaths', searchPaths.length);
console.log('matchPaths', matchPaths.length);
matchPaths.forEach( path => {
console.log(`match type: ${path.parentPath.node.arguments[0].type}`);
console.log(` code: ${generate(path.parentPath.node.arguments[0]).code}`);
});
}
});
result
searchPaths 3
matchPaths 3
match type: StringLiteral
code: 'Hello world!'
match type: StringLiteral
code: 'Hello earth!'
match type: Identifier
code: KEY_VALUE
API
findPaths
findPaths(path, scout, babelConfig);
Returns an object with Babel path results for searchPaths and matchPaths.
Path
object - Babel path object.
Scout
string|object - Defines search, matching and path reporting requirements. See below for more scout examples.
BabelConfig
object - Internally babel parser is used for creating a nested visitors structrure. Passing this config ensures the AST created from the search parameter is in line with the AST created from the code you want to analyse.
Scout Examples
Simple search
In the returned searchPaths all results found for CallExpression paths with the exact match of getMyString(welcomeMessageKey)
are listed.
const scout = 'getMyString(welcomeMessageKey)'
Search with regExpr defined in match
In the returned searchPaths all results found for ImportDeclaration paths with the exact match of import { getMyString } from \'./common/utils\
are listed.
In the returned matchPaths all child paths are listed for Identifier getMyString
and in addition for Identifier getAllMyStrings
.
To instruct ast-scout to include the matching child node in the matchPaths results use: marked: true
.
const scout = {
search: 'import { getMyString } from \'./common/utils\';',
match: [{
search: 'getMyString',
regExpr: /^getMyString$|^getAllMyStrings$/,
marked: true
}, {
search: './common/utils',
regExpr: /common\/utils$/
}],
}
Search with context and startType
Searching for jsx attribute declarations without providing the containing jsx container in the search term would lead us to results of object definition types instead. Therefore we can define a search context (the jsx attribute definition within div tags) and instruct the ast-scout process to start the visitor object tree at the JSXAttribute node.
In the returned searchPaths all paths found for the exact match of key={previousSearchTerm}
are listed.
In the returned matchPaths all child paths are listed for Identifier previousSearchTerm
.
const scout = {
search: {
context: '<div key={previousSearchTerm} />',
startType: 'JSXAttribute'
},
match: [{
search: 'previousSearchTerm',
marked: true
}],
}