@ugo-studio/jspp 0.3.0 → 0.3.2

package/dist/{core → interpreter/core}/codegen/function-handlers.js

@@ -5,6 +5,18 @@ import { CodeGenerator } from "./index.js";
 export function generateLambdaComponents(node, context, options) {
     const declaredSymbols = this.getDeclaredSymbols(node);
     const argsName = this.generateUniqueName("__args_", declaredSymbols, context.globalScopeSymbols, context.localScopeSymbols);
+    // const nativeExcessArgsName = this.generateUniqueName(
+    //     "__excess_args",
+    //     declaredSymbols,
+    //     context.globalScopeSymbols,
+    //     context.localScopeSymbols,
+    // );
+    // const nativeTotalArgsSizeName = this.generateUniqueName(
+    //     "__total_args_size",
+    //     declaredSymbols,
+    //     context.globalScopeSymbols,
+    //     context.localScopeSymbols,
+    // );
     const isInsideGeneratorFunction = this.isGeneratorFunction(node);
     const isInsideAsyncFunction = this.isAsyncFunction(node);
     const isArrow = ts.isArrowFunction(node);
@@ -12,15 +24,27 @@ export function generateLambdaComponents(node, context, options) {
         isInsideGeneratorFunction: isInsideGeneratorFunction,
         isInsideAsyncFunction: isInsideAsyncFunction,
     });
-    const funcReturnType = (isInsideGeneratorFunction && isInsideAsyncFunction)
-        ? "jspp::JsAsyncIterator<jspp::AnyValue>"
-        : (isInsideGeneratorFunction
-            ? "jspp::JsIterator<jspp::AnyValue>"
-            : (isInsideAsyncFunction ? "jspp::JsPromise" : "jspp::AnyValue"));
+    const getFuncReturnType = (isInsideNativeLambda) => {
+        if (isInsideGeneratorFunction && isInsideAsyncFunction) {
+            return "jspp::JsAsyncIterator<jspp::AnyValue>";
+        }
+        else if (isInsideGeneratorFunction) {
+            return "jspp::JsIterator<jspp::AnyValue>";
+        }
+        else if (isInsideAsyncFunction)
+            return "jspp::JsPromise";
+        else {
+            const inferedReturnType = this.typeAnalyzer.inferFunctionReturnType(node);
+            if (isInsideNativeLambda && inferedReturnType === "number") {
+                return "double";
+            }
+            return "jspp::AnyValue";
+        }
+    };
     // Lambda arguments: regular functions use std::span for performance.
     // Generators and async functions use std::vector to ensure they are safely copied into the coroutine frame.
     const paramThisType = "jspp::AnyValue";
-    const paramArgsType = (isInsideGeneratorFunction || isInsideAsyncFunction)
+    const paramArgsType = isInsideGeneratorFunction || isInsideAsyncFunction
         ? "std::vector<jspp::AnyValue>"
         : "std::span<const jspp::AnyValue>";
     const globalScopeSymbols = this.prepareScopeSymbolsForVisit(context.globalScopeSymbols, context.localScopeSymbols);
