yuku-ast 0.8.6 → 0.9.0

package/README.md

@@ -106,6 +106,7 @@ import {
   nameOf,          // Identifier name or string Literal value
   literalValue,    // string | number | boolean | bigint | RegExp | null
   unwrap,          // strips parens and erased TS assertion wrappers
+  isWrapper,       // true for the wrappers unwrap strips
   isCallOf,        // isCallOf(node, "require")
   bindingIdentifiers, // every binding Identifier a pattern introduces
   findAll,         // findAll(program, "CallExpression")

package/dist/aliases.d.ts

@@ -0,0 +1,22 @@
+import type { NodeOfType } from "@yuku-toolchain/types";
+export declare const ALIAS_GROUPS: {
+    readonly Expression: readonly ["Identifier", "Literal", "ThisExpression", "Super", "ArrayExpression", "ObjectExpression", "FunctionExpression", "ArrowFunctionExpression", "ClassExpression", "TaggedTemplateExpression", "TemplateLiteral", "MemberExpression", "CallExpression", "NewExpression", "ChainExpression", "SequenceExpression", "ParenthesizedExpression", "BinaryExpression", "LogicalExpression", "ConditionalExpression", "UnaryExpression", "UpdateExpression", "AssignmentExpression", "YieldExpression", "AwaitExpression", "ImportExpression", "MetaProperty", "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion", "TSNonNullExpression", "TSInstantiationExpression", "JSXElement", "JSXFragment"];
+    readonly Statement: readonly ["ExpressionStatement", "BlockStatement", "EmptyStatement", "DebuggerStatement", "ReturnStatement", "LabeledStatement", "BreakStatement", "ContinueStatement", "IfStatement", "SwitchStatement", "ThrowStatement", "TryStatement", "WhileStatement", "DoWhileStatement", "ForStatement", "ForInStatement", "ForOfStatement", "WithStatement", "FunctionDeclaration", "ClassDeclaration", "VariableDeclaration", "TSDeclareFunction", "TSTypeAliasDeclaration", "TSInterfaceDeclaration", "TSEnumDeclaration", "TSModuleDeclaration", "TSImportEqualsDeclaration"];
+    readonly Declaration: readonly ["FunctionDeclaration", "ClassDeclaration", "VariableDeclaration", "TSDeclareFunction", "TSTypeAliasDeclaration", "TSInterfaceDeclaration", "TSEnumDeclaration", "TSModuleDeclaration", "TSImportEqualsDeclaration"];
+    readonly ModuleDeclaration: readonly ["ImportDeclaration", "ExportNamedDeclaration", "ExportDefaultDeclaration", "ExportAllDeclaration", "TSExportAssignment", "TSNamespaceExportDeclaration"];
+    readonly Function: readonly ["FunctionDeclaration", "FunctionExpression", "TSDeclareFunction", "TSEmptyBodyFunctionExpression", "ArrowFunctionExpression"];
+    readonly Class: readonly ["ClassDeclaration", "ClassExpression"];
+    readonly Method: readonly ["MethodDefinition", "TSAbstractMethodDefinition"];
+    readonly Loop: readonly ["DoWhileStatement", "ForInStatement", "ForOfStatement", "ForStatement", "WhileStatement"];
+    readonly Pattern: readonly ["ArrayPattern", "ObjectPattern", "AssignmentPattern", "RestElement"];
+    readonly JSX: readonly ["JSXAttribute", "JSXClosingElement", "JSXClosingFragment", "JSXElement", "JSXEmptyExpression", "JSXExpressionContainer", "JSXFragment", "JSXIdentifier", "JSXMemberExpression", "JSXNamespacedName", "JSXOpeningElement", "JSXOpeningFragment", "JSXSpreadAttribute", "JSXSpreadChild", "JSXText"];
+    readonly TSType: readonly ["TSAnyKeyword", "TSUnknownKeyword", "TSNeverKeyword", "TSVoidKeyword", "TSNullKeyword", "TSUndefinedKeyword", "TSStringKeyword", "TSNumberKeyword", "TSBigIntKeyword", "TSBooleanKeyword", "TSSymbolKeyword", "TSObjectKeyword", "TSIntrinsicKeyword", "TSThisType", "TSTypeReference", "TSTypeQuery", "TSImportType", "TSLiteralType", "TSTemplateLiteralType", "TSArrayType", "TSIndexedAccessType", "TSTupleType", "TSNamedTupleMember", "TSJSDocNullableType", "TSJSDocNonNullableType", "TSJSDocUnknownType", "TSUnionType", "TSIntersectionType", "TSConditionalType", "TSInferType", "TSTypeOperator", "TSParenthesizedType", "TSFunctionType", "TSConstructorType", "TSTypePredicate", "TSTypeLiteral", "TSMappedType"];
+};
+export type AliasName = keyof typeof ALIAS_GROUPS;
+type GroupType<A extends AliasName> = (typeof ALIAS_GROUPS)[A][number];
+/** The node union each alias covers, e.g. `AliasMap["Function"]`. */
+export type AliasMap = {
+    [A in AliasName]: NodeOfType<GroupType<A>>;
+};
+export declare const ALIAS_NAMES: readonly AliasName[];
+export {};

package/dist/aliases.js

@@ -0,0 +1,157 @@
+// every group member must be a real node type, and the union-backed
+// groups must match their @yuku-toolchain/types union exactly, both
+// directions checked below
+export const ALIAS_GROUPS = {
+    Expression: [
+        "Identifier",
+        "Literal",
+        "ThisExpression",
+        "Super",
+        "ArrayExpression",
+        "ObjectExpression",
+        "FunctionExpression",
+        "ArrowFunctionExpression",
+        "ClassExpression",
+        "TaggedTemplateExpression",
+        "TemplateLiteral",
+        "MemberExpression",
+        "CallExpression",
+        "NewExpression",
+        "ChainExpression",
+        "SequenceExpression",
+        "ParenthesizedExpression",
+        "BinaryExpression",
+        "LogicalExpression",
+        "ConditionalExpression",
+        "UnaryExpression",
+        "UpdateExpression",
+        "AssignmentExpression",
+        "YieldExpression",
+        "AwaitExpression",
+        "ImportExpression",
+        "MetaProperty",
+        "TSAsExpression",
+        "TSSatisfiesExpression",
+        "TSTypeAssertion",
+        "TSNonNullExpression",
+        "TSInstantiationExpression",
+        "JSXElement",
+        "JSXFragment",
+    ],
+    Statement: [
+        "ExpressionStatement",
+        "BlockStatement",
+        "EmptyStatement",
+        "DebuggerStatement",
+        "ReturnStatement",
+        "LabeledStatement",
+        "BreakStatement",
+        "ContinueStatement",
+        "IfStatement",
+        "SwitchStatement",
+        "ThrowStatement",
+        "TryStatement",
+        "WhileStatement",
+        "DoWhileStatement",
+        "ForStatement",
+        "ForInStatement",
+        "ForOfStatement",
+        "WithStatement",
+        "FunctionDeclaration",
+        "ClassDeclaration",
+        "VariableDeclaration",
+        "TSDeclareFunction",
+        "TSTypeAliasDeclaration",
+        "TSInterfaceDeclaration",
+        "TSEnumDeclaration",
+        "TSModuleDeclaration",
+        "TSImportEqualsDeclaration",
+    ],
+    Declaration: [
+        "FunctionDeclaration",
+        "ClassDeclaration",
+        "VariableDeclaration",
+        "TSDeclareFunction",
+        "TSTypeAliasDeclaration",
+        "TSInterfaceDeclaration",
+        "TSEnumDeclaration",
+        "TSModuleDeclaration",
+        "TSImportEqualsDeclaration",
+    ],
+    ModuleDeclaration: [
+        "ImportDeclaration",
+        "ExportNamedDeclaration",
+        "ExportDefaultDeclaration",
+        "ExportAllDeclaration",
+        "TSExportAssignment",
+        "TSNamespaceExportDeclaration",
+    ],
+    Function: [
+        "FunctionDeclaration",
+        "FunctionExpression",
+        "TSDeclareFunction",
+        "TSEmptyBodyFunctionExpression",
+        "ArrowFunctionExpression",
+    ],
+    Class: ["ClassDeclaration", "ClassExpression"],
+    Method: ["MethodDefinition", "TSAbstractMethodDefinition"],
+    Loop: ["DoWhileStatement", "ForInStatement", "ForOfStatement", "ForStatement", "WhileStatement"],
+    Pattern: ["ArrayPattern", "ObjectPattern", "AssignmentPattern", "RestElement"],
+    JSX: [
+        "JSXAttribute",
+        "JSXClosingElement",
+        "JSXClosingFragment",
+        "JSXElement",
+        "JSXEmptyExpression",
+        "JSXExpressionContainer",
+        "JSXFragment",
+        "JSXIdentifier",
+        "JSXMemberExpression",
+        "JSXNamespacedName",
+        "JSXOpeningElement",
+        "JSXOpeningFragment",
+        "JSXSpreadAttribute",
+        "JSXSpreadChild",
+        "JSXText",
+    ],
+    TSType: [
+        "TSAnyKeyword",
+        "TSUnknownKeyword",
+        "TSNeverKeyword",
+        "TSVoidKeyword",
+        "TSNullKeyword",
+        "TSUndefinedKeyword",
+        "TSStringKeyword",
+        "TSNumberKeyword",
+        "TSBigIntKeyword",
+        "TSBooleanKeyword",
+        "TSSymbolKeyword",
+        "TSObjectKeyword",
+        "TSIntrinsicKeyword",
+        "TSThisType",
+        "TSTypeReference",
+        "TSTypeQuery",
+        "TSImportType",
+        "TSLiteralType",
+        "TSTemplateLiteralType",
+        "TSArrayType",
+        "TSIndexedAccessType",
+        "TSTupleType",
+        "TSNamedTupleMember",
+        "TSJSDocNullableType",
+        "TSJSDocNonNullableType",
+        "TSJSDocUnknownType",
+        "TSUnionType",
+        "TSIntersectionType",
+        "TSConditionalType",
+        "TSInferType",
+        "TSTypeOperator",
+        "TSParenthesizedType",
+        "TSFunctionType",
+        "TSConstructorType",
+        "TSTypePredicate",
+        "TSTypeLiteral",
+        "TSMappedType",
+    ],
+};
+export const ALIAS_NAMES = Object.keys(ALIAS_GROUPS);

package/dist/builders.d.ts

@@ -0,0 +1,19 @@
+import type { Node, NodeOfType, NodeType } from "@yuku-toolchain/types";
+type BuilderInput<T> = T extends Node ? Omit<T, "type" | "start" | "end"> & {
+    start?: number;
+    end?: number;
+} : never;
+type Builders = {
+    [K in NodeType]: (fields: BuilderInput<NodeOfType<K>>) => NodeOfType<K>;
+};
+/**
+ * One constructor per node type, its fields derived from the node type
+ * itself. `start` and `end` default to 0, which `ctx.replace` treats
+ * as span-less and fills from the replaced node.
+ *
+ * @example
+ * b.Identifier({ name: "x" })
+ * b.ExpressionStatement({ expression: b.Identifier({ name: "x" }) })
+ */
+export declare const b: Builders;
+export {};

package/dist/builders.js

@@ -0,0 +1,14 @@
+import { NODE_TYPES } from "./generated.js";
+/**
+ * One constructor per node type, its fields derived from the node type
+ * itself. `start` and `end` default to 0, which `ctx.replace` treats
+ * as span-less and fills from the replaced node.
+ *
+ * @example
+ * b.Identifier({ name: "x" })
+ * b.ExpressionStatement({ expression: b.Identifier({ name: "x" }) })
+ */
+export const b = Object.fromEntries(NODE_TYPES.map((type) => [
+    type,
+    (fields) => ({ type, start: 0, end: 0, ...fields }),
+]));

package/dist/context.d.ts

@@ -0,0 +1,55 @@
+import type { Node } from "@yuku-toolchain/types";
+interface Frame {
+    i: number;
+}
+/**
+ * The walk context: one reused object exposing the current position and
+ * the tree mutation operations. Valid only during the visit that
+ * receives it, do not store it. Underscore members are engine state.
+ */
+export declare class WalkContext<T extends Node = Node, S = unknown> {
+    #private;
+    _ancestors: Node[];
+    _node: Node | null;
+    _key: string | null;
+    _list: Node[] | null;
+    _frame: Frame | null;
+    _skip: boolean;
+    _stopped: boolean;
+    _removed: boolean;
+    _replacement: Node | null;
+    /** State threaded through the walk, the third `walk` argument. */
+    state: S;
+    /** The node being visited. */
+    get node(): T;
+    /** The node holding {@link node}, or null at the walk root. */
+    get parent(): Node | null;
+    /** The field on {@link parent} holding {@link node}, or null at the root. */
+    get key(): string | null;
+    /** Index within an array field, or null in a plain field. */
+    get index(): number | null;
+    /** Ancestors from the walk root down to {@link parent}. */
+    ancestors(): Node[];
+    /** Do not descend into the current node's children. */
+    skip(): void;
+    /** Stop the walk entirely. */
+    stop(): void;
+    /**
+     * Replace the current node. The walk continues into the replacement's
+     * children and `leave` fires for the replacement's type. A synthetic
+     * node with `start === 0 && end === 0` inherits the original span,
+     * for source maps. Throws at the walk root.
+     */
+    replace(node: Node): void;
+    /**
+     * Remove the current node from its parent: spliced from array fields,
+     * nulled in plain fields. Children are not walked and `leave` does
+     * not fire. Throws at the walk root.
+     */
+    remove(): void;
+    /** Insert a sibling before the current node, not visited. Array fields only. */
+    insertBefore(node: Node): void;
+    /** Insert a sibling after the current node, visited by the walk. Array fields only. */
+    insertAfter(node: Node): void;
+}
+export {};

package/dist/context.js

@@ -0,0 +1,92 @@
+/**
+ * The walk context: one reused object exposing the current position and
+ * the tree mutation operations. Valid only during the visit that
+ * receives it, do not store it. Underscore members are engine state.
+ */
+export class WalkContext {
+    _ancestors = [];
+    _node = null;
+    _key = null;
+    _list = null;
+    _frame = null;
+    _skip = false;
+    _stopped = false;
+    _removed = false;
+    _replacement = null;
+    /** State threaded through the walk, the third `walk` argument. */
+    state;
+    /** The node being visited. */
+    get node() {
+        return this._node;
+    }
+    /** The node holding {@link node}, or null at the walk root. */
+    get parent() {
+        const a = this._ancestors;
+        return a.length === 0 ? null : a[a.length - 1];
+    }
+    /** The field on {@link parent} holding {@link node}, or null at the root. */
+    get key() {
+        return this._key;
+    }
+    /** Index within an array field, or null in a plain field. */
+    get index() {
+        return this._list === null ? null : this._frame.i;
+    }
+    /** Ancestors from the walk root down to {@link parent}. */
+    ancestors() {
+        return [...this._ancestors];
+    }
+    /** Do not descend into the current node's children. */
+    skip() {
+        this._skip = true;
+    }
+    /** Stop the walk entirely. */
+    stop() {
+        this._stopped = true;
+    }
+    /**
+     * Replace the current node. The walk continues into the replacement's
+     * children and `leave` fires for the replacement's type. A synthetic
+     * node with `start === 0 && end === 0` inherits the original span,
+     * for source maps. Throws at the walk root.
+     */
+    replace(node) {
+        if (node === null || typeof node !== "object" || typeof node.type !== "string") {
+            throw new TypeError("replace: expected an AST node");
+        }
+        if (this.parent === null) {
+            throw new TypeError("replace: cannot replace the walk root");
+        }
+        if (node.start === 0 && node.end === 0) {
+            node.start = this.node.start;
+            node.end = this.node.end;
+        }
+        this._replacement = node;
+    }
+    /**
+     * Remove the current node from its parent: spliced from array fields,
+     * nulled in plain fields. Children are not walked and `leave` does
+     * not fire. Throws at the walk root.
+     */
+    remove() {
+        if (this.parent === null) {
+            throw new TypeError("remove: cannot remove the walk root");
+        }
+        this._removed = true;
+    }
+    /** Insert a sibling before the current node, not visited. Array fields only. */
+    insertBefore(node) {
+        this.#insert(node, 0);
+        this._frame.i++;
+    }
+    /** Insert a sibling after the current node, visited by the walk. Array fields only. */
+    insertAfter(node) {
+        this.#insert(node, 1);
+    }
+    #insert(node, offset) {
+        if (this._list === null) {
+            throw new TypeError("insertBefore/insertAfter require a node in an array field");
+        }
+        this._list.splice(this._frame.i + offset, 0, node);
+    }
+}

