index.ts

import {
	AST_NODE_TYPES,
	ASTUtils,
	TSESLint,
	TSESLintScope,
	TSESTree,
} from '@typescript-eslint/utils';

import {
	isArrayExpression,
	isArrowFunctionExpression,
	isAssignmentExpression,
	isBlockStatement,
	isCallExpression,
	isExpressionStatement,
	isImportDeclaration,
	isImportNamespaceSpecifier,
	isImportSpecifier,
	isLiteral,
	isMemberExpression,
	isObjectPattern,
	isProperty,
	isReturnStatement,
	isVariableDeclaration,
} from './is-node-of-type';

export * from './is-node-of-type';

const ValidLeftHandSideExpressions = [
	AST_NODE_TYPES.CallExpression,
	AST_NODE_TYPES.ClassExpression,
	AST_NODE_TYPES.ClassDeclaration,
	AST_NODE_TYPES.FunctionExpression,
	AST_NODE_TYPES.Literal,
	AST_NODE_TYPES.TemplateLiteral,
	AST_NODE_TYPES.MemberExpression,
	AST_NODE_TYPES.ArrayExpression,
	AST_NODE_TYPES.ArrayPattern,
	AST_NODE_TYPES.ClassExpression,
	AST_NODE_TYPES.FunctionExpression,
	AST_NODE_TYPES.Identifier,
	AST_NODE_TYPES.JSXElement,
	AST_NODE_TYPES.JSXFragment,
	AST_NODE_TYPES.JSXOpeningElement,
	AST_NODE_TYPES.MetaProperty,
	AST_NODE_TYPES.ObjectExpression,
	AST_NODE_TYPES.ObjectPattern,
	AST_NODE_TYPES.Super,
	AST_NODE_TYPES.ThisExpression,
	AST_NODE_TYPES.TSNullKeyword,
	AST_NODE_TYPES.TaggedTemplateExpression,
	AST_NODE_TYPES.TSNonNullExpression,
	AST_NODE_TYPES.TSAsExpression,
	AST_NODE_TYPES.ArrowFunctionExpression,
];

/**
 * Finds the closest CallExpression node for a given node.
 * @param node
 * @param shouldRestrictInnerScope - If true, CallExpression must belong to innermost scope of given node
 */
export function findClosestCallExpressionNode(
	node: TSESTree.Node | null | undefined,
	shouldRestrictInnerScope = false
): TSESTree.CallExpression | null {
	if (isCallExpression(node)) {
		return node;
	}

	if (!node || !node.parent) {
		return null;
	}

	if (
		shouldRestrictInnerScope &&
		!ValidLeftHandSideExpressions.includes(node.parent.type)
	) {
		return null;
	}

	return findClosestCallExpressionNode(node.parent, shouldRestrictInnerScope);
}

export function findClosestVariableDeclaratorNode(
	node: TSESTree.Node | undefined
): TSESTree.VariableDeclarator | null {
	if (!node) {
		return null;
	}

	if (ASTUtils.isVariableDeclarator(node)) {
		return node;
	}

	return findClosestVariableDeclaratorNode(node.parent);
}

/**
 * TODO: remove this one in favor of {@link findClosestCallExpressionNode}
 */
export function findClosestCallNode(
	node: TSESTree.Node,
	name: string
): TSESTree.CallExpression | null {
	if (!node.parent) {
		return null;
	}

	if (
		isCallExpression(node) &&
		ASTUtils.isIdentifier(node.callee) &&
		node.callee.name === name
	) {
		return node;
	} else {
		return findClosestCallNode(node.parent, name);
	}
}

export function hasThenProperty(node: TSESTree.Node): boolean {
	return (
		isMemberExpression(node) &&
		ASTUtils.isIdentifier(node.property) &&
		node.property.name === 'then'
	);
}

export function hasChainedThen(node: TSESTree.Node): boolean {
	const parent = node.parent;

	// wait(...).then(...)
	if (isCallExpression(parent) && parent.parent) {
		return hasThenProperty(parent.parent);
	}

	// promise.then(...)
	return !!parent && hasThenProperty(parent);
}

export function isPromiseIdentifier(
	node: TSESTree.Node
): node is TSESTree.Identifier & { name: 'Promise' } {
	return ASTUtils.isIdentifier(node) && node.name === 'Promise';
}

