ast-search 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# ast-search
+
+A (somewhat) limited-case search tool meant to facilitate large-scale refactors.
+
+Searches files for a given function or property name, and then determines whether those functions or properties contain a given expression or value.
+
+## Example
+
+For example, say you have a large number of VueJS single-file-components with `setup` functions that might be improperly accessing the `this.` instance of the file:
+
+```
+<script>
+...
+export default {
+    setup() {
+        const store = useStore();
+        const dynamicTestValue = computed(() => {
+            return this.testValue
+        })
+    },
+    computed: {
+        testValue: 0
+    }
+}
+</script>
+```
+
+If you have hundreds of component files, this would be especially difficult (if not impossible) to find with a regular expression because it would require both searching across multiple lines and knowing the lexical scope of the `setup` function, which would vary widely across each file.
+
+## Usage
+
+`ast-search` leverages [ acornjs ](https://github.com/acornjs/acorn) to construct an Abstract Syntax Tree of each JavaScript file it parses, and then searches relevant paths for both the given top-level function or property as well as the desired search term.
+
+For example, say the above VueJS SFC is a file at `src/components/TestValue.vue`. To search this file and determine whether the `setup` function has a `this.` expression, you'd do the following:
+
+```bash
+$ ast-search -f ./src/components/TestValue.vue --fn setup -e ThisExpression
+```
+
+If it finds the expression in the function, it echoes the file path:
+
+```bash
+$ ast-search -f ./src/components/TestValue.vue --fn setup -e ThisExpression
+./src/components/TestValue.vue
+```
+
+## Arguments
+
+| Flag               | Definition                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| `-f, --file`       | the file path to search, relative or absolute                                                      |
+| `--function, fn`   | the function to search; can be any variation of a function declaration or expression               |
+| `-p, --property`   | the property to search; expected to be a property on an object                                     |
+| `-m, --multiple`   | used for searching function calls, of which a single file may contain several                      |
+| `-e, --expression` | the type of expression to search for; must be a valid `acornjs` JavaScript expression (list below) |
+| `-d, --debug`      | output the full Abstract Syntax Tree to a file called `output.json`                                |
+
+### Supported Expressions
+
+| Expression Name          | Reference                                             | Common Operators              |
+| ------------------------ | ----------------------------------------------------- | ----------------------------- |
+| ArrayExpression          | begins an array expression                            | `[]`                          |
+| ArrowFunctionExpression  | begins an arrow function in any lexical context       | `() =>`                       |
+| AssignmentExpression     | equals operator                                       | `=`                           |
+| AwaitExpression          | asynchronous promise resolver                         | `await`                       |
+| BinaryExpression         | any left + right side operation                       | `1 + 1`                       |
+| CallExpression           | function calls                                        | `fn()`                        |
+| ChainExpression          | chained property or method accessors                  | `store.state.someFn()`        |
+| ConditionalExpression    | ternary expression                                    | `x ? y : z`                   |
+| FunctionExpression       | named, non-assigned functions                         | `fn() {}`                     |
+| ImportExpression         | import statements                                     | `import x from 'y'`           |
+| LogicalExpression        | evaluates to a boolean, e.g. if statement expressions | `if (x > y)`                  |
+| MemberExpression         | object member accessor                                | `this.theMember`              |
+| NewExpression            | `new` constructor declaration                         | `const x = new Item()`        |
+| ObjectExpression         | an object as referenced by its brackets               | `{}`                          |
+| ParenthesizedExpression  | an expression wrapped in parens                       | `const foo = (bar)`           |
+| SequenceExpression       | deconstructor expressions                             | `({...(a,b),c})`              |
+| TaggedTemplateExpression | backtick expressions                                  | <pre>`${test}`</pre>          |
+| ThisExpression           | this accessors                                        | `this.someItem`               |
+| UnaryExpression          | standalone statements                                 | ` return x + 1` (the `x + 1`) |
+| UpdateExpression         | increments, decrements                                | `x++` or `--y`                |
+| YieldExpression          | yield statements in iterators                         | `yield x`                     |
+
+## Support
+
+Currently only supports VueJS's Single File Components.

package/build/file.js

@@ -0,0 +1,58 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { open } from "node:fs/promises";
+import { extname } from "node:path";
+import * as parser from "@babel/parser";
+export function getAst(contents) {
+    return parser.parse(contents, {
+        sourceType: "module",
+        plugins: ["jsx", "typescript"],
+    });
+}
+export const SCRIPT_OPEN = /^\s*<script(\s[^>]*)?\s*>/;
+export const SCRIPT_CLOSE = /^\s*<\/script>\s*/;
+export function parseVueSFC(lines) {
+    const fileContents = [];
+    let append = false;
+    for (const line of lines.toString().split("\n")) {
+        if (SCRIPT_OPEN.test(line)) {
+            append = true;
+            continue;
+        }
+        if (SCRIPT_CLOSE.test(line)) {
+            append = false;
+            break;
+        }
+        if (append) {
+            fileContents.push(line);
+        }
+    }
+    return fileContents.join("\n");
+}
+const JS_EXTENSIONS = new Set([".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"]);
+export function getAstFromPath(path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const file = yield open(path);
+        const lines = yield file.readFile();
+        const ext = extname(path);
+        let fileContents;
+        if (ext === ".vue") {
+            fileContents = parseVueSFC(lines);
+        }
+        else if (JS_EXTENSIONS.has(ext)) {
+            fileContents = lines.toString();
+        }
+        else {
+            throw new Error(`Unsupported file extension: "${ext}" in path: ${path}`);
+        }
+        const ast = getAst(fileContents);
+        return { ast, file, source: fileContents };
+    });
+}

