# oxc-walker

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![Github Actions][github-actions-src]][github-actions-href]
[![Codecov][codecov-src]][codecov-href]

A strongly-typed ESTree AST walker built on top of [oxc-parser](https://github.com/oxc-project/oxc).

## Usage

Install package:

```sh
# npm
npm install oxc-walker

# pnpm
pnpm install oxc-walker
```

### Walk a parsed AST

```ts
import { parseSync } from "oxc-parser";
import { walk } from "oxc-walker";

const ast = parseSync("example.js", "const x = 1");

walk(ast.program, {
  enter(node, parent, ctx) {
    // ...
  },
});
```

### Parse and walk directly

```js
import { parseAndWalk } from "oxc-walker";

parseAndWalk("const x = 1", "example.js", (node, parent, ctx) => {
  // ...
});
```

## ⚙️ API

### `walk(ast, options)`

Walk an AST.

```ts
// options
interface WalkOptions {
  /**
   * The function to be called when entering a node.
   */
  enter?: (node: Node, parent: Node | null, ctx: CallbackContext) => void;
  /**
   * The function to be called when leaving a node.
   */
  leave?: (node: Node, parent: Node | null, ctx: CallbackContext) => void;
  /**
   * The instance of `ScopeTracker` to use for tracking declarations and references.
   */
  scopeTracker?: ScopeTracker;
}

interface CallbackContext {
  /**
   * The key of the current node within its parent node object, if applicable.
   */
  key: string | number | symbol | null | undefined;
  /**
   * The zero-based index of the current node within its parent's children array, if applicable.
   */
  index: number | null;
  /**
   * The full Abstract Syntax Tree (AST) that is being walked, starting from the root node.
   */
  ast: Program | Node;
}
```

#### `this.skip()`

When called inside an `enter` callback, prevents the node's children from being walked.
It is not available in `leave`.

#### `this.replace(newNode)`

Replaces the current node with `newNode`. When called inside `enter`, the **new node's children** will be walked.
The leave callback will still be called with the original node.

> ⚠️ When a `ScopeTracker` is provided, calling `this.replace()` will not update its declarations.

#### `this.remove()`

Removes the current node from its parent. When called inside `enter`, the removed node's children
will not be walked.

_This has a higher precedence than `this.replace()`, so if both are called, the node will be removed._

> ⚠️ When a `ScopeTracker` is provided, calling `this.remove()` will not update its declarations.

### `parseAndWalk(source, filename, callback, options?)`

Parse the source code using `oxc-parser`, walk the resulting AST and return the `ParseResult`.

Overloads:

- `parseAndWalk(code, filename, enter)`
- `parseAndWalk(code, filename, options)`

```ts
interface ParseAndWalkOptions {
  /**
   * The function to be called when entering a node.
   */
  enter?: (node: Node, parent: Node | null, ctx: CallbackContext) => void;
  /**
   * The function to be called when leaving a node.
   */
  leave?: (node: Node, parent: Node | null, ctx: CallbackContext) => void;
  /**
   * The instance of `ScopeTracker` to use for tracking declarations and references.
   */
  scopeTracker?: ScopeTracker;
  /**
   * The options for `oxc-parser` to use when parsing the code.
   */
  parseOptions?: ParserOptions;
}
```

### `ScopeTracker`

A utility to track scopes and declarations while walking an AST. It is designed to be used with the `walk`
function from this library.

```ts
interface ScopeTrackerOptions {
  /**
   * If true, the scope tracker will preserve exited scopes in memory.
   * @default false
   */
  preserveExitedScopes?: boolean;
}
```

#### Example usage:

```ts
import { parseAndWalk, ScopeTracker } from "oxc-walker";

const scopeTracker = new ScopeTracker();

parseAndWalk("const x = 1; function foo() { console.log(x) }", "example.js", {
  scopeTracker,
  enter(node, parent) {
    if (node.type === "Identifier" && node.name === "x" && parent?.type === "CallExpression") {
      const declaration = scopeTracker.getDeclaration(node.name);
      console.log(declaration); // ScopeTrackerVariable
    }
  },
});
```

```ts
import { parseAndWalk, ScopeTracker, walk } from "oxc-walker";

const code = `
function foo() {
  console.log(a)
}

const a = 1
`;

const scopeTracker = new ScopeTracker({
  preserveExitedScopes: true,
});

// pre-pass to collect hoisted declarations
const { program } = parseAndWalk(code, "example.js", {
  scopeTracker,
});

// freeze the scope tracker to prevent further modifications
// and prepare it for second pass
scopeTracker.freeze();

// main pass to analyze references
walk(program, {
  scopeTracker,
  enter(node) {
    if (node.type === "CallExpression" && node.callee.type === "MemberExpression" /* ... */) {
      const declaration = scopeTracker.getDeclaration("a");
      console.log(declaration); // ScopeTrackerVariable; would be `null` without the pre-pass
    }
  },
});
```

#### Helpers:

- `scopeTracker.isDeclared(name: string): boolean` - check if an identifier is declared in reference to the current scope
- `scopeTracker.getDeclaration(name: string): ScopeTrackerNode | null` - get the scope tracker node with metadata for a given identifier name in reference to the current scope
- `scopeTracker.freeze()` - freeze the scope tracker to prevent further modifications and prepare for second pass (useful for multi-pass analysis)
- `scopeTracker.getCurrentScope(): string` - get the key of the current scope (a unique identifier for the scope, do not rely on its format)
- `scopeTracker.isCurrentScopeUnder(scopeKey: string): boolean` - check if the current scope is a child of the given scope key

## 💻 Development

- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Run interactive tests using `pnpm dev`

## License

Made with ❤️

Published under [MIT License](./LICENCE).

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/oxc-walker?style=flat-square
[npm-version-href]: https://npmjs.com/package/oxc-walker
[npm-downloads-src]: https://img.shields.io/npm/dm/oxc-walker?style=flat-square
[npm-downloads-href]: https://npm.chart.dev/oxc-walker
[github-actions-src]: https://img.shields.io/github/actions/workflow/status/danielroe/oxc-walker/ci.yml?branch=main&style=flat-square
[github-actions-href]: https://github.com/danielroe/oxc-walker/actions?query=workflow%3Aci
[codecov-src]: https://img.shields.io/codecov/c/gh/danielroe/oxc-walker/main?style=flat-square
[codecov-href]: https://codecov.io/gh/danielroe/oxc-walker