@alexlit/lint-kit 166.1.0 → 167.0.0

package/packages/config-eslint/node_modules/eslint/lib/rules/preserve-caught-error.js

@@ -1,535 +0,0 @@
-/**
- * @fileoverview Rule to preserve caught errors when re-throwing exceptions
- * @author Amnish Singh Arora
- */
-"use strict";
-
-//------------------------------------------------------------------------------
-// Requirements
-//------------------------------------------------------------------------------
-
-const astUtils = require("./utils/ast-utils");
-
-//------------------------------------------------------------------------------
-// Types
-//------------------------------------------------------------------------------
-
-/** @typedef {import("estree").Node} ASTNode */
-
-//------------------------------------------------------------------------------
-// Helpers
-//------------------------------------------------------------------------------
-
-/*
- * This is an indicator of an error cause node, that is too complicated to be detected and fixed.
- * Eg, when error options is an `Identifier` or a `SpreadElement`.
- */
-const UNKNOWN_CAUSE = Symbol("unknown_cause");
-
-const BUILT_IN_ERROR_TYPES = new Set([
-	"Error",
-	"EvalError",
-	"RangeError",
-	"ReferenceError",
-	"SyntaxError",
-	"TypeError",
-	"URIError",
-	"AggregateError",
-]);
-
-/**
- * Finds and returns information about the `cause` property of an error being thrown.
- * @param {ASTNode} throwStatement `ThrowStatement` to be checked.
- * @returns {{ value: ASTNode; multipleDefinitions: boolean; } | UNKNOWN_CAUSE | null}
- * Information about the `cause` of the error being thrown, such as the value node and
- * whether there are multiple definitions of `cause`. `null` if there is no `cause`.
- */
-function getErrorCause(throwStatement) {
-	const throwExpression = throwStatement.argument;
-	/*
-	 * Determine which argument index holds the options object
-	 * `AggregateError` is a special case as it accepts the `options` object as third argument.
-	 */
-	const optionsIndex =
-		throwExpression.callee.name === "AggregateError" ? 2 : 1;
-
-	/*
-	 * Make sure there is no `SpreadElement` at or before the `optionsIndex`
-	 * as this messes up the effective order of arguments and makes it complicated
-	 * to track where the actual error options need to be at
-	 */
-	const spreadExpressionIndex = throwExpression.arguments.findIndex(
-		arg => arg.type === "SpreadElement",
-	);
-	if (spreadExpressionIndex >= 0 && spreadExpressionIndex <= optionsIndex) {
-		return UNKNOWN_CAUSE;
-	}
-
-	const errorOptions = throwExpression.arguments[optionsIndex];
-
-	if (errorOptions) {
-		if (errorOptions.type === "ObjectExpression") {
-			if (
-				errorOptions.properties.some(
-					prop => prop.type === "SpreadElement",
-				)
-			) {
-				/*
-				 * If there is a spread element as part of error options, it is too complicated
-				 * to verify if the cause is used properly and auto-fix.
-				 */
-				return UNKNOWN_CAUSE;
-			}
-
-			const causeProperties = errorOptions.properties.filter(
-				prop => astUtils.getStaticPropertyName(prop) === "cause",
-			);
-
-			const causeProperty = causeProperties.at(-1);
-			return causeProperty
-				? {
-						value: causeProperty.value,
-						multipleDefinitions: causeProperties.length > 1,
-					}
-				: null;
-		}
-
-		// Error options exist, but too complicated to be analyzed/fixed
-		return UNKNOWN_CAUSE;
-	}
-
-	return null;
-}
-
-/**
- * Finds and returns the `CatchClause` node, that the `node` is part of.
- * @param {ASTNode} node The AST node to be evaluated.
- * @returns {ASTNode | null } The closest parent `CatchClause` node, `null` if the `node` is not in a catch block.
- */
-function findParentCatch(node) {
-	let currentNode = node;
-
-	while (currentNode && currentNode.type !== "CatchClause") {
-		if (
-			[
-				"FunctionDeclaration",
-				"FunctionExpression",
-				"ArrowFunctionExpression",
-				"StaticBlock",
-			].includes(currentNode.type)
-		) {
-			/*
-			 * Make sure the ThrowStatement is not made inside a function definition or a static block inside a high level catch.
-			 * In such cases, the caught error is not directly related to the Throw.
-			 *
-			 * For example,
-			 * try {
-			 * } catch (error) {
-			 * 	foo = {
-			 * 		bar() {
-			 *	 	throw new Error();
-			 * 	  }
-			 * };
-			 * }
-			 */
-			return null;
-		}
-		currentNode = currentNode.parent;
-	}
-
-	return currentNode;
-}
-
-//------------------------------------------------------------------------------
-// Rule Definition
-//------------------------------------------------------------------------------
-
-/** @type {import('../types').Rule.RuleModule} */
-module.exports = {
-	meta: {
-		type: "suggestion",
-
-		defaultOptions: [
-			{
-				requireCatchParameter: false,
-			},
-		],
-
-		docs: {
-			description:
-				"Disallow losing originally caught error when re-throwing custom errors",
-			recommended: false,
-			url: "https://eslint.org/docs/latest/rules/preserve-caught-error", // URL to the documentation page for this rule
-		},
-		/*
-		 * TODO: We should allow passing `customErrorTypes` option once something like `typescript-eslint`'s
-		 * 		`TypeOrValueSpecifier` is implemented in core Eslint.
-		 *      See:
-		 * 		1. https://typescript-eslint.io/packages/type-utils/type-or-value-specifier/
-		 *      2. https://github.com/eslint/eslint/pull/19913#discussion_r2192608593
-		 *      3. https://github.com/eslint/eslint/discussions/16540
-		 */
-		schema: [
-			{
-				type: "object",
-				properties: {
-					requireCatchParameter: {
-						type: "boolean",
-						description:
-							"Requires the catch blocks to always have the caught error parameter so it is not discarded.",
-					},
-				},
-				additionalProperties: false,
-			},
-		],
-		messages: {
-			missingCause:
-				"There is no `cause` attached to the symptom error being thrown.",
-			incorrectCause:
-				"The symptom error is being thrown with an incorrect `cause`.",
-			includeCause:
-				"Include the original caught error as the `cause` of the symptom error.",
-			missingCatchErrorParam:
-				"The caught error is not accessible because the catch clause lacks the error parameter. Start referencing the caught error using the catch parameter.",
-			partiallyLostError:
-				"Re-throws cannot preserve the caught error as a part of it is being lost due to destructuring.",
-			caughtErrorShadowed:
-				"The caught error is being attached as `cause`, but is shadowed by a closer scoped redeclaration.",
-		},
-		hasSuggestions: true,
-	},
-
-	create(context) {
-		const sourceCode = context.sourceCode;
-		const [{ requireCatchParameter }] = context.options;
-
-		//----------------------------------------------------------------------
-		// Helpers
-		//----------------------------------------------------------------------
-
-		/**
-		 * Checks if a `ThrowStatement` is constructing and throwing a new `Error` object.
-		 *
-		 * Covers all the error types on `globalThis` that support `cause` property:
-		 * https://github.com/microsoft/TypeScript/blob/main/src/lib/es2022.error.d.ts
-		 * @param {ASTNode} throwStatement The `ThrowStatement` that needs to be checked.
-		 * @returns {boolean} `true` if a new "Error" is being thrown, else `false`.
-		 */
-		function isThrowingNewError(throwStatement) {
-			return (
-				(throwStatement.argument.type === "NewExpression" ||
-					throwStatement.argument.type === "CallExpression") &&
-				throwStatement.argument.callee.type === "Identifier" &&
-				BUILT_IN_ERROR_TYPES.has(throwStatement.argument.callee.name) &&
-				/*
-				 * Make sure the thrown Error is instance is one of the built-in global error types.
-				 * Custom imports could shadow this, which would lead to false positives.
-				 * e.g. import { Error } from "./my-custom-error.js";
-				 *      throw Error("Failed to perform error prone operations");
-				 */
-				sourceCode.isGlobalReference(throwStatement.argument.callee)
-			);
-		}
-
-		/**
-		 * Inserts `cause: <caughtErrorName>` into an inline options object expression.
-		 * @param {RuleFixer} fixer The fixer object.
-		 * @param {ASTNode} optionsNode The options object node.
-		 * @param {string} caughtErrorName The name of the caught error (e.g., "err").
-		 * @returns {Fix} The fix object.
-		 */
-		function insertCauseIntoOptions(fixer, optionsNode, caughtErrorName) {
-			const properties = optionsNode.properties;
-
-			if (properties.length === 0) {
-				// Insert inside empty braces: `{}` → `{ cause: err }`
-				return fixer.insertTextAfter(
-					sourceCode.getFirstToken(optionsNode),
-					`cause: ${caughtErrorName}`,
-				);
-			}
-
-			const lastProp = properties.at(-1);
-			return fixer.insertTextAfter(
-				lastProp,
-				`, cause: ${caughtErrorName}`,
-			);
-		}
-
-		//----------------------------------------------------------------------
-		// Public
-		//----------------------------------------------------------------------
-		return {
-			ThrowStatement(node) {
-				// Check if the throw is inside a catch block
-				const parentCatch = findParentCatch(node);
-				const throwStatement = node;
-
-				// Check if a new error is being thrown in a catch block
-				if (parentCatch && isThrowingNewError(throwStatement)) {
-					if (
-						parentCatch.param &&
-						parentCatch.param.type !== "Identifier"
-					) {
-						/*
-						 * When a part of the caught error is being lost at the parameter level, commonly due to destructuring.
-						 * e.g. catch({ message, ...rest })
-						 */
-						context.report({
-							messageId: "partiallyLostError",
-							node: parentCatch,
-						});
-						return;
-					}
-
-					const caughtError =
-						parentCatch.param?.type === "Identifier"
-							? parentCatch.param
-							: null;
-
-					// Check if there are throw statements and caught error is being ignored
-					if (!caughtError) {
-						if (requireCatchParameter) {
-							context.report({
-								node: throwStatement,
-								messageId: "missingCatchErrorParam",
-							});
-							return;
-						}
-						return;
-					}
-
-					// Check if there is a cause attached to the new error
-					const errorCauseInfo = getErrorCause(throwStatement);
-
-					if (errorCauseInfo === UNKNOWN_CAUSE) {
-						// Error options exist, but too complicated to be analyzed/fixed
-						return;
-					}
-
-					if (errorCauseInfo === null) {
-						// If there is no `cause` attached to the error being thrown.
-						context.report({
-							messageId: "missingCause",
-							node: throwStatement,
-							suggest: [
-								{
-									messageId: "includeCause",
-									fix(fixer) {
-										const throwExpression =
-											throwStatement.argument;
-										const args = throwExpression.arguments;
-										const errorType =
-											throwExpression.callee.name;
-
-										// AggregateError: errors, message, options
-										if (errorType === "AggregateError") {
-											const errorsArg = args[0];
-											const messageArg = args[1];
-											const optionsArg = args[2];
-
-											if (!errorsArg) {
-												// Case: `throw new AggregateError()` → insert all arguments
-												const lastToken =
-													sourceCode.getLastToken(
-														throwExpression,
-													);
-												const lastCalleeToken =
-													sourceCode.getLastToken(
-														throwExpression.callee,
-													);
-												const parenToken =
-													sourceCode.getFirstTokenBetween(
-														lastCalleeToken,
-														lastToken,
-														astUtils.isOpeningParenToken,
-													);
-
-												if (parenToken) {
-													return fixer.insertTextAfter(
-														parenToken,
-														`[], "", { cause: ${caughtError.name} }`,
-													);
-												}
-												return fixer.insertTextAfter(
-													throwExpression.callee,
-													`([], "", { cause: ${caughtError.name} })`,
-												);
-											}
-
-											if (!messageArg) {
-												// Case: `throw new AggregateError([])` → insert message and options
-												return fixer.insertTextAfter(
-													errorsArg,
-													`, "", { cause: ${caughtError.name} }`,
-												);
-											}
-
-											if (!optionsArg) {
-												// Case: `throw new AggregateError([], "")` → insert error options only
-												return fixer.insertTextAfter(
-													messageArg,
-													`, { cause: ${caughtError.name} }`,
-												);
-											}
-
-											if (
-												optionsArg.type ===
-												"ObjectExpression"
-											) {
-												return insertCauseIntoOptions(
-													fixer,
-													optionsArg,
-													caughtError.name,
-												);
-											}
-
-											// Complex dynamic options — skip
-											return null;
-										}
-
-										// Normal Error types
-										const messageArg = args[0];
-										const optionsArg = args[1];
-
-										if (!messageArg) {
-											// Case: `throw new Error()` → insert both message and options
-											const lastToken =
-												sourceCode.getLastToken(
-													throwExpression,
-												);
-											const lastCalleeToken =
-												sourceCode.getLastToken(
-													throwExpression.callee,
-												);
-											const parenToken =
-												sourceCode.getFirstTokenBetween(
-													lastCalleeToken,
-													lastToken,
-													astUtils.isOpeningParenToken,
-												);
-
-											if (parenToken) {
-												return fixer.insertTextAfter(
-													parenToken,
-													`"", { cause: ${caughtError.name} }`,
-												);
-											}
-											return fixer.insertTextAfter(
-												throwExpression.callee,
-												`("", { cause: ${caughtError.name} })`,
-											);
-										}
-										if (!optionsArg) {
-											// Case: `throw new Error("Some message")` → insert only options
-											return fixer.insertTextAfter(
-												messageArg,
-												`, { cause: ${caughtError.name} }`,
-											);
-										}
-
-										if (
-											optionsArg.type ===
-											"ObjectExpression"
-										) {
-											return insertCauseIntoOptions(
-												fixer,
-												optionsArg,
-												caughtError.name,
-											);
-										}
-
-										return null; // Identifier or spread — do not fix
-									},
-								},
-							],
-						});
-
-						// We don't need to check further
-						return;
-					}
-
-					const { value: thrownErrorCause } = errorCauseInfo;
-
-					// If there is an attached cause, verify that it matches the caught error
-					if (
-						!(
-							thrownErrorCause.type === "Identifier" &&
-							thrownErrorCause.name === caughtError.name
-						)
-					) {
-						const suggest = errorCauseInfo.multipleDefinitions
-							? null // If there are multiple `cause` definitions, a suggestion could be confusing.
-							: [
-									{
-										messageId: "includeCause",
-										fix(fixer) {
-											/*
-											 * In case `cause` is attached using object property shorthand or as a method or accessor.
-											 * e.g. throw Error("fail", { cause });
-											 *      throw Error("fail", { cause() { doSomething(); } });
-											 *      throw Error("fail", { get cause() { return error; } });
-											 */
-											if (
-												thrownErrorCause.parent
-													.method ||
-												thrownErrorCause.parent
-													.shorthand ||
-												thrownErrorCause.parent.kind !==
-													"init"
-											) {
-												return fixer.replaceText(
-													thrownErrorCause.parent,
-													`cause: ${caughtError.name}`,
-												);
-											}
-
-											return fixer.replaceText(
-												thrownErrorCause,
-												caughtError.name,
-											);
-										},
-									},
-								];
-						context.report({
-							messageId: "incorrectCause",
-							node: thrownErrorCause,
-							suggest,
-						});
-						return;
-					}
-
-					/*
-					 * If the attached cause matches the identifier name of the caught error,
-					 * make sure it is not being shadowed by a closer scoped redeclaration.
-					 *
-					 * e.g. try {
-					 *      doSomething();
-					 * 	  } catch (error) {
-					 * 	     if (whatever) {
-					 * 	       const error = anotherError;
-					 * 	       throw new Error("Something went wrong");
-					 * 	     }
-					 *   }
-					 */
-					let scope = sourceCode.getScope(throwStatement);
-					do {
-						const variable = scope.set.get(caughtError.name);
-						if (variable) {
-							break;
-						}
-						scope = scope.upper;
-					} while (scope);
-
-					if (scope?.block !== parentCatch) {
-						// Caught error is being shadowed
-						context.report({
-							messageId: "caughtErrorShadowed",
-							node: throwStatement,
-						});
-					}
-				}
-			},
-		};
-	},
-};