package/build/helpers/nodes.js

@@ -0,0 +1,149 @@
+import { isBlockStatement } from "@babel/types";
+export const hasKeyedNode = (node) => {
+    switch (node.type) {
+        case "ObjectMethod":
+        case "ObjectProperty":
+        case "ClassMethod":
+        case "ClassProperty":
+        case "ClassAccessorProperty":
+        case "ObjectTypeProperty":
+        case "ImportAttribute":
+        case "TSDeclareMethod":
+            return true;
+        case "ClassPrivateProperty":
+        case "ClassPrivateMethod":
+            return true;
+        case "TSPropertySignature":
+        case "TSMethodSignature":
+            return false;
+    }
+};
+export const hasIdentifier = (node) => {
+    switch (node.type) {
+        case "PrivateName":
+        case "ClassImplements":
+        case "DeclareClass":
+        case "DeclareFunction":
+        case "DeclareInterface":
+        case "DeclareModule":
+        case "DeclareTypeAlias":
+        case "DeclareOpaqueType":
+        case "DeclareVariable":
+        case "GenericTypeAnnotation":
+        case "InterfaceExtends":
+        case "InterfaceDeclaration":
+        case "ObjectTypeInternalSlot":
+        case "OpaqueType":
+        case "QualifiedTypeIdentifier":
+        case "TypeAlias":
+        case "EnumDeclaration":
+        case "EnumBooleanMember":
+        case "EnumNumberMember":
+        case "EnumStringMember":
+        case "EnumDefaultedMember":
+        case "TSInterfaceDeclaration":
+        case "TSTypeAliasDeclaration":
+        case "TSEnumDeclaration":
+        case "TSEnumMember":
+        case "TSModuleDeclaration":
+        case "TSImportEqualsDeclaration":
+        case "TSNamespaceExportDeclaration":
+        case "VariableDeclarator":
+            return true;
+        default:
+            return false;
+    }
+};
+export const hasBodyBlockStatement = (node) => {
+    if ("body" in node) {
+        switch (node.type) {
+            case "CatchClause":
+            case "FunctionDeclaration":
+            case "FunctionExpression":
+            case "ObjectMethod":
+            case "ClassMethod":
+            case "ClassPrivateMethod":
+            case "DeclareModule":
+            case "DoExpression":
+                return true;
+            case "ArrowFunctionExpression":
+                return !!isBlockStatement(node.body);
+            default:
+                return false;
+        }
+    }
+    if ("block" in node) {
+        return !!isBlockStatement(node.block);
+    }
+    return false;
+};
+export const hasDeclarations = (node) => {
+    if ("declarations" in node) {
+        switch (node.type) {
+            case "VariableDeclaration":
+                return true;
+            default:
+                return false;
+        }
+    }
+};
+export const hasProperties = (node) => {
+    if ("properties" in node) {
+        switch (node.type) {
+            case "ObjectExpression":
+            case "ObjectPattern":
+            case "ObjectTypeAnnotation":
+            case "RecordExpression":
+                return true;
+            default:
+                return false;
+        }
+    }
+};
+const arrayifyNode = (node) => {
+    if (Array.isArray(node)) {
+        return node;
+    }
+    else {
+        return [node];
+    }
+};
+export const getNodeBody = (node) => {
+    if ("argument" in node) {
+        return arrayifyNode(node.argument);
+    }
+    if ("arguments" in node) {
+        return [...node.arguments, ...arrayifyNode(node.callee)];
+    }
+    if ("block" in node) {
+        return arrayifyNode(node.block);
+    }
+    if ("body" in node) {
+        return arrayifyNode(node.body);
+    }
+    if ("declaration" in node) {
+        return arrayifyNode(node.declaration);
+    }
+    if ("declarations" in node) {
+        return node.declarations;
+    }
+    if ("expression" in node) {
+        return arrayifyNode(node.expression);
+    }
+    if ("init" in node) {
+        return arrayifyNode(node.init);
+    }
+    if ("object" in node) {
+        if ("property" in node) {
+            return [node.object, ...arrayifyNode(node.property)];
+        }
+        return arrayifyNode(node.object);
+    }
+    if ("properties" in node) {
+        return node.properties;
+    }
+    if ("value" in node) {
+        return arrayifyNode(node.value);
+    }
+    return [];
+};

