yuku-analyzer 0.6.4 → 0.6.6

package/README.md

@@ -6,170 +6,61 @@ Full semantic analysis for JavaScript and TypeScript: scopes, symbols, resolved
 
 **At native speed.** Up to ~15× faster per file than `eslint-scope`, `@typescript-eslint/scope-manager`, and `@babel/traverse`, with zero per-query cost after the single native call. Stitch those separate tools together yourself and the gap only widens: each re-walks the AST, you re-parse to resolve across files, and you keep the indexes between them in sync by hand. `yuku-analyzer` pays all of that once, in Zig.
 
+## Install
+
 ```bash
 npm install yuku-analyzer
 ```
 
 ## Quick start
 
-```js
-import { Analyzer, SymbolFlags } from "yuku-analyzer";
-
-const analyzer = new Analyzer();
-
-analyzer.addFile("lib.ts", `export const helper = (x: number) => x * 2;`);
-const main = analyzer.addFile(
-  "main.ts",
-  `import { helper } from "./lib.ts";
-   export const out = helper(21);`,
-);
-
-// per-file semantics
-const helperSym = main.rootScope.find("helper");
-console.log(helperSym.has(SymbolFlags.Import)); // true
-console.log(helperSym.references.length); // 1, the call site
-
-// cross-file: follow the import to where helper is actually defined
-const def = helperSym.definition();
-console.log(def.module.path); // "lib.ts"
-console.log(def.symbol.has(SymbolFlags.Const)); // true
-```
-
-## How it works
-
-Nothing semantic is reimplemented in JavaScript. The binder, scope tree, reference resolution, and module records are computed by the same well-tested native analyzer that powers the rest of Yuku, then shipped to JavaScript as one compact buffer that the JS side only decodes, through lazy zero-copy views. That handoff is usually where native tooling stalls: either every query pays an FFI round trip, or the semantics get a hand-written JS twin that slowly drifts. Here there is one implementation and one crossing, so it cannot drift, and the corner cases arrive already correct: catch-clause scope sharing, named function expression scopes, `var` hoist targets, TS declaration merging, space-aware resolution (a `const T` never captures a type-position `T` away from an outer `type T`), and write detection through destructuring patterns.
-
-## What one `addFile` gives you
+For one file, `analyze` returns the full per-file semantics in a call:
 
 ```js
-const module = analyzer.addFile("app.tsx", source);
-
-module.ast                  // ESTree / TS-ESTree program
-module.scopes               // every lexical scope, as a tree
-module.symbols              // every declared binding
-module.references           // every identifier use, resolved to its symbol
-module.unresolvedReferences // free names and globals
-module.imports              // import records, dynamic import() and require() included
-module.exports              // spec-true export records
-module.moduleFlags          // CommonJS classification signals
-module.diagnostics          // syntax + semantic errors
-```
-
-And node-level queries that work directly on AST nodes:
+import { analyze } from "yuku-analyzer";
 
