"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    var desc = Object.getOwnPropertyDescriptor(m, k);
    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
      desc = { enumerable: true, get: function() { return m[k]; } };
    }
    Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
    Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
    o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
    var ownKeys = function(o) {
        ownKeys = Object.getOwnPropertyNames || function (o) {
            var ar = [];
            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
            return ar;
        };
        return ownKeys(o);
    };
    return function (mod) {
        if (mod && mod.__esModule) return mod;
        var result = {};
        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
        __setModuleDefault(result, mod);
        return result;
    };
})();
Object.defineProperty(exports, "__esModule", { value: true });
const utils_1 = require("@typescript-eslint/utils");
const ts = __importStar(require("typescript"));
const util_1 = require("../util");
exports.default = (0, util_1.createRule)({
    name: 'return-await',
    meta: {
        type: 'problem',
        docs: {
            description: 'Enforce consistent awaiting of returned promises',
            recommended: {
                strict: ['error-handling-correctness-only'],
            },
            requiresTypeChecking: true,
        },
        fixable: 'code',
        // eslint-disable-next-line eslint-plugin/require-meta-has-suggestions -- suggestions are exposed through a helper.
        hasSuggestions: true,
        messages: {
            disallowedPromiseAwait: 'Returning an awaited promise is not allowed in this context.',
            disallowedPromiseAwaitSuggestion: 'Remove `await` before the expression. Use caution as this may impact control flow.',
            nonPromiseAwait: 'Returning an awaited value that is not a promise is not allowed.',
            requiredPromiseAwait: 'Returning an awaited promise is required in this context.',
            requiredPromiseAwaitSuggestion: 'Add `await` before the expression. Use caution as this may impact control flow.',
        },
        schema: [
            {
                type: 'string',
                oneOf: [
                    {
                        type: 'string',
                        description: 'Requires that all returned promises be awaited.',
                        enum: ['always'],
                    },
                    {
                        type: 'string',
                        description: 'In error-handling contexts, the rule enforces that returned promises must be awaited. In ordinary contexts, the rule does not enforce any particular behavior around whether returned promises are awaited.',
                        enum: ['error-handling-correctness-only'],
                    },
                    {
                        type: 'string',
                        description: 'In error-handling contexts, the rule enforces that returned promises must be awaited. In ordinary contexts, the rule enforces that returned promises _must not_ be awaited.',
                        enum: ['in-try-catch'],
                    },
                    {
                        type: 'string',
                        description: 'Disallows awaiting any returned promises.',
                        enum: ['never'],
                    },
                ],
            },
        ],
    },
    defaultOptions: ['in-try-catch'],
    create(context, [option]) {
        const services = (0, util_1.getParserServices)(context);
        const checker = services.program.getTypeChecker();
        const scopeInfoStack = [];
        function enterFunction(node) {
            scopeInfoStack.push({
                hasAsync: node.async,
                owningFunc: node,
            });
        }
        function exitFunction() {
            scopeInfoStack.pop();
        }
        function affectsExplicitResourceManagement(node) {
            // just need to determine if there is a `using` declaration in scope.
            let scope = context.sourceCode.getScope(node);
            const functionScope = scope.variableScope;
            while (true) {
                for (const variable of scope.variables) {
                    if (variable.defs.length !== 1) {
                        // This can't be the case for `using` or `await using` since it's
                        // an error to redeclare those more than once in the same scope,
                        // unlike, say, `var` declarations.
                        continue;
                    }
                    const declaration = variable.defs[0];
                    const declaratorNode = declaration.node;
                    const declarationNode = declaratorNode.parent;
                    // if it's a using/await using declaration, and it comes _before_ the
                    // node we're checking, it affects control flow for that node.
                    if (['await using', 'using'].includes(declarationNode.kind) &&
                        declaratorNode.range[1] < node.range[0]) {
                        return true;
                    }
                }
                if (scope === functionScope) {
                    // We've checked all the relevant scopes
                    break;
                }
                // This should always exist, since the rule should only be checking
                // contexts in which `return` statements are legal, which should always
                // be inside a function.
                scope = (0, util_1.nullThrows)(scope.upper, 'Expected parent scope to exist. return-await should only operate on return statements within functions');
            }
            return false;
        }
        /**
         * Tests whether a node is inside of an explicit error handling context
         * (try/catch/finally) in a way that throwing an exception will have an
         * impact on the program's control flow.
         */
        function affectsExplicitErrorHandling(node) {
            // If an error-handling block is followed by another error-handling block,
            // control flow is affected by whether promises in it are awaited or not.
            // Otherwise, we need to check recursively for nested try statements until
            // we get to the top level of a function or the program. If by then,
            // there's no offending error-handling blocks, it doesn't affect control
            // flow.
            const tryAncestorResult = findContainingTryStatement(node);
            if (tryAncestorResult == null) {
                return false;
            }
            const { block, tryStatement } = tryAncestorResult;
            switch (block) {
                case 'catch':
                    // Exceptions thrown in catch blocks followed by a finally block affect
                    // control flow.
                    if (tryStatement.finallyBlock != null) {
                        return true;
                    }
                    // Otherwise recurse.
                    return affectsExplicitErrorHandling(tryStatement);
                case 'finally':
                    return affectsExplicitErrorHandling(tryStatement);
                case 'try':
                    // Try blocks are always followed by either a catch or finally,
                    // so exceptions thrown here always affect control flow.
                    return true;
                default: {
                    const __never = block;
                    throw new Error(`Unexpected block type: ${String(__never)}`);
                }
            }
        }
        /**
         * A try _statement_ is the whole thing that encompasses try block,
         * catch clause, and finally block. This function finds the nearest
         * enclosing try statement (if present) for a given node, and reports which
         * part of the try statement the node is in.
         */
        function findContainingTryStatement(node) {
            let child = node;
            let ancestor = node.parent;
            while (ancestor && !ts.isFunctionLike(ancestor)) {
                if (ts.isTryStatement(ancestor)) {
                    let block;
                    if (child === ancestor.tryBlock) {
                        block = 'try';
                    }
                    else if (child === ancestor.catchClause) {
                        block = 'catch';
                    }
                    else if (child === ancestor.finallyBlock) {
                        block = 'finally';
                    }
                    return {
                        block: (0, util_1.nullThrows)(block, 'Child of a try statement must be a try block, catch clause, or finally block'),
                        tryStatement: ancestor,
                    };
                }
                child = ancestor;
                ancestor = ancestor.parent;
            }
            return undefined;
        }
        function removeAwait(fixer, node) {
            // Should always be an await node; but let's be safe.
            /* istanbul ignore if */ if (!(0, util_1.isAwaitExpression)(node)) {
                return null;
            }
            const awaitToken = context.sourceCode.getFirstToken(node, util_1.isAwaitKeyword);
            // Should always be the case; but let's be safe.
            /* istanbul ignore if */ if (!awaitToken) {
                return null;
            }
            const startAt = awaitToken.range[0];
            let endAt = awaitToken.range[1];
            // Also remove any extraneous whitespace after `await`, if there is any.
            const nextToken = context.sourceCode.getTokenAfter(awaitToken, {
                includeComments: true,
            });
            if (nextToken) {
                endAt = nextToken.range[0];
            }
            return fixer.removeRange([startAt, endAt]);
        }
        function insertAwait(fixer, node, isHighPrecedence) {
            if (isHighPrecedence) {
                return fixer.insertTextBefore(node, 'await ');
            }
            return [
                fixer.insertTextBefore(node, 'await ('),
                fixer.insertTextAfter(node, ')'),
            ];
        }
        function test(node, expression) {
            let child;
            const isAwait = ts.isAwaitExpression(expression);
            if (isAwait) {
                child = expression.getChildAt(1);
            }
            else {
                child = expression;
            }
            const type = checker.getTypeAtLocation(child);
            const certainty = (0, util_1.needsToBeAwaited)(checker, expression, type);
            // handle awaited _non_thenables
            if (certainty !== util_1.Awaitable.Always) {
                if (isAwait) {
                    if (certainty === util_1.Awaitable.May) {
                        return;
                    }
                    context.report({
                        node,
                        messageId: 'nonPromiseAwait',
                        fix: fixer => removeAwait(fixer, node),
                    });
                }
                return;
            }
            // At this point it's definitely a thenable.
            const affectsErrorHandling = affectsExplicitErrorHandling(expression) ||
                affectsExplicitResourceManagement(node);
            const useAutoFix = !affectsErrorHandling;
            const ruleConfiguration = getConfiguration(option);
            const shouldAwaitInCurrentContext = affectsErrorHandling
                ? ruleConfiguration.errorHandlingContext
                : ruleConfiguration.ordinaryContext;
            switch (shouldAwaitInCurrentContext) {
                case 'await':
                    if (!isAwait) {
                        context.report({
                            node,
                            messageId: 'requiredPromiseAwait',
                            ...(0, util_1.getFixOrSuggest)({
                                fixOrSuggest: useAutoFix ? 'fix' : 'suggest',
                                suggestion: {
                                    messageId: 'requiredPromiseAwaitSuggestion',
                                    fix: fixer => insertAwait(fixer, node, (0, util_1.isHigherPrecedenceThanAwait)(expression)),
                                },
                            }),
                        });
                    }
                    break;
                case "don't-care":
                    break;
                case 'no-await':
                    if (isAwait) {
                        context.report({
                            node,
                            messageId: 'disallowedPromiseAwait',
                            ...(0, util_1.getFixOrSuggest)({
                                fixOrSuggest: useAutoFix ? 'fix' : 'suggest',
                                suggestion: {
                                    messageId: 'disallowedPromiseAwaitSuggestion',
                                    fix: fixer => removeAwait(fixer, node),
                                },
                            }),
                        });
                    }
                    break;
            }
        }
        function findPossiblyReturnedNodes(node) {
            if (node.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
                return [
                    ...findPossiblyReturnedNodes(node.alternate),
                    ...findPossiblyReturnedNodes(node.consequent),
                ];
            }
            return [node];
        }
        return {
            ArrowFunctionExpression: enterFunction,
            'ArrowFunctionExpression:exit': exitFunction,
            FunctionDeclaration: enterFunction,
            'FunctionDeclaration:exit': exitFunction,
            FunctionExpression: enterFunction,
            'FunctionExpression:exit': exitFunction,
            // executes after less specific handler, so exitFunction is called
            'ArrowFunctionExpression[async = true]:exit'(node) {
                if (node.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
                    findPossiblyReturnedNodes(node.body).forEach(node => {
                        const tsNode = services.esTreeNodeToTSNodeMap.get(node);
                        test(node, tsNode);
                    });
                }
            },
            ReturnStatement(node) {
                const scopeInfo = scopeInfoStack.at(-1);
                if (!scopeInfo?.hasAsync || !node.argument) {
                    return;
                }
                findPossiblyReturnedNodes(node.argument).forEach(node => {
                    const tsNode = services.esTreeNodeToTSNodeMap.get(node);
                    test(node, tsNode);
                });
            },
        };
    },
});
function getConfiguration(option) {
    switch (option) {
        case 'always':
            return {
                errorHandlingContext: 'await',
                ordinaryContext: 'await',
            };
        case 'error-handling-correctness-only':
            return {
                errorHandlingContext: 'await',
                ordinaryContext: "don't-care",
            };
        case 'in-try-catch':
            return {
                errorHandlingContext: 'await',
                ordinaryContext: 'no-await',
            };
        case 'never':
            return {
                errorHandlingContext: 'no-await',
                ordinaryContext: 'no-await',
            };
    }
}