package/build/main.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import yargs from "yargs/yargs";
+import { walkRepoFiles } from "./walk.js";
+import { getAstFromPath } from "./file.js";
+import { runQuery, validateSelector } from "./search.js";
+import { formatMatches } from "./output.js";
+export function searchRepo(selector, dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_1, _b, _c;
+        validateSelector(selector); // throws early on invalid selector syntax
+        const results = [];
+        try {
+            for (var _d = true, _e = __asyncValues(walkRepoFiles(dir)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const filePath = _c;
+                let file;
+                try {
+                    const result = yield getAstFromPath(filePath);
+                    file = result.file;
+                    const matches = runQuery(selector, result.ast, result.source, filePath);
+                    results.push(...matches);
+                }
+                catch (_g) {
+                    // skip unparseable files
+                }
+                finally {
+                    yield (file === null || file === void 0 ? void 0 : file.close());
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return results;
+    });
+}
+const y = yargs(process.argv.slice(2))
+    .scriptName("ast-search")
+    .usage("$0 <query> [--dir <path>] [--format <fmt>]")
+    .command("$0 <query>", "Search a repo for AST patterns using CSS selector syntax", (yargs) => yargs
+    .positional("query", {
+    type: "string",
+    describe: "esquery CSS selector string",
+    demandOption: true,
+})
+    .option("dir", {
+    alias: "d",
+    type: "string",
+    describe: "root directory to search",
+    default: process.cwd(),
+})
+    .option("format", {
+    alias: "f",
+    type: "string",
+    describe: "output format: text (default), json, files",
+    default: "text",
+    choices: ["text", "json", "files"],
+}), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const { query, dir, format } = argv;
+    try {
+        const matches = yield searchRepo(query, dir);
+        const isTTY = (_a = process.stdout.isTTY) !== null && _a !== void 0 ? _a : false;
+        for (const line of formatMatches(matches, isTTY, format)) {
+            console.log(line);
+        }
+        process.exit(matches.length > 0 ? 0 : 1);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${msg}\n`);
+        process.exit(2);
+    }
+}))
+    .help();
+if (process.env.NODE_ENV !== "test") {
+    y.parse();
+}

package/build/output.js

@@ -0,0 +1,20 @@
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+export function formatMatches(matches, isTTY, format = "text") {
+    if (format === "json") {
+        return [JSON.stringify(matches, null, 2)];
+    }
+    if (format === "files") {
+        const seen = new Set();
+        return matches.map((m) => m.file).filter((f) => !seen.has(f) && !!seen.add(f));
+    }
+    return matches.map((m) => formatMatch(m, isTTY));
+}
+function formatMatch(match, isTTY) {
+    const loc = `${match.file}:${match.line}:${match.col}`;
+    if (!match.source)
+        return loc;
+    const src = isTTY ? `${BOLD}${CYAN}${match.source}${RESET}` : match.source;
+    return `${loc}: ${src}`;
+}

package/build/search.js

@@ -0,0 +1,71 @@
+import esquery from "esquery";
+import { VISITOR_KEYS } from "@babel/types";
+export const SHORTHANDS = {
+    this: "ThisExpression",
+    await: "AwaitExpression",
+    yield: "YieldExpression",
+    new: "NewExpression",
+    call: "CallExpression",
+    arrow: "ArrowFunctionExpression",
+    fn: "FunctionExpression",
+    member: "MemberExpression",
+    ternary: "ConditionalExpression",
+    template: "TemplateLiteral",
+    tagged: "TaggedTemplateExpression",
+    assign: "AssignmentExpression",
+    binary: "BinaryExpression",
+    logical: "LogicalExpression",
+    spread: "SpreadElement",
+};
+// Expand shorthands to full Babel type names, but not inside quoted attribute values.
+export function expandShorthands(selector) {
+    const keys = Object.keys(SHORTHANDS);
+    const pattern = new RegExp(`\\b(${keys.join("|")})\\b`, "g");
+    const parts = [];
+    let i = 0;
+    while (i < selector.length) {
+        const ch = selector[i];
+        if (ch === '"' || ch === "'") {
+            // Preserve quoted string as-is
+            let j = i + 1;
+            while (j < selector.length && selector[j] !== ch)
+                j++;
+            parts.push(selector.slice(i, j + 1));
+            i = j + 1;
+        }
+        else {
+            const nextQuote = selector.slice(i).search(/['"]/);
+            const segment = nextQuote === -1 ? selector.slice(i) : selector.slice(i, i + nextQuote);
+            parts.push(segment.replace(pattern, (m) => { var _a; return (_a = SHORTHANDS[m]) !== null && _a !== void 0 ? _a : m; }));
+            i = nextQuote === -1 ? selector.length : i + nextQuote;
+        }
+    }
+    return parts.join("");
+}
+function extractFirstLine(source, node) {
+    var _a;
+    if (!source || node.start == null)
+        return "";
+    const text = source.slice(node.start, (_a = node.end) !== null && _a !== void 0 ? _a : node.start);
+    return text.split("\n")[0].trim();
+}
+export function validateSelector(selector) {
+    esquery.parse(expandShorthands(selector));
+}
+export function runQuery(selector, ast, source = "", filename = "") {
+    const expanded = expandShorthands(selector);
+    // Cast to any: esquery expects estree.Node but Babel AST is structurally
+    // compatible; VISITOR_KEYS ensures correct traversal of Babel-specific nodes.
+    const nodes = esquery.query(ast, expanded, {
+        visitorKeys: VISITOR_KEYS,
+    });
+    return nodes.map((node) => {
+        var _a, _b, _c, _d;
+        return ({
+            file: filename,
+            line: (_b = (_a = node.loc) === null || _a === void 0 ? void 0 : _a.start.line) !== null && _b !== void 0 ? _b : 0,
+            col: (_d = (_c = node.loc) === null || _c === void 0 ? void 0 : _c.start.column) !== null && _d !== void 0 ? _d : 0,
+            source: extractFirstLine(source, node),
+        });
+    });
+}

package/build/walk.js

@@ -0,0 +1,54 @@
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { readdir } from "node:fs/promises";
+import { extname, join } from "node:path";
+const SUPPORTED_EXTENSIONS = new Set([
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".mjs",
+    ".cjs",
+    ".vue",
+]);
+export function walkRepoFiles(dir) {
+    return __asyncGenerator(this, arguments, function* walkRepoFiles_1() {
+        const entries = yield __await(readdir(dir, { withFileTypes: true }));
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            if (entry.name === "node_modules")
+                continue;
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                yield __await(yield* __asyncDelegator(__asyncValues(walkRepoFiles(fullPath))));
+            }
+            else if (entry.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry.name))) {
+                yield yield __await(fullPath);
+            }
+        }
+    });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ast-search",
+  "version": "0.1.0",
+  "description": "",
+  "main": "main.js",
+  "scripts": {
+    "dev": "npx tsc --watch",
+    "debug:vue": "npx tsc && node ./build/main.js 'setup > this' --dir src/__tests__/dummyFiles",
+    "debug:react": "npx tsc && node ./build/main.js 'useState' --dir src/__tests__/dummyFiles",
+    "debug:empty": "npx tsc && node ./build/main.js 'ValidationsTab > this' --dir src/__tests__/dummyFiles",
+    "debug:basics": "npx tsc && node ./build/main.js 'arrowFunction' --dir src/__tests__/dummyFiles",
+    "test": "jest",
+    "build": "npx tsc && cp build/main.js ast-search",
+    "prepublishOnly": "npx tsc"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "author": "shiplet",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shiplet/ast-search.git"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "dependencies": {
+    "@babel/parser": "^7.24.4",
+    "@babel/types": "^7.24.0",
+    "esquery": "^1.7.0",
+    "yargs": "^17.7.2"
+  },
+  "bin": {
+    "ast-search": "./build/main.js"
+  },
+  "files": [
+    "build/*.js",
+    "build/helpers/*.js",
+    "README.md"
+  ],
+  "pkg": {
+    "targets": [
+      "node18",
+      "macos-x64"
+    ]
+  },
+  "devDependencies": {
+    "@babel/preset-typescript": "^7.24.1",
+    "@jest/globals": "^29.7.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.0.0",
+    "@semantic-release/npm": "^13.1.3",
+    "@types/esquery": "^1.5.4",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.7",
+    "jest": "^29.7.0",
+    "memfs": "^4.8.1",
+    "semantic-release": "^25.0.3",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  }
+}