-```js
-module.symbolOf(node)    // the symbol a node declares or references
-module.referenceOf(node) // the reference recorded for an identifier
-module.scopeOf(node)     // the innermost scope containing the node
-module.parentOf(node)    // the node that structurally contains it, or null
-module.resolve("name")             // scope-chain lookup, like the engine at runtime
-module.resolve("T", scope, "type") // or in another declaration space
-```
-
-Every reference carries the declaration space its position resolves in (`ref.space`: `"value"`, `"type"`, `"namespace"`, `"typeof"`, or `"any"`), and resolution is space-aware the way TypeScript's is: an inner `const T` does not capture a type annotation's `T` away from an outer `type T`.
-
-Node identity is exact: the node you reach by walking `module.ast` and the node a semantic query returns are the same JavaScript object, so `===` always works.
-
-## Editing the AST
-
-That identity is the payoff. Because the `node` on a symbol or reference _is_ the AST node, a refactor is a plain assignment, and [`yuku-codegen`](https://www.npmjs.com/package/yuku-codegen) prints the mutated tree back to source. No visitor to register, no separate model to translate back.
-
-```js
-import { print } from "yuku-codegen";
-
-const m = analyzer.addFile("util.ts", `const tmp = load();\nexport const data = tmp.value + tmp.size;`);
-const tmp = m.rootScope.find("tmp");
-tmp.declarations[0] === m.ast.body[0].declarations[0].id; // true, literally the same node
-
-tmp.declarations[0].name = "raw"; // rename the binding
-for (const ref of tmp.references) ref.node.name = "raw"; // and every resolved use
-
-// across files, analyzer.referencesOf(symbol) hands back these same live nodes for every use
-print(m.ast).code;
-// const raw = load();
-// export const data = raw.value + raw.size;
-```
+const module = analyze(`const double = (n: number) => n * 2; double(21);`, { lang: "ts" });
 
-The uses come from resolved references, not a name search, so a shadowing inner `tmp` is left untouched: the rename only reaches the identifiers that actually bind to this symbol.
-
-## Walking with semantic context
-
-`module.walk` is a typed visitor walk where every handler also receives the current scope, symbol, and reference. No manual scope tracking, ever:
-
-```js
+module.rootScope.find("double").references.length; // 1
 module.walk({
   Identifier(node, ctx) {
-    if (ctx.reference?.isWrite && ctx.symbol?.has(SymbolFlags.Import)) {
-      console.log(`${node.name} assigns to an import`);
-    }
-  },
-  FunctionDeclaration: {
-    enter(node, ctx) {
-      console.log(node.id.name, "declared in a", ctx.scope.kind, "scope");
-    },
+    console.log(node.name, ctx.scope.kind, ctx.symbol, ctx.reference);
   },
 });
 ```
 
-The walk mutates in place: `ctx.replace(node)`, `ctx.remove()`, `ctx.insertBefore(node)`, `ctx.insertAfter(node)`, plus `ctx.skip()` and `ctx.stop()`. Transform the AST during the walk and print it with [`yuku-codegen`](https://www.npmjs.com/package/yuku-codegen).
-
-## Closure analysis
-
-`capturesOf` reports the free variables of any function: every outer binding it closes over, with the capturing reference sites and whether the function writes to the binding. Shadowing and aliasing are handled by the resolved reference table, not by name matching:
-
-```js
-const [fn] = main.findAll("FunctionDeclaration");
-for (const capture of main.capturesOf(fn)) {
-  console.log(capture.symbol.name, capture.isWritten ? "(written)" : "");
-}
-```
-
-## Cross-file analysis
-
-The analyzer joins imports to exports across every added file with the spec's ResolveExport semantics: re-export and `export *` chains are followed per name, `default` never travels through `export *`, and a name supplied by multiple `export *` declarations through different bindings is reported as ambiguous.
+For a project, `Analyzer` adds files and links them:
 
 ```js
-// where is this binding actually defined?
-analyzer.definitionOf(symbol); // { module, symbol } or null for external modules
-
-// every use across the whole graph, imports followed back
-analyzer.referencesOf(symbol); // [{ module, reference }, ...]
-
-module.exportedNames(); // every exported name, `export *` chains included
-module.dependencies;    // modules this file imports from
-module.dependents;      // modules that import this file
-analyzer.diagnostics;   // e.g. "Module './lib.ts' has no export 'helpr'"
-```
+import { Analyzer, SymbolFlags } from "yuku-analyzer";
 
-Linking is automatic: every cross-file surface relinks on demand after files change. Re-adding a path replaces its module with a new object and relinks, and removing it relinks too. Call `analyzer.link()` explicitly if you want to control when the work happens.
+const analyzer = new Analyzer();
 
-Module records and linking model ECMAScript and TypeScript module syntax, so CommonJS `require` and `module.exports` are ordinary code rather than records and take no part in linking. Per-file scopes, symbols, and references are still computed for CommonJS sources.
+analyzer.addFile("lib.ts", `export const helper = (x: number) => x * 2;`);
+const main = analyzer.addFile("main.ts", `import { helper } from "./lib.ts"; helper(21);`);
 
-Module resolution is pluggable. The default resolves relative specifiers among added files with standard extension and index probing. Pass your own resolver for anything else:
+const helper = main.rootScope.find("helper");
+helper.has(SymbolFlags.Import); // true
 
-```js
-const analyzer = new Analyzer({
-  resolve: (specifier, importerPath) => myResolver(specifier, importerPath),
-});
+const def = helper.definition(); // follow the import across files
+def.module.path; // "lib.ts"
 ```
 
-## Performance
-
-Analysis runs in the native parser pass, so full semantics cost roughly half of parsing time on top of the parse itself. Validated against every file in the [parser test corpus](https://yuku.fyi/testing/).
+## What you get
 
-Concretely, on an Apple M-series machine: parsing plus complete semantic analysis of a typical source file lands well under a millisecond, walking sustains tens of millions of nodes per second, and linking a 2,000-module graph takes about a millisecond.
+- **Scopes** as a tree, with `var` hoist targets, catch-clause sharing, and named-expression scopes exact.
+- **Symbols** with TypeScript declaration merging, queried through one `SymbolFlags` bitset.
+- **References** resolved and space-aware, so a value never captures a same-named type.
+- **Node queries** on object identity: `symbolOf`, `referenceOf`, `scopeOf`, `parentOf`, `resolve`.
+- **A semantic walk** and `walkAsync`, every handler receiving the current scope, symbol, and reference.
+- **Closure analysis** via `capturesOf`, shadowing- and alias-correct.
+- **Cross-file linking**: `definition()`, `referencesOf`, `exportedNames`, and spec-true `ResolveExport` across the graph.
 
-## TypeScript
-
-Everything is fully typed. Visitor handlers receive exact node types, and the semantic surface (`Module`, `Scope`, `Symbol`, `Reference`, `Import`, `Export`, `Capture`) is exported:
-
-```ts
-import type { Module, Symbol, Capture } from "yuku-analyzer";
-```
+Node identity is exact throughout: the node a semantic query returns is the same object you reach by walking `module.ast`, so a rename is a plain assignment and [`yuku-codegen`](https://www.npmjs.com/package/yuku-codegen) prints it back.
 
 ## Documentation
 
-The full documentation, including the architecture, every type, and the design decisions: [yuku.fyi/analyzer](https://yuku.fyi/analyzer).
+The full guide, with the architecture, every API, and the design decisions: **[yuku.fyi/analyzer](https://yuku.fyi/analyzer)**.
 
 ## License
 

package/decode.js

@@ -19,191 +19,7 @@ const TS_METHOD_SIGNATURE_KINDS = ["method", "get", "set"];
 const TS_MODULE_KINDS = ["namespace", "module"];
 const TS_MAPPED_OPTIONAL = [false, true, "+", "-"];
 const TS_MAPPED_READONLY = [null, true, "+", "-"];
-const CHILD_KEYS = Object.create(null);
-function _ck(type, keys) {
-  const prev = CHILD_KEYS[type];
-  if (prev === undefined) CHILD_KEYS[type] = keys;
-  else for (const k of keys) if (!prev.includes(k)) prev.push(k);
-}
-_ck("SequenceExpression", ["expressions"]);
-_ck("ParenthesizedExpression", ["expression"]);
-_ck("ArrowFunctionExpression", ["typeParameters", "params", "returnType", "body"]);
-_ck("FunctionDeclaration", ["id", "typeParameters", "params", "returnType", "body"]);
-_ck("FunctionExpression", ["id", "typeParameters", "params", "returnType", "body"]);
-_ck("TSDeclareFunction", ["id", "typeParameters", "params", "returnType", "body"]);
-_ck("TSEmptyBodyFunctionExpression", ["id", "typeParameters", "params", "returnType", "body"]);
-_ck("BlockStatement", ["body"]);
-_ck("BlockStatement", ["body"]);
-_ck("BinaryExpression", ["left", "right"]);
-_ck("LogicalExpression", ["left", "right"]);
-_ck("ConditionalExpression", ["test", "consequent", "alternate"]);
-_ck("UnaryExpression", ["argument"]);
-_ck("UpdateExpression", ["argument"]);
-_ck("AssignmentExpression", ["left", "right"]);
-_ck("ArrayExpression", ["elements"]);
-_ck("ObjectExpression", ["properties"]);
-_ck("SpreadElement", ["argument"]);
-_ck("Property", ["key", "value"]);
-_ck("MemberExpression", ["object", "property"]);
-_ck("CallExpression", ["callee", "typeArguments", "arguments"]);
-_ck("ChainExpression", ["expression"]);
-_ck("TaggedTemplateExpression", ["tag", "typeArguments", "quasi"]);
-_ck("NewExpression", ["callee", "typeArguments", "arguments"]);
-_ck("AwaitExpression", ["argument"]);
-_ck("YieldExpression", ["argument"]);
-_ck("MetaProperty", ["meta", "property"]);
-_ck("Decorator", ["expression"]);
-_ck("ClassDeclaration", ["decorators", "id", "typeParameters", "superClass", "superTypeArguments", "implements", "body"]);
-_ck("ClassExpression", ["decorators", "id", "typeParameters", "superClass", "superTypeArguments", "implements", "body"]);
-_ck("ClassBody", ["body"]);
-_ck("MethodDefinition", ["decorators", "key", "value"]);
-_ck("TSAbstractMethodDefinition", ["decorators", "key", "value"]);
-_ck("PropertyDefinition", ["decorators", "key", "typeAnnotation", "value"]);
-_ck("AccessorProperty", ["decorators", "key", "typeAnnotation", "value"]);
-_ck("TSAbstractPropertyDefinition", ["decorators", "key", "typeAnnotation", "value"]);
-_ck("TSAbstractAccessorProperty", ["decorators", "key", "typeAnnotation", "value"]);
-_ck("StaticBlock", ["body"]);
-_ck("Super", []);
-_ck("Literal", []);
-_ck("Literal", []);
-_ck("Literal", []);
-_ck("Literal", []);
-_ck("Literal", []);
-_ck("ThisExpression", []);
-_ck("Literal", []);
-_ck("TemplateLiteral", ["quasis", "expressions"]);
-_ck("TemplateElement", []);
-_ck("Identifier", []);
-_ck("PrivateIdentifier", []);
-_ck("Identifier", ["decorators", "typeAnnotation"]);
-_ck("Identifier", []);
-_ck("Identifier", []);
-_ck("ExpressionStatement", ["expression"]);
-_ck("IfStatement", ["test", "consequent", "alternate"]);
-_ck("SwitchStatement", ["discriminant", "cases"]);
-_ck("SwitchCase", ["test", "consequent"]);
-_ck("ForStatement", ["init", "test", "update", "body"]);
-_ck("ForInStatement", ["left", "right", "body"]);
-_ck("ForOfStatement", ["left", "right", "body"]);
-_ck("WhileStatement", ["test", "body"]);
-_ck("DoWhileStatement", ["body", "test"]);
-_ck("BreakStatement", ["label"]);
-_ck("ContinueStatement", ["label"]);
-_ck("LabeledStatement", ["label", "body"]);
-_ck("WithStatement", ["object", "body"]);
-_ck("ReturnStatement", ["argument"]);
-_ck("ThrowStatement", ["argument"]);
-_ck("TryStatement", ["block", "handler", "finalizer"]);
-_ck("CatchClause", ["param", "body"]);
-_ck("DebuggerStatement", []);
-_ck("EmptyStatement", []);
-_ck("VariableDeclaration", ["declarations"]);
-_ck("VariableDeclarator", ["id", "init"]);
-_ck("ExpressionStatement", ["expression"]);
-_ck("AssignmentPattern", ["decorators", "left", "typeAnnotation", "right"]);
-_ck("RestElement", ["decorators", "argument", "typeAnnotation"]);
-_ck("ArrayPattern", ["decorators", "elements", "typeAnnotation"]);
-_ck("ObjectPattern", ["decorators", "properties", "typeAnnotation"]);
-_ck("Property", ["key", "value"]);
-_ck("Program", ["hashbang", "body"]);
-_ck("ImportExpression", ["source", "options"]);
-_ck("ImportDeclaration", ["specifiers", "source", "attributes"]);
-_ck("ImportSpecifier", ["imported", "local"]);
-_ck("ImportDefaultSpecifier", ["local"]);
-_ck("ImportNamespaceSpecifier", ["local"]);
-_ck("ImportAttribute", ["key", "value"]);
-_ck("ExportNamedDeclaration", ["declaration", "specifiers", "source", "attributes"]);
-_ck("ExportDefaultDeclaration", ["declaration"]);
-_ck("ExportAllDeclaration", ["exported", "source", "attributes"]);
-_ck("ExportSpecifier", ["local", "exported"]);
-_ck("TSTypeAnnotation", ["typeAnnotation"]);
-_ck("TSAnyKeyword", []);
-_ck("TSUnknownKeyword", []);
-_ck("TSNeverKeyword", []);
-_ck("TSVoidKeyword", []);
-_ck("TSNullKeyword", []);
-_ck("TSUndefinedKeyword", []);
-_ck("TSStringKeyword", []);
-_ck("TSNumberKeyword", []);
-_ck("TSBigIntKeyword", []);
-_ck("TSBooleanKeyword", []);
-_ck("TSSymbolKeyword", []);
-_ck("TSObjectKeyword", []);
-_ck("TSIntrinsicKeyword", []);
-_ck("TSThisType", []);
-_ck("TSTypeReference", ["typeName", "typeArguments"]);
-_ck("TSQualifiedName", ["left", "right"]);
-_ck("TSTypeQuery", ["exprName", "typeArguments"]);
-_ck("TSImportType", ["source", "options", "qualifier", "typeArguments"]);
-_ck("TSTypeParameter", ["name", "constraint", "default"]);
-_ck("TSTypeParameterDeclaration", ["params"]);
-_ck("TSTypeParameterInstantiation", ["params"]);
-_ck("TSLiteralType", ["literal"]);
-_ck("TSTemplateLiteralType", ["quasis", "types"]);
-_ck("TSArrayType", ["elementType"]);
-_ck("TSIndexedAccessType", ["objectType", "indexType"]);
-_ck("TSTupleType", ["elementTypes"]);
-_ck("TSNamedTupleMember", ["label", "elementType"]);
-_ck("TSOptionalType", ["typeAnnotation"]);
-_ck("TSRestType", ["typeAnnotation"]);
-_ck("TSJSDocNullableType", ["typeAnnotation"]);
-_ck("TSJSDocNonNullableType", ["typeAnnotation"]);
-_ck("TSJSDocUnknownType", []);
-_ck("TSUnionType", ["types"]);
-_ck("TSIntersectionType", ["types"]);
-_ck("TSConditionalType", ["checkType", "extendsType", "trueType", "falseType"]);
-_ck("TSInferType", ["typeParameter"]);
-_ck("TSTypeOperator", ["typeAnnotation"]);
-_ck("TSParenthesizedType", ["typeAnnotation"]);
-_ck("TSFunctionType", ["typeParameters", "params", "returnType"]);
-_ck("TSConstructorType", ["typeParameters", "params", "returnType"]);
-_ck("TSTypePredicate", ["parameterName", "typeAnnotation"]);
-_ck("TSTypeLiteral", ["members"]);
-_ck("TSMappedType", ["key", "constraint", "nameType", "typeAnnotation"]);
-_ck("TSPropertySignature", ["key", "typeAnnotation"]);
-_ck("TSMethodSignature", ["key", "typeParameters", "params", "returnType"]);
-_ck("TSCallSignatureDeclaration", ["typeParameters", "params", "returnType"]);
-_ck("TSConstructSignatureDeclaration", ["typeParameters", "params", "returnType"]);
-_ck("TSIndexSignature", ["parameters", "typeAnnotation"]);
-_ck("TSTypeAliasDeclaration", ["id", "typeParameters", "typeAnnotation"]);
-_ck("TSInterfaceDeclaration", ["id", "typeParameters", "extends", "body"]);
-_ck("TSInterfaceBody", ["body"]);
-_ck("TSInterfaceHeritage", ["expression", "typeArguments"]);
-_ck("TSClassImplements", ["expression", "typeArguments"]);
-_ck("TSEnumDeclaration", ["id", "body"]);
-_ck("TSEnumBody", ["members"]);
-_ck("TSEnumMember", ["id", "initializer"]);
-_ck("TSModuleDeclaration", ["id", "body"]);
-_ck("TSModuleBlock", ["body"]);
-_ck("TSModuleDeclaration", ["id", "body"]);
-_ck("TSParameterProperty", ["decorators", "parameter"]);
-_ck("Identifier", ["typeAnnotation"]);
-_ck("TSAsExpression", ["expression", "typeAnnotation"]);
-_ck("TSSatisfiesExpression", ["expression", "typeAnnotation"]);
-_ck("TSTypeAssertion", ["typeAnnotation", "expression"]);
-_ck("TSNonNullExpression", ["expression"]);
-_ck("TSInstantiationExpression", ["expression", "typeArguments"]);
-_ck("TSExportAssignment", ["expression"]);
-_ck("TSNamespaceExportDeclaration", ["id"]);
-_ck("TSImportEqualsDeclaration", ["id", "moduleReference"]);
-_ck("TSExternalModuleReference", ["expression"]);
-_ck("JSXElement", ["openingElement", "children", "closingElement"]);
-_ck("JSXOpeningElement", ["name", "typeArguments", "attributes"]);
-_ck("JSXClosingElement", ["name"]);
-_ck("JSXFragment", ["openingFragment", "children", "closingFragment"]);
-_ck("JSXOpeningFragment", []);
-_ck("JSXClosingFragment", []);
-_ck("JSXIdentifier", []);
-_ck("JSXNamespacedName", ["namespace", "name"]);
-_ck("JSXMemberExpression", ["object", "property"]);
-_ck("JSXAttribute", ["name", "value"]);
-_ck("JSXSpreadAttribute", ["argument"]);
-_ck("JSXExpressionContainer", ["expression"]);
-_ck("JSXEmptyExpression", []);
-_ck("JSXText", []);
-_ck("JSXSpreadChild", ["expression"]);
-_ck("Hashbang", []);
-const SCOPE_KINDS = ["global", "module", "function", "block", "class", "staticBlock", "expressionName", "tsModule"];
+const SCOPE_KINDS = ["global", "module", "function", "block", "class", "staticBlock", "expressionName", "tsModule", "functionBody"];
 const IMPORT_PHASES = ["source", "defer"];
 const IMPORT_KINDS = ["named", "namespace", "sideEffect", "importEquals", "dynamic", "require"];
 const EXPORT_KINDS = ["named", "reExport", "namespace", "star", "equals", "global"];
@@ -229,10 +45,11 @@ const SymbolFlags = Object.freeze({
   CatchVariable: 1 << 16,
   Exported: 1 << 17,
   Default: 1 << 18,
+  EnumMember: 1 << 19,
   Variable: 3,
   Import: 6144,
-  ValueSpace: 127,
-  TypeSpace: 952,
+  ValueSpace: 524415,
+  TypeSpace: 525240,
   NamespaceSpace: 1136,
 });
 const CHILD_SLOTS = [
@@ -1376,4 +1193,4 @@ function decode(buffer, source) {
     get semantic() { return _semantic(); },
   };
 }
-export { decode, SymbolFlags, CHILD_KEYS };
+export { decode, SymbolFlags };

package/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * yuku-analyzer: semantic analysis for JavaScript and TypeScript.
- */
-
 import type {
   Comment,
   Diagnostic,
@@ -114,14 +110,16 @@ declare const SymbolFlags: {
   readonly Exported: number;
   /** The default export. */
   readonly Default: number;
+  /** A TS enum member, declared in its enum's body scope. */
+  readonly EnumMember: number;
 
   /** Composite: any variable (`var` / `let` / `const`, params, catch). */
   readonly Variable: number;
   /** Composite: any import binding, value or `import type`. */
   readonly Import: number;
-  /** Composite: visible at runtime (var, function, class, enum, value namespace). */
+  /** Composite: visible at runtime (var, function, class, enum and its members, value namespace). */
   readonly ValueSpace: number;
-  /** Composite: referencable from a type position (class, enum, interface, alias, type param). */
+  /** Composite: referencable from a type position (class, enum and its members, interface, alias, type param). */
   readonly TypeSpace: number;
   /** Composite: what a dotted type name starts from (namespace, enum). */
   readonly NamespaceSpace: number;
@@ -151,7 +149,8 @@ type ScopeKind =
   | "class"
   | "staticBlock"
   | "expressionName"
-  | "tsModule";
+  | "tsModule"
+  | "functionBody";
 
 /** A lexical scope in a module's scope tree. */
 interface Scope {
@@ -301,6 +300,23 @@ type Visitors = {
   leave?: WalkHandler;
 };
 
+/** Handler for one node type in an async walk, free to return a promise. */
+type AsyncWalkHandler<T extends Node = Node> = (node: T, ctx: WalkContext<T>) => void | Promise<void>;
+
+/** Enter/leave pair for one node type in an async walk. */
+interface AsyncWalkHooks<T extends Node = Node> {
+  enter?: AsyncWalkHandler<T>;
+  leave?: AsyncWalkHandler<T>;
+}
+
+/** {@link Visitors}, with handlers that may return promises. */
+type AsyncVisitors = {
+  [K in NodeType]?: AsyncWalkHandler<NodeOfType<K>> | AsyncWalkHooks<NodeOfType<K>>;
+} & {
+  enter?: AsyncWalkHandler;
+  leave?: AsyncWalkHandler;
+};
+
 /** A free variable of a function, as reported by {@link Module.capturesOf}. */
 interface Capture {
   /** The outer binding being closed over. */
@@ -431,7 +447,9 @@ interface Module {
    * find the nearest binding of `name` visible in `space` (default:
    * `"value"`, resolving like runtime code). A binding outside the
    * space does not shadow, the walk keeps going. `"any"` matches by
-   * name alone.
+   * name alone. A value-position `arguments` lookup stops at the
+   * first non-arrow function or static block, where the implicit
+   * arguments object shadows any outer binding of that name.
    */
   resolve(name: string, from?: Scope, space?: Space): Symbol | null;
   /**
@@ -463,6 +481,13 @@ interface Module {
    */
   walk(visitors: Visitors, root?: Node): void;
 
+  /**
+   * The async counterpart of {@link Module.walk}: identical traversal
+   * order and mutation semantics, with every handler awaited before
+   * the walk moves on.
+   */
+  walkAsync(visitors: AsyncVisitors, root?: Node): Promise<void>;
+
   /** Collects every node of the given type(s), in source order. */
   findAll<K extends NodeType>(type: K): NodeOfType<K>[];
   findAll<K extends NodeType>(types: Iterable<K>): NodeOfType<K>[];
@@ -493,6 +518,29 @@ interface ModuleReference {
   readonly reference: Reference;
 }
 
+/** Options for {@link analyze}: {@link AddFileOptions} plus the module path. */
+interface AnalyzeOptions extends AddFileOptions {
+  /**
+   * The path recorded on the module, also the default source of
+   * `lang` and `sourceType`.
+   * @default "input.js"
+   */
+  path?: string;
+}
+
+/**
+ * Parses and analyzes a single file, the shorthand for one-file
+ * semantics: scopes, symbols, resolved references, and a semantic
+ * walk. Cross-file surfaces stay empty, use {@link Analyzer} and
+ * {@link Analyzer.addFile} for multi-file projects and linking.
+ *
+ * ```ts
+ * const module = analyze(`const x = 1; x;`, { lang: "ts" });
+ * module.walk({ Identifier(node, ctx) { ctx.symbol; } });
+ * ```
+ */
+declare function analyze(source: string, options?: AnalyzeOptions): Module;
+
 /**
  * The project: a set of analyzed modules and the links between them.
  *
@@ -559,12 +607,17 @@ declare function langFromPath(path: string): SourceLang;
 declare function sourceTypeFromPath(path: string): SourceType;
 
 export {
+  analyze,
   Analyzer,
   SymbolFlags,
   langFromPath,
   sourceTypeFromPath,
   type AddFileOptions,
+  type AnalyzeOptions,
   type AnalyzerOptions,
+  type AsyncVisitors,
+  type AsyncWalkHandler,
+  type AsyncWalkHooks,
   type Capture,
   type Definition,
   type Export,

package/index.js

@@ -1,2 +1,9 @@
-export { Analyzer } from "./analyzer.js";
+import { Analyzer } from "./analyzer.js";
+
+export { Analyzer };
 export { SymbolFlags, langFromPath, sourceTypeFromPath } from "./module.js";
+
+export function analyze(source, options = {}) {
+  const { path = "input.js", ...rest } = options;
+  return new Analyzer().addFile(path, source, rest);
+}

package/module.js

@@ -1,7 +1,7 @@
 // one analyzed file, its AST plus a lazily built semantic graph
 import binding from "./binding.js";
 import { decode, SymbolFlags } from "./decode.js";
-import { walkModule } from "./walk.js";
+import { walkModule, walkModuleAsync } from "./walk.js";
 
 export function langFromPath(path) {
   if (path.endsWith(".d.ts") || path.endsWith(".d.mts") || path.endsWith(".d.cts")) return "dts";
@@ -344,19 +344,32 @@ export class Module {
 
   // structural parent, or null at the root or for a foreign node
   parentOf(node) {
+    // the synthesized hashbang has no native index, its parent is the program
+    if (node?.type === "Hashbang") {
+      return node === this.ast.hashbang ? this.ast : null;
+    }
     const index = this.#r.indexOf(node);
     if (index === undefined) return null;
     const parent = this.#r.parentIndex(index);
     return parent < 0 ? null : this.#r.nodeOf(parent);
   }
 
-  // the space filters what the name can see, exactly like reference
-  // resolution: a binding outside the space does not shadow, the walk
-  // keeps going. "any" matches by name alone
+  // mirrors reference resolution: a binding outside the space does not
+  // shadow, "any" matches by name alone, and a value-position arguments
+  // lookup stops where the implicit arguments object shadows
   resolve(name, from = this.rootScope, space = "value") {
+    const argumentsBarrier =
+      name === "arguments" && (space === "value" || space === "typeof");
     for (let s = from; s; s = s.parent) {
       const found = s.find(name);
       if (found && found.visibleIn(space)) return found;
+      if (
+        argumentsBarrier &&
+        (s.kind === "staticBlock" ||
+          (s.kind === "function" && s.node.type !== "ArrowFunctionExpression"))
+      ) {
+        return null;
+      }
     }
     return null;
   }
@@ -417,6 +430,10 @@ export class Module {
     walkModule(this, visitor, root);
   }
 
+  walkAsync(visitor, root) {
+    return walkModuleAsync(this, visitor, root);
+  }
+
   findAll(types) {
     const single = typeof types === "string" ? types : null;
     const set = single === null ? new Set(types) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-analyzer",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Full JavaScript and TypeScript semantic analysis: scopes, symbols, resolved references, closures, and cross-file module linking, computed natively in Zig and queried as plain JavaScript objects",
   "license": "MIT",
   "repository": {
@@ -16,22 +16,21 @@
     "analyzer.js",
     "module.js",
     "walk.js",
-    "engine.js",
     "binding.js",
     "decode.js"
   ],
   "optionalDependencies": {
-    "@yuku-analyzer/binding-linux-x64-gnu": "0.6.4",
-    "@yuku-analyzer/binding-linux-arm64-gnu": "0.6.4",
-    "@yuku-analyzer/binding-linux-arm-gnu": "0.6.4",
-    "@yuku-analyzer/binding-linux-x64-musl": "0.6.4",
-    "@yuku-analyzer/binding-linux-arm64-musl": "0.6.4",
-    "@yuku-analyzer/binding-linux-arm-musl": "0.6.4",
-    "@yuku-analyzer/binding-darwin-x64": "0.6.4",
-    "@yuku-analyzer/binding-darwin-arm64": "0.6.4",
-    "@yuku-analyzer/binding-win32-x64": "0.6.4",
-    "@yuku-analyzer/binding-win32-arm64": "0.6.4",
-    "@yuku-analyzer/binding-freebsd-x64": "0.6.4"
+    "@yuku-analyzer/binding-linux-x64-gnu": "0.6.6",
+    "@yuku-analyzer/binding-linux-arm64-gnu": "0.6.6",
+    "@yuku-analyzer/binding-linux-arm-gnu": "0.6.6",
+    "@yuku-analyzer/binding-linux-x64-musl": "0.6.6",
+    "@yuku-analyzer/binding-linux-arm64-musl": "0.6.6",
+    "@yuku-analyzer/binding-linux-arm-musl": "0.6.6",
+    "@yuku-analyzer/binding-darwin-x64": "0.6.6",
+    "@yuku-analyzer/binding-darwin-arm64": "0.6.6",
+    "@yuku-analyzer/binding-win32-x64": "0.6.6",
+    "@yuku-analyzer/binding-win32-arm64": "0.6.6",
+    "@yuku-analyzer/binding-freebsd-x64": "0.6.6"
   },
   "keywords": [
     "analyzer",
@@ -49,6 +48,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@yuku-toolchain/types": "0.5.43"
+    "@yuku-toolchain/types": "0.6.5",
+    "yuku-ast": "0.6.5"
   }
 }

package/walk.js

@@ -1,4 +1,4 @@
-import { WalkContext, _walk } from "./engine.js";
+import { WalkContext, _walk, _walkAsync } from "yuku-ast";
 
 class SemanticWalkContext extends WalkContext {
   #module;
@@ -23,3 +23,7 @@ class SemanticWalkContext extends WalkContext {
 export function walkModule(module, visitors, root) {
   _walk(root ?? module.ast, visitors, undefined, new SemanticWalkContext(module));
 }
+
+export function walkModuleAsync(module, visitors, root) {
+  return _walkAsync(root ?? module.ast, visitors, undefined, new SemanticWalkContext(module));
+}

package/engine.js

@@ -1,184 +0,0 @@
-import { CHILD_KEYS } from "./decode.js";
-
-export class WalkContext {
-  _ancestors = [];
-  _node = null;
-  _key = null;
-  _list = null;
-  _frame = null;
-  _skip = false;
-  _stopped = false;
-  _removed = false;
-  _replacement = null;
-  state;
-
-  get node() {
-    return this._node;
-  }
-  get parent() {
-    const a = this._ancestors;
-    return a.length === 0 ? null : a[a.length - 1];
-  }
-  get key() {
-    return this._key;
-  }
-  get index() {
-    return this._list === null ? null : this._frame.i;
-  }
-  ancestors() {
-    return [...this._ancestors];
-  }
-  skip() {
-    this._skip = true;
-  }
-  stop() {
-    this._stopped = true;
-  }
-  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");
-    }
-    // synthetic nodes inherit the original span, for source maps
-    if (node.start === 0 && node.end === 0) {
-      node.start = this._node.start;
-      node.end = this._node.end;
-    }
-    this._replacement = node;
-  }
-  remove() {
-    if (this.parent === null) {
-      throw new TypeError("remove: cannot remove the walk root");
-    }
-    this._removed = true;
-  }
-  insertBefore(node) {
-    // advance past the insert so the current node keeps its turn
-    this.#insert(node, 0);
-    this._frame.i++;
-  }
-  insertAfter(node) {
-    // lands at the next slot, so the walk visits it
-    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);
-  }
-}
-
-function createDispatch(visitors) {
-  let enter = null;
-  let leave = null;
-  const concrete = new Map();
-  for (const [name, value] of Object.entries(visitors)) {
-    if (value == null) continue;
-    if (name === "enter") enter = value;
-    else if (name === "leave") leave = value;
-    else if (typeof value === "function") concrete.set(name, { enter: value, leave: null });
-    else concrete.set(name, { enter: value.enter ?? null, leave: value.leave ?? null });
-  }
-  return { enter, leave, typed: (type) => concrete.get(type) };
-}
-
-export function walk(root, visitors, state) {
-  _walk(root, visitors, state, new WalkContext());
-  return root;
-}
-
-export function _walk(root, visitors, state, ctx) {
-  const d = createDispatch(visitors);
-  ctx.state = state;
-  const ancestors = ctx._ancestors;
-
-  function position(node, key, list, frame) {
-    ctx._node = node;
-    ctx._key = key;
-    ctx._list = list;
-    ctx._frame = frame;
-  }
-
-  function applyReplace(parent, key, list, frame) {
-    const next = ctx._replacement;
-    ctx._replacement = null;
-    if (list !== null) list[frame.i] = next;
-    else parent[key] = next;
-    return next;
-  }
-
-  function applyRemove(parent, key, list, frame) {
-    ctx._removed = false;
-    if (list !== null) {
-      list.splice(frame.i, 1);
-      frame.i--;
-    } else {
-      parent[key] = null;
-    }
-  }
-
-  (function visit(node, key, list, frame) {
-    let typed = d.typed(node.type);
-    const parent = ctx.parent;
-
-    position(node, key, list, frame);
-    if (d.enter !== null) {
-      d.enter(node, ctx);
-      if (ctx._stopped) return false;
-    }
-    if (typed !== undefined && typed.enter !== null) {
-      typed.enter(node, ctx);
-      if (ctx._stopped) return false;
-    }
-    if (ctx._removed) {
-      applyRemove(parent, key, list, frame);
-      return true;
-    }
-    if (ctx._replacement !== null) {
-      node = applyReplace(parent, key, list, frame);
-      typed = d.typed(node.type);
-    }
-
-    const skipped = ctx._skip;
-    ctx._skip = false;
-    if (!skipped) {
-      const keys = CHILD_KEYS[node.type];
-      if (keys !== undefined && keys.length > 0) {
-        ancestors.push(node);
-        for (let k = 0; k < keys.length; k++) {
-          const key2 = keys[k];
-          const value = node[key2];
-          if (value === null || value === undefined || typeof value !== "object") continue;
-          if (Array.isArray(value)) {
-            const childFrame = { i: 0 };
-            for (; childFrame.i < value.length; childFrame.i++) {
-              const item = value[childFrame.i];
-              // pattern element holes are null
-              if (item !== null && !visit(item, key2, value, childFrame)) return false;
-            }
-          } else if (!visit(value, key2, null, null)) {
-            return false;
-          }
-        }
-        ancestors.pop();
-      }
-    }
-
-    position(node, key, list, frame);
-    if (typed !== undefined && typed.leave !== null) {
-      typed.leave(node, ctx);
-      if (ctx._stopped) return false;
-    }
-    if (d.leave !== null) {
-      d.leave(node, ctx);
-      if (ctx._stopped) return false;
-    }
-    if (ctx._removed) applyRemove(parent, key, list, frame);
-    else if (ctx._replacement !== null) applyReplace(parent, key, list, frame);
-
-    return true;
-  })(root, null, null, null);
-}