export function isPromiseAll(node: TSESTree.CallExpression): boolean {
	return (
		isMemberExpression(node.callee) &&
		isPromiseIdentifier(node.callee.object) &&
		ASTUtils.isIdentifier(node.callee.property) &&
		node.callee.property.name === 'all'
	);
}

export function isPromiseAllSettled(node: TSESTree.CallExpression): boolean {
	return (
		isMemberExpression(node.callee) &&
		isPromiseIdentifier(node.callee.object) &&
		ASTUtils.isIdentifier(node.callee.property) &&
		node.callee.property.name === 'allSettled'
	);
}

/**
 * Determines whether a given node belongs to handled Promise.all or Promise.allSettled
 * array expression.
 */
export function isPromisesArrayResolved(node: TSESTree.Node): boolean {
	const closestCallExpression = findClosestCallExpressionNode(node, true);

	if (!closestCallExpression) {
		return false;
	}

	return (
		!!closestCallExpression.parent &&
		isArrayExpression(closestCallExpression.parent) &&
		isCallExpression(closestCallExpression.parent.parent) &&
		(isPromiseAll(closestCallExpression.parent.parent) ||
			isPromiseAllSettled(closestCallExpression.parent.parent))
	);
}

/**
 * Determines whether an Identifier related to a promise is considered as handled.
 *
 * It will be considered as handled if:
 * - it belongs to the `await` expression
 * - it belongs to the `Promise.all` method
 * - it belongs to the `Promise.allSettled` method
 * - it's chained with the `then` method
 * - it's returned from a function
 * - has `resolves` or `rejects` jest methods
 */
export function isPromiseHandled(nodeIdentifier: TSESTree.Identifier): boolean {
	const closestCallExpressionNode = findClosestCallExpressionNode(
		nodeIdentifier,
		true
	);

	const suspiciousNodes = [nodeIdentifier, closestCallExpressionNode].filter(
		Boolean
	);

	for (const node of suspiciousNodes) {
		if (!node || !node.parent) {
			continue;
		}
		if (ASTUtils.isAwaitExpression(node.parent)) {
			return true;
		}

		if (
			isArrowFunctionExpression(node.parent) ||
			isReturnStatement(node.parent)
		) {
			return true;
		}

		if (hasClosestExpectResolvesRejects(node.parent)) {
			return true;
		}

		if (hasChainedThen(node)) {
			return true;
		}

		if (isPromisesArrayResolved(node)) {
			return true;
		}
	}

	return false;
}

export function getVariableReferences(
	context: TSESLint.RuleContext<string, unknown[]>,
	node: TSESTree.Node
): TSESLint.Scope.Reference[] {
	if (ASTUtils.isVariableDeclarator(node)) {
		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
		return context.getDeclaredVariables(node)[0]?.references?.slice(1) ?? [];
	}

	return [];
}

interface InnermostFunctionScope extends TSESLintScope.FunctionScope {
	block:
		| TSESTree.ArrowFunctionExpression
		| TSESTree.FunctionDeclaration
		| TSESTree.FunctionExpression;
}

export function getInnermostFunctionScope(
	context: TSESLint.RuleContext<string, unknown[]>,
	asyncQueryNode: TSESTree.Identifier
): InnermostFunctionScope | null {
	const innermostScope = ASTUtils.getInnermostScope(
		context.getScope(),
		asyncQueryNode
	);

	if (
		innermostScope.type === 'function' &&
		ASTUtils.isFunction(innermostScope.block)
	) {
		return innermostScope as unknown as InnermostFunctionScope;
	}

	return null;
}

export function getFunctionReturnStatementNode(
	functionNode:
		| TSESTree.ArrowFunctionExpression
		| TSESTree.FunctionDeclaration
		| TSESTree.FunctionExpression
): TSESTree.Node | null {
	if (isBlockStatement(functionNode.body)) {
		// regular function or arrow function with block
		const returnStatementNode = functionNode.body.body.find((statement) =>
			isReturnStatement(statement)
		) as TSESTree.ReturnStatement | undefined;

		if (!returnStatementNode) {
			return null;
		}
		return returnStatementNode.argument;
	} else if (functionNode.expression) {
		// arrow function with implicit return
		return functionNode.body;
	}

	return null;
}

/**
 * Gets the property identifier node of a given property node.
 *
 * Not to be confused with {@link getDeepestIdentifierNode}
 *
 * An example:
 * Having `const a = rtl.within('foo').getByRole('button')`:
 *  if we call `getPropertyIdentifierNode` with `rtl` property node,
 *  it will return `rtl` identifier node
 */