@@ -29,7 +53,7 @@ export function generateLambdaComponents(node, context, options) {
         isMainContext: false,
         isInsideFunction: true,
         isFunctionBody: false,
-        lambdaName: undefined,
+        functionName: undefined,
         globalScopeSymbols,
         localScopeSymbols: new DeclaredSymbols(),
         superClassVar: context.superClassVar,
@@ -59,7 +83,7 @@ export function generateLambdaComponents(node, context, options) {
             nativePreamble +=
                 `${this.indent()}jspp::AnyValue ${this.globalThisVar} = ${finalThisParamName};\n`;
         }
-        // Note: Arguments are now automatically copied into the coroutine frame because 
+        // Note: Arguments are now automatically copied into the coroutine frame because
         // the lambda parameter is passed by value (std::vector).
         // We just need to define argsName as a reference to the parameter.
         preamble +=
@@ -69,17 +93,33 @@ export function generateLambdaComponents(node, context, options) {
     let nativeFuncArgs = "";
     let nativeParamsContent = "";
     this.validateFunctionParams(node.parameters).forEach((p, i) => {
-        const name = ts.isIdentifier(p.name)
-            ? p.name.text
-            : this.generateUniqueName(`__param_native_${i}_`, visitContext.localScopeSymbols);
+        const isIdentifier = ts.isIdentifier(p.name);
+        const name = isIdentifier ? p.name.text : this.generateUniqueName(`__param_native_${i}_`, visitContext.localScopeSymbols);
         const defaultValue = p.initializer
             ? this.visit(p.initializer, visitContext)
             : !!p.dotDotDotToken
                 ? "jspp::AnyValue::make_array(std::vector<jspp::AnyValue>{})"
                 : "jspp::Constants::UNDEFINED";
-        nativeFuncArgs += `, jspp::AnyValue ${name} = ${defaultValue}`;
-        if (!ts.isIdentifier(p.name)) {
-            nativeParamsContent += this.generateDestructuring(p.name, name, visitContext) + ";\n";
+        let signatureName = name;
+        let needsTemp = !isIdentifier;
+        if (isIdentifier) {
+            const scope = this.getScopeForNode(p);
+            const typeInfo = this.typeAnalyzer.scopeManager.lookupFromScope(name, scope);
+            if (typeInfo?.needsHeapAllocation) {
+                needsTemp = true;
+                signatureName = this.generateUniqueName(`__${name}_param_`, visitContext.localScopeSymbols);
+            }
+        }
+        nativeFuncArgs += `, jspp::AnyValue ${signatureName} = ${defaultValue}`;
+        if (needsTemp) {
+            if (isIdentifier) {
+                nativeParamsContent +=
+                    `${this.indent()}auto ${name} = std::make_shared<jspp::AnyValue>(${signatureName});\n`;
+            }
+            else {
+                nativeParamsContent += this.generateDestructuring(p.name, signatureName, visitContext) +
+                    ";\n";
+            }
         }
     });
     // Extract lambda parameters from arguments span/vector
@@ -97,12 +137,11 @@ export function generateLambdaComponents(node, context, options) {
                     checks: { initialized: true },
                 });
                 const scope = this.getScopeForNode(p);
-                const typeInfo = this.typeAnalyzer.scopeManager
-                    .lookupFromScope(name, scope);
+                const typeInfo = this.typeAnalyzer.scopeManager.lookupFromScope(name, scope);
                 // Handle rest parameters
                 if (!!p.dotDotDotToken) {
                     const initValue = `jspp::AnyValue::make_array(${argsName}.subspan(${i}))`;
-                    if (typeInfo.needsHeapAllocation) {
+                    if (typeInfo?.needsHeapAllocation) {
                         paramsCode +=
                             `${this.indent()}auto ${name} = std::make_shared<jspp::AnyValue>(${initValue});\n`;
                     }
@@ -114,7 +153,7 @@ export function generateLambdaComponents(node, context, options) {
                 }
                 // Normal parameter
                 const initValue = `${argsName}.size() > ${i} ? ${argsName}[${i}] : ${defaultValue}`;
-                if (typeInfo && typeInfo.needsHeapAllocation) {
+                if (typeInfo?.needsHeapAllocation) {
                     paramsCode +=
                         `${this.indent()}auto ${name} = std::make_shared<jspp::AnyValue>(${initValue});\n`;
                 }
@@ -131,14 +170,43 @@ export function generateLambdaComponents(node, context, options) {
                 const initValue = `${argsName}.size() > ${i} ? ${argsName}[${i}] : ${defaultValue}`;
                 paramsCode +=
                     `${this.indent()}auto ${tempName} = ${initValue};\n`;
-                paramsCode += this.generateDestructuring(p.name, tempName, visitContext) + ";\n";
+                paramsCode +=
+                    this.generateDestructuring(p.name, tempName, visitContext) +
+                        ";\n";
             }
         });
         return paramsCode;
     };
     // Generate params and function body
     let paramsContent = "";
-    let blockContentWithoutOpeningBrace = "";
+    let getBlockContentWithoutOpeningBrace = () => "";
+    // Generate `arguments` variable if it used in the function body
+    // TODO: compile arguments array from parameters
+    // if (
+    //     this.isVariableUsedWithoutDeclaration("arguments", node.body as ts.Node)
+    // ) {
+    //     // Add span parameter for holding the excess arguments from the caller of the native lambda
+    //     nativeFuncArgs +=
+    //         `, const std::size_t ${nativeTotalArgsSizeName}, std::span<const jspp::AnyValue> ${nativeExcessArgsName} = {}`;
+    //     // this.indentationLevel++;
+    //     // nativeParamsContent +=
+    //     //     `${this.indent()}jspp::AnyValue arguments = jspp::Constants::UNDEFINED;\n`;
+    //     // nativeParamsContent += `${this.indent()}{\n`;
+    //     // this.indentationLevel++;
+    //     // nativeParamsContent +=
+    //     //     `${this.indent()}std::vector<jspp::AnyValue> ${argsName};\n`;
+    //     // this.validateFunctionParams(node.parameters).forEach(
+    //     //     (p, i) => {
+    //     //     },
+    //     // );
+    //     // this.indentationLevel--;
+    //     // nativeParamsContent += `${this.indent()}}\n`;
+    //     // this.indentationLevel--;
+    //     // this.indentationLevel++;
+    //     // paramsContent =
+    //     //     `${this.indent()}jspp::AnyValue arguments = jspp::AnyValue::make_array(${argsName});\n`;
+    //     // this.indentationLevel--;
+    // }
     if (node.body) {
         if (ts.isBlock(node.body)) {
             // Hoist var declarations in the function body
@@ -148,38 +216,65 @@ export function generateLambdaComponents(node, context, options) {
                 preamble += hoistCode;
                 nativePreamble += hoistCode;
             });
+            // Hoist parameters (especially for destructuring)
+            node.parameters.forEach((p) => {
+                if (!ts.isIdentifier(p.name)) {
+                    const hoistCode = this.hoistDeclaration(p, visitContext.localScopeSymbols, node.body);
+                    preamble += hoistCode;
+                    nativePreamble += hoistCode;
+                }
+            });
             this.indentationLevel++;
-            paramsContent = generateParamsBuilder();
+            paramsContent += generateParamsBuilder();
             this.indentationLevel--;
             // The block visitor already adds braces, so we need to remove the opening brace to inject the preamble and param extraction.
-            blockContentWithoutOpeningBrace = this.visit(node.body, {
-                ...visitContext,
-                isMainContext: false,
-                isInsideFunction: true,
-                isFunctionBody: true,
-                isInsideGeneratorFunction: isInsideGeneratorFunction,
-                isInsideAsyncFunction: isInsideAsyncFunction,
-            }).trimStart().substring(2);
+            const properIndentationLevel = this.indentationLevel;
+            const nodeBody = node.body;
+            getBlockContentWithoutOpeningBrace = (isInsideNativeLambda) => {
+                const currentIndentationLevel = this.indentationLevel;
+                this.indentationLevel = properIndentationLevel;
+                const code = this.visit(nodeBody, {
+                    ...visitContext,
+                    isMainContext: false,
+                    isInsideFunction: true,
+                    isFunctionBody: true,
+                    isInsideGeneratorFunction,
+                    isInsideAsyncFunction,
+                    isInsideNativeLambda,
+                })
+                    .trim()
+                    .substring(2);
+                this.indentationLevel = currentIndentationLevel;
+                return code;
+            };
         }
         else {
             this.indentationLevel++;
-            paramsContent = generateParamsBuilder();
-            blockContentWithoutOpeningBrace =
-                `${this.indent()}${returnCommand} ${this.visit(node.body, {
+            paramsContent += generateParamsBuilder();
+            const properIndentationLevel = this.indentationLevel;
+            const nodeBody = node.body;
+            getBlockContentWithoutOpeningBrace = (isInsideNativeLambda) => {
+                const currentIndentationLevel = this.indentationLevel;
+                this.indentationLevel = properIndentationLevel;
+                let code = `${this.indent()}${returnCommand} ${this.visit(nodeBody, {
                     ...visitContext,
                     isMainContext: false,
                     isInsideFunction: true,
                     isFunctionBody: false,
-                    isInsideGeneratorFunction: isInsideGeneratorFunction,
-                    isInsideAsyncFunction: isInsideAsyncFunction,
+                    isInsideGeneratorFunction,
+                    isInsideAsyncFunction,
+                    isInsideNativeLambda,
                 })};\n`;
+                this.indentationLevel--;
+                code += `${this.indent()}}`;
+                this.indentationLevel = currentIndentationLevel;
+                return code;
+            };
             this.indentationLevel--;
-            blockContentWithoutOpeningBrace += `${this.indent()}}`;
         }
     }
     else {
-        blockContentWithoutOpeningBrace =
-            `${returnCommand} jspp::Constants::UNDEFINED; }\n`;
+        getBlockContentWithoutOpeningBrace = () => `${returnCommand} jspp::Constants::UNDEFINED; }`;
     }
     return {
         node,
@@ -189,37 +284,39 @@ export function generateLambdaComponents(node, context, options) {
         thisArgParam,
         funcArgs,
         nativeFuncArgs,
-        funcReturnType,
+        getFuncReturnType,
         preamble,
         nativePreamble,
         paramsContent,
         nativeParamsContent,
-        blockContentWithoutOpeningBrace,
+        getBlockContentWithoutOpeningBrace,
         isInsideGeneratorFunction,
         isInsideAsyncFunction,
     };
 }
 export function generateNativeLambda(comps) {
-    const { options, thisArgParam, nativeFuncArgs, funcReturnType, nativePreamble, nativeParamsContent, blockContentWithoutOpeningBrace, } = comps;
+    const { options, thisArgParam, nativeFuncArgs, getFuncReturnType, nativePreamble, nativeParamsContent, getBlockContentWithoutOpeningBrace, } = comps;
     const capture = options?.capture || "[=]";
     const nativeName = options?.nativeName;
     const selfParam = nativeName ? `this auto&& ${nativeName}, ` : "";
     const mutableLabel = nativeName ? "" : "mutable ";
+    const funcReturnType = getFuncReturnType(true);
     let lambda = `${capture}(${selfParam}${thisArgParam}${nativeFuncArgs}) ${mutableLabel}-> ${funcReturnType} {\n`;
     lambda += nativePreamble;
     lambda += nativeParamsContent;
-    lambda += blockContentWithoutOpeningBrace;
+    lambda += getBlockContentWithoutOpeningBrace(true);
     return lambda;
 }
 export function generateWrappedLambda(comps) {
-    const { node, context, options, thisArgParam, funcArgs, funcReturnType, preamble, paramsContent, blockContentWithoutOpeningBrace, isInsideGeneratorFunction, isInsideAsyncFunction, } = comps;
+    const { node, context, options, thisArgParam, funcArgs, getFuncReturnType, preamble, paramsContent, getBlockContentWithoutOpeningBrace, isInsideGeneratorFunction, isInsideAsyncFunction, } = comps;
     const capture = options?.capture || "[=]";
     const isAssignment = options?.isAssignment || false;
+    const funcReturnType = getFuncReturnType(false);
     const noTypeSignature = options?.noTypeSignature || false;
     let lambda = `${capture}(${thisArgParam}, ${funcArgs}) mutable -> ${funcReturnType} {\n`;
     lambda += preamble;
     lambda += paramsContent;
-    lambda += blockContentWithoutOpeningBrace;
+    lambda += getBlockContentWithoutOpeningBrace(false);
     let callable = lambda;
     let method = "";
     // Handle generator function
@@ -258,7 +355,7 @@ export function generateWrappedLambda(comps) {
             method = `jspp::AnyValue::make_function`;
         }
     }
-    const funcName = context?.lambdaName || node.name?.getText();
+    const funcName = context?.functionName || node.name?.getText();
     const hasName = !!funcName && funcName.length > 0;
     let args = callable;
     const isArrow = ts.isArrowFunction(node);
@@ -283,7 +380,23 @@ export function generateWrappedLambda(comps) {
             args += `, "${funcName}"`;
         }
     }
-    const fullExpression = `${method}(${args})`;
+    let prototypeExpr = "";
+    if (isInsideGeneratorFunction) {
+        if (isInsideAsyncFunction) {
+            prototypeExpr =
+                '::AsyncGeneratorFunction.get_own_property("prototype")';
+        }
+        else {
+            prototypeExpr = '::GeneratorFunction.get_own_property("prototype")';
+        }
+    }
+    else if (isInsideAsyncFunction) {
+        prototypeExpr = '::AsyncFunction.get_own_property("prototype")';
+    }
+    else {
+        prototypeExpr = '::Function.get_own_property("prototype")';
+    }
+    const fullExpression = `${method}(${args}).set_prototype(${prototypeExpr})`;
     if (ts.isFunctionDeclaration(node) && !isAssignment && node.name) {
         const funcName = node.name?.getText();
         return `${this.indent()}auto ${funcName} = ${fullExpression};\n`;
@@ -312,7 +425,7 @@ export function visitFunctionExpression(node, context) {
             `${this.indent()}auto ${funcName} = std::make_shared<jspp::AnyValue>();\n`;
         const lambda = this.generateWrappedLambda(this.generateLambdaComponents(funcExpr, {
             ...context,
-            lambdaName: funcName,
+            functionName: funcName,
         }, {
             isAssignment: true,
             capture: "[=]",

package/dist/{core → interpreter/core}/codegen/helpers.js

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { BUILTIN_OBJECTS, Scope } from "../../analysis/scope.js";
-import { DeclarationType, DeclaredSymbols } from "../../ast/symbols.js";
+import { DeclarationType, DeclaredSymbols, } from "../../ast/symbols.js";
 import { CompilerError } from "../error.js";
 import { CodeGenerator } from "./index.js";
 /**
@@ -161,6 +161,9 @@ export function getJsVarName(node) {
  * @returns The C++ code for accessing the variable's value.
  */
 export function getDerefCode(nodeText, varName, context, typeInfo) {
+    if (typeInfo?.isBuiltin) {
+        return nodeText;
+    }
     // Make sure varName is incased in quotes
     if (!varName.startsWith('"'))
         varName = '"' + varName;
@@ -230,22 +233,24 @@ export function getReturnCommand(context) {
  * @throws CompilerError if a duplicate declaration is found.
  */
 export function hoistDeclaration(decl, hoistedSymbols, scopeNode) {
-    const isLet = ts.isVariableDeclaration(decl) &&
-        (decl.parent.flags & (ts.NodeFlags.Let)) !== 0;
+    const isLet = ts.isParameter(decl) || (ts.isVariableDeclaration(decl) &&
+        (decl.parent.flags & (ts.NodeFlags.Let)) !== 0);
     const isConst = ts.isVariableDeclaration(decl) &&
         (decl.parent.flags & (ts.NodeFlags.Const)) !== 0;
-    const declType = isLet
+    const declType = ts.isParameter(decl)
         ? DeclarationType.let
-        : isConst
-            ? DeclarationType.const
-            : ts.isFunctionDeclaration(decl)
-                ? DeclarationType.function
-                : ts.isClassDeclaration(decl)
-                    ? DeclarationType.class
-                    : ts.isEnumDeclaration(decl)
-                        ? DeclarationType.enum
-                        : DeclarationType.var;
-    const hoistName = (nameNode) => {
+        : isLet
+            ? DeclarationType.let
+            : isConst
+                ? DeclarationType.const
+                : ts.isFunctionDeclaration(decl)
+                    ? DeclarationType.function
+                    : ts.isClassDeclaration(decl)
+                        ? DeclarationType.class
+                        : ts.isEnumDeclaration(decl)
+                            ? DeclarationType.enum
+                            : DeclarationType.var;
+    const hoistName = (nameNode, isFromDestructuring = false) => {
         if (ts.isIdentifier(nameNode)) {
             const name = nameNode.text;
             if (hoistedSymbols.has(name)) {
@@ -264,40 +269,53 @@ export function hoistDeclaration(decl, hoistedSymbols, scopeNode) {
             }
             else {
                 // Add the symbol to the hoisted symbols
+                hoistedSymbols.add(name, {
+                    type: declType,
+                });
+                // Get and update symbol features
                 if (ts.isFunctionDeclaration(decl) ||
                     (ts.isVariableDeclaration(decl) && decl.initializer &&
                         nameNode === decl.name &&
                         (ts.isArrowFunction(decl.initializer) ||
-                            ts.isFunctionExpression(decl.initializer)))) {
+                            (ts.isFunctionExpression(decl.initializer) &&
+                                !decl.initializer.name)))) {
                     const funcExpr = ts.isVariableDeclaration(decl)
                         ? decl.initializer
                         : decl;
-                    const isAsync = this.isAsyncFunction(funcExpr);
-                    const isGenerator = this.isGeneratorFunction(funcExpr);
-                    hoistedSymbols.add(name, {
-                        type: declType,
-                        features: { isAsync, isGenerator },
+                    // Update features
+                    hoistedSymbols.update(name, {
+                        features: {
+                            isAsync: this.isAsyncFunction(funcExpr),
+                            isGenerator: this.isGeneratorFunction(funcExpr),
+                        },
                     });
                     // Don't hoist declarations not used as a variable
                     // They will be called with their native lambda/value
                     if (!this.isDeclarationUsedAsValue(decl, scopeNode) &&
                         !this.isDeclarationUsedBeforeInitialization(name, scopeNode)) {
+                        hoistedSymbols.update(name, {
+                            checks: { skippedHoisting: true },
+                        });
                         return "";
                     }
                 }
-                else {
-                    hoistedSymbols.add(name, { type: declType });
-                }
             }
             const scope = this.getScopeForNode(decl);
             const typeInfo = this.typeAnalyzer.scopeManager.lookupFromScope(name, scope);
             const initializer = isLet || isConst || ts.isClassDeclaration(decl)
                 ? "jspp::Constants::UNINITIALIZED"
                 : "jspp::Constants::UNDEFINED";
-            if (typeInfo.needsHeapAllocation) {
+            if (typeInfo?.needsHeapAllocation) {
                 return `${this.indent()}auto ${name} = std::make_shared<jspp::AnyValue>(${initializer});\n`;
             }
             else {
+                if ((isLet || isConst) &&
+                    !this.isDeclarationUsedBeforeInitialization(name, scopeNode) && !isFromDestructuring) {
+                    hoistedSymbols.update(name, {
+                        checks: { skippedHoisting: true },
+                    });
+                    return "";
+                }
                 return `${this.indent()}jspp::AnyValue ${name} = ${initializer};\n`;
             }
         }
@@ -305,7 +323,7 @@ export function hoistDeclaration(decl, hoistedSymbols, scopeNode) {
             let code = "";
             nameNode.elements.forEach((element) => {
                 if (ts.isBindingElement(element)) {
-                    code += hoistName(element.name);
+                    code += hoistName(element.name, true);
                 }
             });
             return code;
@@ -638,6 +656,104 @@ export function isDeclarationUsedBeforeInitialization(name, root) {
     visit(root);
     return isUsedBefore;
 }
+/**
+ * Checks if a variable name is used within a node subtree without a preceding declaration.
+ * Returns true if:
+ * 1. The variable is used but never declared within the provided root node.
+ * 2. The variable is used lexically before its declaration within the root node.
+ *
+ * @param name The variable name to check.
+ * @param root The root node to search within.
+ * @returns True if used without/before declaration.
+ */
+export function isVariableUsedWithoutDeclaration(name, root) {
+    let declPos = -1;
+    let foundDecl = false;
+    // 1. Find the declaration position within this root
+    const findDecl = (node) => {
+        if (foundDecl)
+            return;
+        if ((ts.isFunctionDeclaration(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isVariableDeclaration(node) ||
+            ts.isEnumDeclaration(node) ||
+            ts.isParameter(node)) &&
+            node.name && ts.isIdentifier(node.name) && node.name.text === name) {
+            declPos = node.getStart();
+            foundDecl = true;
+        }
+        else {
+            ts.forEachChild(node, findDecl);
+        }
+    };
+    findDecl(root);
+    let isUsedIllegally = false;
+    // 2. Traverse for usages
+    const visit = (node) => {
+        if (isUsedIllegally)
+            return;
+        if (ts.isIdentifier(node) && node.text === name) {
+            const parent = node.parent;
+            // Skip if this identifier IS the declaration site
+            const isDeclarationSite = (ts.isFunctionDeclaration(parent) ||
+                ts.isVariableDeclaration(parent) ||
+                ts.isClassDeclaration(parent) ||
+                ts.isMethodDeclaration(parent) ||
+                ts.isEnumDeclaration(parent) ||
+                ts.isEnumMember(parent) ||
+                ts.isParameter(parent) ||
+                ts.isImportSpecifier(parent)) &&
+                parent.name === node;
+            // Skip if it's a property access (e.g., obj.name)
+            const isProperty = (ts.isPropertyAccessExpression(parent) &&
+                parent.name === node) ||
+                (ts.isPropertyAssignment(parent) && parent.name === node);
+            if (!isDeclarationSite && !isProperty) {
+                const usagePos = node.getStart();
+                // Case 1: Used but not declared in this node
+                if (!foundDecl) {
+                    isUsedIllegally = true;
+                    return;
+                }
+                // Case 2: Used lexically before declaration
+                if (usagePos < declPos) {
+                    isUsedIllegally = true;
+                    return;
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(root);
+    return isUsedIllegally;
+}
+/**
+ * Checks if a node (usually a SourceFile) contains any top-level await expressions.
+ * This determines if the module function should be a coroutine.
+ */
+export function needsTopLevelAwait(node) {
+    let found = false;
+    const visitor = (n) => {
+        if (found)
+            return;
+        if (ts.isAwaitExpression(n)) {
+            found = true;
+            return;
+        }
+        if (ts.isForOfStatement(n) && n.awaitModifier) {
+            found = true;
+            return;
+        }
+        // Nested functions/classes have their own context
+        if (ts.isFunctionLike(n) || ts.isClassLike(n) ||
+            ts.isModuleDeclaration(n)) {
+            return;
+        }
+        ts.forEachChild(n, visitor);
+    };
+    ts.forEachChild(node, visitor);
+    return found;
+}
 /**
  * Validates and filters function parameters, checking for illegal "this"
  * and correctly positioned rest parameters.
@@ -667,3 +783,32 @@ export function validateFunctionParams(parameters) {
         return p;
     }) || [];
 }
+/**
+ * Traverses the AST upwards from the given node to find the nearest enclosing
+ * `FunctionDeclaration` node that contains a `ReturnStatement` ancestor.
+ *
+ * This function is useful for determining the function context in which a return
+ * statement appears. It starts from the provided node and walks up the parent
+ * chain, tracking whether a return statement has been encountered. Once a
+ * function declaration is found after encountering a return statement, it is returned.
+ *
+ * @param node - The starting TypeScript AST node.
+ * @returns The enclosing `ts.FunctionDeclaration` node if found, otherwise `undefined`.
+ */
+export function findEnclosingFunctionDeclarationFromReturnStatement(node) {
+    let current = node;
+    let foundReturn = false;
+    while (current) {
+        if (ts.isFunctionDeclaration(current)) {
+            if (foundReturn) {
+                return current;
+            }
+            break;
+        }
+        if (ts.isReturnStatement(current)) {
+            foundReturn = true;
+        }
+        current = current.parent;
+    }
+    return undefined;
+}