yuku-ast 0.1.7 → 0.6.8

package/README.md

@@ -1,146 +1,129 @@
 # yuku-ast
 
-A fast, fully typed AST toolkit for [`yuku-parser`](https://www.npmjs.com/package/yuku-parser):
-node builders, type guards, and identifier validators.
+A typed, mutating AST walker and syntactic utilities for JavaScript and TypeScript ESTree trees, powered by [Yuku](https://github.com/yuku-toolchain/yuku).
 
-| Import                | Provides                                |
-| --------------------- | --------------------------------------- |
-| `yuku-ast`            | `b` (node builders), `is` (type guards) |
-| `yuku-ast/utils`      | node utilities such as `nameOf`         |
-| `yuku-ast/identifier` | identifier and reserved-word validators |
-
-```ts
-import { parse } from "yuku-parser";
-import { b, is } from "yuku-ast";
-
-const { program } = parse("const greet = 1;");
-
-const decl = program.body[0];
-if (is.VariableDeclaration(decl)) {
-  // `decl` is narrowed; swap the initializer for a freshly built node.
-  decl.declarations[0].init = b.numericLiteral(42);
-}
-```
+Works with any ESTree / TypeScript-ESTree AST. Traversal order is driven by tables generated from the [yuku-parser](https://www.npmjs.com/package/yuku-parser) AST definition, so it can never drift from the parser, and there is no runtime key discovery.
 
 ## Install
 
-```sh
-bun add yuku-ast
+```bash
+npm install yuku-ast
 ```
 
-## Type guards (`is`)
+## Walking
 
-A guard for every node `type`, the alias families, and the variants that share a
-`type` string. All accept `null` / `undefined` and return `false`.
+Handlers are keyed by node `type`, by alias group, or the universal `enter` / `leave`. Every handler receives the exact node type.
 
 ```ts
-import { is } from "yuku-ast";
-
-is.CallExpression(node); // every concrete type
-is.Expression(node); // families
-is.StringLiteral(node); // Literal variants
-is.StaticMemberExpression(node); // MemberExpression variants
-
-is.Identifier(node, "this"); // an Identifier with that exact name
-is.oneOf(node, ["CallExpression", "NewExpression"]); // any of these types
+import { parse } from "yuku-parser";
+import { walk } from "yuku-ast";
+
+const { program } = parse(source);
+
+walk(program, {
+  Identifier(node) {
+    console.log(node.name);
+  },
+  CallExpression: {
+    enter(node, ctx) {},
+    leave(node, ctx) {},
+  },
+  Function(node) {
+    // fires for function declarations, expressions, and arrows
+  },
+  enter(node) {},
+});
 ```
 
-`is.oneOf(node, types)` narrows to the union of the listed types, and
-`is.Identifier(node, name?)` narrows to `Identifier`. A matching guard narrows the
-node for typed field access:
+Aliases: `Expression`, `Statement`, `Declaration`, `ModuleDeclaration`, `Function`, `Class`, `Method`, `Loop`, `Pattern`, `JSX`, `TSType`. Per node the order is universal `enter`, alias enters, the typed enter, children, then the mirror for leave.
 
-```ts
-const element = arrayExpression.elements[0];
-if (is.Identifier(element)) {
-  element.name; // `element` is narrowed to Identifier
-}
-```
+The context exposes the position (`ctx.parent`, `ctx.key`, `ctx.index`, `ctx.ancestors()`), flow control (`ctx.skip()`, `ctx.stop()`), and in-place mutation: `ctx.replace(node)` continues into the replacement, `ctx.remove()` skips the removed subtree, `ctx.insertBefore(node)` inserts a sibling without visiting it, `ctx.insertAfter(node)` inserts one the walk visits. An optional third argument threads state to every handler as `ctx.state`.
 
-Aliases: `Expression`, `Statement`, `Declaration`, `ModuleDeclaration`,
-`Function`, `Class`, `Method`, `Loop`, `Pattern`, `JSX`, `TSType`.
+`walkAsync` is the async counterpart: identical traversal and mutation semantics, every handler awaited before the walk moves on.
 
-## Reading names (`nameOf`)
+## Builders
 
-`nameOf(node)` returns the static name a node denotes, an `Identifier`'s `name`
-or a string `Literal`'s `value`, and `null` for anything else (including `null`
-or `undefined`). It reads the common `Identifier | StringLiteral` slots, such as
-a `ModuleExportName` or a static property or member key, in one call.
+One constructor per node type, its fields derived from the node type itself, so a builder can never drift from the AST. Spans default to 0, which `ctx.replace` fills from the replaced node.
 
 ```ts
-import { nameOf } from "yuku-ast/utils";
+import { b } from "yuku-ast";
+
+b.Identifier({ name: "x" });
+b.CallExpression({ callee: b.Identifier({ name: "f" }), arguments: [], optional: false });
+```
 
-// `export { x as y }` and `export { x as "z" }` both resolve.
-nameOf(specifier.exported); // "y", "z"
+## Guards
 
-// A static (non-computed) property key, else null.
-if (!property.computed) nameOf(property.key);
+```ts
+import { is } from "yuku-ast";
+
+is.CallExpression(node);
+is.Identifier(node, "require");
+is.oneOf(node, ["FunctionDeclaration", "ClassDeclaration"]);
+is.Expression(node);
+is.StringLiteral(node);
+is.StaticMemberExpression(node);
+is.Directive(node);
 ```
 
-## Builders (`b`)
+One guard per concrete node type, per alias group, and for the common shapes ESTree folds into one type: literal kinds, member expression kinds, and directives. Every guard accepts `null` and `undefined` and narrows.
 
-A builder for every node type. Required fields are positional, the rest go in a
-trailing options object. Synthetic nodes get a zero span.
+## Modules
 
 ```ts
-import { b } from "yuku-ast";
+import { collectImports, collectExports } from "yuku-ast";
+
+for (const record of collectImports(program)) {
+  record.source;   // "./m"
+  record.local;    // the local binding name
+  record.imported; // "default", "*", or the export name
+  record.typeOnly; // import type / import { type x }
+  record.phase;    // "source" | "defer" | null
+}
 
-b.identifier("x");
-b.callExpression(b.identifier("f"), [b.numericLiteral(1)]);
-b.arrowFunctionExpression([b.identifier("a")], b.identifier("a"));
-b.variableDeclaration("const", [b.variableDeclarator(b.identifier("x"), b.numericLiteral(0))]);
+for (const record of collectExports(program)) {
+  record.exported; // the exported name, null for bare export *
+  record.local;    // the backing local name, when there is one
+  record.source;   // the re-export specifier, when there is one
+  record.typeOnly;
+}
 ```
 
-When you assign a synthetic node in place of an existing one, copy the original's
-`start` / `end` first so [`yuku-codegen`](https://www.npmjs.com/package/yuku-codegen)
-source maps still point back to the original input.
+Declaration forms expand to one record per bound name, destructuring included. The per-declaration forms `collectImportDeclaration` and `collectExportDeclaration` return the records of a single statement, composing with a walk:
 
-## Build and print
+```ts
+walk(program, {
+  ImportDeclaration(node) {
+    records.push(...collectImportDeclaration(node));
+  },
+});
+```
 
-Pair it with [`yuku-codegen`](https://www.npmjs.com/package/yuku-codegen) to print
-a built tree back to source.
+## Utilities
 
 ```ts
-import { print } from "yuku-codegen";
-import { b } from "yuku-ast";
-
-const program = b.program([
-  b.variableDeclaration("const", [b.variableDeclarator(b.identifier("x"), b.numericLiteral(42))]),
-  b.expressionStatement(
-    b.callExpression(b.memberExpression(b.identifier("console"), b.identifier("log")), [
-      b.identifier("x"),
-    ]),
-  ),
-]);
-
-console.log(print(program).code);
-// const x = 42;
-// console.log(x);
+import {
+  nameOf,          // Identifier name or string Literal value
+  literalValue,    // string | number | boolean | bigint | RegExp | null
+  unwrap,          // strips parens and erased TS assertion wrappers
+  isCallOf,        // isCallOf(node, "require")
+  bindingIdentifiers, // every binding Identifier a pattern introduces
+  findAll,         // findAll(program, "CallExpression")
+} from "yuku-ast";
 ```
 
 ## Identifiers
 
-Identifier and reserved-word helpers for raw strings and code points.
-
 ```ts
-import { isIdentifierName, isValidIdentifier } from "yuku-ast/identifier";
+import { isValidIdentifier, isIdentifierName, isKeyword } from "yuku-ast";
 
-isIdentifierName("π"); // true  - a well-formed IdentifierName
-isIdentifierName("class"); // true  - purely syntactic, keywords included
-isValidIdentifier("class"); // false - rejects reserved words (use for bindings)
-isValidIdentifier("π"); // true
+isValidIdentifier("foo");   // true
+isValidIdentifier("class"); // false, reserved
+isIdentifierName("class");  // true, syntactically an IdentifierName
 ```
 
-| Function                                         | Checks                                                                    |
-| ------------------------------------------------ | ------------------------------------------------------------------------- |
-| `isIdentifierName(name)`                         | `name` is a syntactically valid `IdentifierName`                          |
-| `isValidIdentifier(name, reserved?)`             | a valid binding name; rejects reserved words unless `reserved` is `false` |
-| `isIdentifierStart(cp)` / `isIdentifierChar(cp)` | a code point may start / continue an identifier                           |
-| `isKeyword(word)`                                | `word` is a core grammar keyword (`if`, `class`, …)                       |
-| `isReservedWord(word, inModule?)`                | reserved everywhere (`enum`; `await` in modules)                          |
-| `isStrictReservedWord(word, inModule?)`          | also reserved in strict mode (`let`, `yield`, …)                          |
-| `isStrictBindOnlyReservedWord(word)`             | `eval` / `arguments`                                                      |
-| `isStrictBindReservedWord(word, inModule?)`      | strict reserved, plus `eval` / `arguments`                                |
+Plus `isIdentifierStart`, `isIdentifierChar`, `isReservedWord`, `isStrictReservedWord`, `isStrictBindReservedWord`, `isStrictBindOnlyReservedWord`.
 
-## License
+## Semantic analysis
 
-MIT
+[`yuku-analyzer`](https://www.npmjs.com/package/yuku-analyzer) builds on this walker and adds full semantics: scopes, symbols, resolved references, closure analysis, and cross-file module linking, computed natively. Its `module.walk` carries the semantic model in context (`ctx.scope`, `ctx.symbol`, `ctx.reference`).