export function getPropertyIdentifierNode(
	node: TSESTree.Node
): TSESTree.Identifier | null {
	if (ASTUtils.isIdentifier(node)) {
		return node;
	}

	if (isMemberExpression(node)) {
		return getPropertyIdentifierNode(node.object);
	}

	if (isCallExpression(node)) {
		return getPropertyIdentifierNode(node.callee);
	}

	if (isExpressionStatement(node)) {
		return getPropertyIdentifierNode(node.expression);
	}

	return null;
}

/**
 * Gets the deepest identifier node in the expression from a given node.
 *
 * Opposite of {@link getReferenceNode}
 *
 * An example:
 * Having `const a = rtl.within('foo').getByRole('button')`:
 *  if we call `getDeepestIdentifierNode` with `rtl` node,
 *  it will return `getByRole` identifier
 */
export function getDeepestIdentifierNode(
	node: TSESTree.Node
): TSESTree.Identifier | null {
	if (ASTUtils.isIdentifier(node)) {
		return node;
	}

	if (isMemberExpression(node) && ASTUtils.isIdentifier(node.property)) {
		return node.property;
	}

	if (isCallExpression(node)) {
		return getDeepestIdentifierNode(node.callee);
	}

	if (ASTUtils.isAwaitExpression(node)) {
		return getDeepestIdentifierNode(node.argument);
	}

	return null;
}

/**
 * Gets the farthest node in the expression from a given node.
 *
 * Opposite of {@link getDeepestIdentifierNode}

 * An example:
 * Having `const a = rtl.within('foo').getByRole('button')`:
 *  if we call `getReferenceNode` with `getByRole` identifier,
 *  it will return `rtl` node
 */
export function getReferenceNode(
	node:
		| TSESTree.CallExpression
		| TSESTree.Identifier
		| TSESTree.MemberExpression
): TSESTree.CallExpression | TSESTree.Identifier | TSESTree.MemberExpression {
	if (
		node.parent &&
		(isMemberExpression(node.parent) || isCallExpression(node.parent))
	) {
		return getReferenceNode(node.parent);
	}

	return node;
}