package/dist/generated.d.ts

@@ -0,0 +1,5 @@
+export declare const CHILD_KEYS: Readonly<Record<string, readonly string[]>>;
+declare const TYPES: readonly ["SequenceExpression", "ParenthesizedExpression", "ArrowFunctionExpression", "FunctionDeclaration", "FunctionExpression", "TSDeclareFunction", "TSEmptyBodyFunctionExpression", "BlockStatement", "BlockStatement", "BinaryExpression", "LogicalExpression", "ConditionalExpression", "UnaryExpression", "UpdateExpression", "AssignmentExpression", "ArrayExpression", "ObjectExpression", "SpreadElement", "Property", "MemberExpression", "CallExpression", "ChainExpression", "TaggedTemplateExpression", "NewExpression", "AwaitExpression", "YieldExpression", "MetaProperty", "Decorator", "ClassDeclaration", "ClassExpression", "ClassBody", "MethodDefinition", "TSAbstractMethodDefinition", "PropertyDefinition", "AccessorProperty", "TSAbstractPropertyDefinition", "TSAbstractAccessorProperty", "StaticBlock", "Super", "Literal", "Literal", "Literal", "Literal", "Literal", "ThisExpression", "Literal", "TemplateLiteral", "TemplateElement", "Identifier", "PrivateIdentifier", "Identifier", "Identifier", "Identifier", "ExpressionStatement", "IfStatement", "SwitchStatement", "SwitchCase", "ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "BreakStatement", "ContinueStatement", "LabeledStatement", "WithStatement", "ReturnStatement", "ThrowStatement", "TryStatement", "CatchClause", "DebuggerStatement", "EmptyStatement", "VariableDeclaration", "VariableDeclarator", "ExpressionStatement", "AssignmentPattern", "RestElement", "ArrayPattern", "ObjectPattern", "Property", "Program", "ImportExpression", "ImportDeclaration", "ImportSpecifier", "ImportDefaultSpecifier", "ImportNamespaceSpecifier", "ImportAttribute", "ExportNamedDeclaration", "ExportDefaultDeclaration", "ExportAllDeclaration", "ExportSpecifier", "TSTypeAnnotation", "TSAnyKeyword", "TSUnknownKeyword", "TSNeverKeyword", "TSVoidKeyword", "TSNullKeyword", "TSUndefinedKeyword", "TSStringKeyword", "TSNumberKeyword", "TSBigIntKeyword", "TSBooleanKeyword", "TSSymbolKeyword", "TSObjectKeyword", "TSIntrinsicKeyword", "TSThisType", "TSTypeReference", "TSQualifiedName", "TSTypeQuery", "TSImportType", "TSTypeParameter", "TSTypeParameterDeclaration", "TSTypeParameterInstantiation", "TSLiteralType", "TSTemplateLiteralType", "TSArrayType", "TSIndexedAccessType", "TSTupleType", "TSNamedTupleMember", "TSOptionalType", "TSRestType", "TSJSDocNullableType", "TSJSDocNonNullableType", "TSJSDocUnknownType", "TSUnionType", "TSIntersectionType", "TSConditionalType", "TSInferType", "TSTypeOperator", "TSParenthesizedType", "TSFunctionType", "TSConstructorType", "TSTypePredicate", "TSTypeLiteral", "TSMappedType", "TSPropertySignature", "TSMethodSignature", "TSCallSignatureDeclaration", "TSConstructSignatureDeclaration", "TSIndexSignature", "TSTypeAliasDeclaration", "TSInterfaceDeclaration", "TSInterfaceBody", "TSInterfaceHeritage", "TSClassImplements", "TSEnumDeclaration", "TSEnumBody", "TSEnumMember", "TSModuleDeclaration", "TSModuleBlock", "TSModuleDeclaration", "TSParameterProperty", "Identifier", "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion", "TSNonNullExpression", "TSInstantiationExpression", "TSExportAssignment", "TSNamespaceExportDeclaration", "TSImportEqualsDeclaration", "TSExternalModuleReference", "JSXElement", "JSXOpeningElement", "JSXClosingElement", "JSXFragment", "JSXOpeningFragment", "JSXClosingFragment", "JSXIdentifier", "JSXNamespacedName", "JSXMemberExpression", "JSXAttribute", "JSXSpreadAttribute", "JSXExpressionContainer", "JSXEmptyExpression", "JSXText", "JSXSpreadChild", "Hashbang"];
+export type GeneratedNodeType = (typeof TYPES)[number];
+export declare const NODE_TYPES: readonly GeneratedNodeType[];
+export {};