export function getFunctionName(
	node:
		| TSESTree.ArrowFunctionExpression
		| TSESTree.FunctionDeclaration
		| TSESTree.FunctionExpression
): string {
	return (
		ASTUtils.getFunctionNameWithKind(node)
			.match(/('\w+')/g)?.[0]
			.replace(/'/g, '') ?? ''
	);
}

// TODO: extract into types file?
export type ImportModuleNode =
	| TSESTree.CallExpression
	| TSESTree.ImportDeclaration;

export function getImportModuleName(
	node: ImportModuleNode | null | undefined
): string | undefined {
	// import node of shape: import { foo } from 'bar'
	if (isImportDeclaration(node) && typeof node.source.value === 'string') {
		return node.source.value;
	}

	// import node of shape: const { foo } = require('bar')
	if (
		isCallExpression(node) &&
		isLiteral(node.arguments[0]) &&
		typeof node.arguments[0].value === 'string'
	) {
		return node.arguments[0].value;
	}

	return undefined;
}

type AssertNodeInfo = {
	matcher: string | null;
	isNegated: boolean;
};
/**
 * Extracts matcher info from MemberExpression node representing an assert.
 */
export function getAssertNodeInfo(
	node: TSESTree.MemberExpression
): AssertNodeInfo {
	const emptyInfo = { matcher: null, isNegated: false } as AssertNodeInfo;

	if (
		!isCallExpression(node.object) ||
		!ASTUtils.isIdentifier(node.object.callee)
	) {
		return emptyInfo;
	}

	if (node.object.callee.name !== 'expect') {
		return emptyInfo;
	}

	let matcher = ASTUtils.getPropertyName(node);
	const isNegated = matcher === 'not';
	if (isNegated) {
		matcher =
			node.parent && isMemberExpression(node.parent)
				? ASTUtils.getPropertyName(node.parent)
				: null;
	}

	if (!matcher) {
		return emptyInfo;
	}

	return { matcher, isNegated };
}

/**
 * Determines whether a node belongs to an async assertion
 * fulfilled by `resolves` or `rejects` properties.
 *
 */
export function hasClosestExpectResolvesRejects(node: TSESTree.Node): boolean {
	if (
		isCallExpression(node) &&
		ASTUtils.isIdentifier(node.callee) &&
		node.parent &&
		isMemberExpression(node.parent) &&
		node.callee.name === 'expect'
	) {
		const expectMatcher = node.parent.property;
		return (
			ASTUtils.isIdentifier(expectMatcher) &&
			(expectMatcher.name === 'resolves' || expectMatcher.name === 'rejects')
		);
	}

	if (!node.parent) {
		return false;
	}

	return hasClosestExpectResolvesRejects(node.parent);
}

/**
 * Gets the Function node which returns the given Identifier.
 */
export function getInnermostReturningFunction(
	context: TSESLint.RuleContext<string, unknown[]>,
	node: TSESTree.Identifier
):
	| TSESTree.ArrowFunctionExpression
	| TSESTree.FunctionDeclaration
	| TSESTree.FunctionExpression
	| undefined {
	const functionScope = getInnermostFunctionScope(context, node);

	if (!functionScope) {
		return undefined;
	}

	const returnStatementNode = getFunctionReturnStatementNode(
		functionScope.block
	);

	if (!returnStatementNode) {
		return undefined;
	}

	const returnStatementIdentifier =
		getDeepestIdentifierNode(returnStatementNode);

	if (returnStatementIdentifier?.name !== node.name) {
		return undefined;
	}

	return functionScope.block;
}

export function hasImportMatch(
	importNode: TSESTree.Identifier | TSESTree.ImportClause,
	identifierName: string
): boolean {
	if (ASTUtils.isIdentifier(importNode)) {
		return importNode.name === identifierName;
	}

	return importNode.local.name === identifierName;
}

export function getStatementCallExpression(
	statement: TSESTree.Statement
): TSESTree.CallExpression | undefined {
	if (isExpressionStatement(statement)) {
		const { expression } = statement;
		if (isCallExpression(expression)) {
			return expression;
		}

		if (
			ASTUtils.isAwaitExpression(expression) &&
			isCallExpression(expression.argument)
		) {
			return expression.argument;
		}

		if (isAssignmentExpression(expression)) {
			if (isCallExpression(expression.right)) {
				return expression.right;
			}

			if (
				ASTUtils.isAwaitExpression(expression.right) &&
				isCallExpression(expression.right.argument)
			) {
				return expression.right.argument;
			}
		}
	}

	if (isReturnStatement(statement) && isCallExpression(statement.argument)) {
		return statement.argument;
	}

	if (isVariableDeclaration(statement)) {
		for (const declaration of statement.declarations) {
			if (isCallExpression(declaration.init)) {
				return declaration.init;
			}
		}
	}
	return undefined;
}

/**
 * Determines whether a given function node is considered as empty function or not.
 *
 * A function is considered empty if its body is empty.
 *
 * Note that comments don't affect the check.
 *
 * If node given is not a function, `false` will be returned.
 */
export function isEmptyFunction(node: TSESTree.Node): boolean | undefined {
	if (ASTUtils.isFunction(node) && isBlockStatement(node.body)) {
		return node.body.body.length === 0;
	}

	return false;
}

/**
 * Finds the import specifier matching a given name for a given import module node.
 */
export function findImportSpecifier(
	specifierName: string,
	node: ImportModuleNode
): TSESTree.Identifier | TSESTree.ImportClause | undefined {
	if (isImportDeclaration(node)) {
		const namedExport = node.specifiers.find((n) => {
			return (
				isImportSpecifier(n) &&
				[n.imported.name, n.local.name].includes(specifierName)
			);
		});

		// it is "import { foo [as alias] } from 'baz'"
		if (namedExport) {
			return namedExport;
		}

		// it could be "import * as rtl from 'baz'"
		return node.specifiers.find((n) => isImportNamespaceSpecifier(n));
	} else {
		if (!ASTUtils.isVariableDeclarator(node.parent)) {
			return undefined;
		}
		const requireNode = node.parent;

		if (ASTUtils.isIdentifier(requireNode.id)) {
			// this is const rtl = require('foo')
			return requireNode.id;
		}

		// this should be const { something } = require('foo')
		if (!isObjectPattern(requireNode.id)) {
			return undefined;
		}

		const property = requireNode.id.properties.find(
			(n) =>
				isProperty(n) &&
				ASTUtils.isIdentifier(n.key) &&
				n.key.name === specifierName
		);
		if (!property) {
			return undefined;
		}
		return (property as TSESTree.Property).key as TSESTree.Identifier;
	}
}