eslint-plugin-absolute 0.1.6 → 0.2.1

package/src/rules/localize-react-props.ts

@@ -0,0 +1,454 @@
+import { TSESLint, TSESTree, AST_NODE_TYPES } from "@typescript-eslint/utils";
+
+type Options = [];
+type MessageIds = "stateAndSetterToChild" | "variableToChild";
+
+type ComponentFunction =
+	| TSESTree.FunctionDeclaration
+	| TSESTree.FunctionExpression
+	| TSESTree.ArrowFunctionExpression;
+
+type Usage = {
+	jsxUsageSet: Set<TSESTree.JSXElement>;
+	hasOutsideUsage: boolean;
+};
+
+type CandidateVariable = {
+	node: TSESTree.VariableDeclarator;
+	varName: string;
+	componentName: string;
+};
+
+export const localizeReactProps: TSESLint.RuleModule<MessageIds, Options> = {
+	create(context) {
+		// A list of candidate variables for reporting (for general variables only).
+		const candidateVariables: CandidateVariable[] = [];
+
+		const getSingleSetElement = <T>(set: Set<T>) => {
+			for (const value of set) {
+				return value;
+			}
+			return null;
+		};
+
+		const getRightmostJSXIdentifier = (
+			name: TSESTree.JSXTagNameExpression
+		) => {
+			let current: TSESTree.JSXTagNameExpression = name;
+			while (current.type === AST_NODE_TYPES.JSXMemberExpression) {
+				current = current.property;
+			}
+			if (current.type === AST_NODE_TYPES.JSXIdentifier) {
+				return current;
+			}
+			return null;
+		};
+
+		const getLeftmostJSXIdentifier = (
+			name: TSESTree.JSXTagNameExpression
+		) => {
+			let current: TSESTree.JSXTagNameExpression = name;
+			while (current.type === AST_NODE_TYPES.JSXMemberExpression) {
+				current = current.object;
+			}
+			if (current.type === AST_NODE_TYPES.JSXIdentifier) {
+				return current;
+			}
+			return null;
+		};
+
+		// Helper: Extract the component name from a JSXElement.
+		const getJSXElementName = (jsxElement: TSESTree.JSXElement | null) => {
+			if (
+				!jsxElement ||
+				!jsxElement.openingElement ||
+				!jsxElement.openingElement.name
+			) {
+				return "";
+			}
+			const nameNode = jsxElement.openingElement.name;
+			if (nameNode.type === AST_NODE_TYPES.JSXIdentifier) {
+				return nameNode.name;
+			}
+			const rightmost = getRightmostJSXIdentifier(nameNode);
+			if (rightmost) {
+				return rightmost.name;
+			}
+			return "";
+		};
+
+		// Helper: Check if the node is a call to useState.
+		const isUseStateCall = (
+			node: TSESTree.Node | null
+		): node is TSESTree.CallExpression =>
+			node !== null &&
+			node.type === AST_NODE_TYPES.CallExpression &&
+			node.callee !== null &&
+			((node.callee.type === AST_NODE_TYPES.Identifier &&
+				node.callee.name === "useState") ||
+				(node.callee.type === AST_NODE_TYPES.MemberExpression &&
+					node.callee.property !== null &&
+					node.callee.property.type === AST_NODE_TYPES.Identifier &&
+					node.callee.property.name === "useState"));
+
+		// Helper: Check if a call expression is a hook call (other than useState).
+		const isHookCall = (
+			node: TSESTree.Node | null
+		): node is TSESTree.CallExpression =>
+			node !== null &&
+			node.type === AST_NODE_TYPES.CallExpression &&
+			node.callee !== null &&
+			node.callee.type === AST_NODE_TYPES.Identifier &&
+			/^use[A-Z]/.test(node.callee.name) &&
+			node.callee.name !== "useState";
+
+		// Helper: Walk upward to find the closest JSXElement ancestor.
+		const getJSXAncestor = (node: TSESTree.Node) => {
+			let current: TSESTree.Node | null | undefined = node.parent;
+			while (current) {
+				if (current.type === AST_NODE_TYPES.JSXElement) {
+					return current;
+				}
+				current = current.parent;
+			}
+			return null;
+		};
+
+		const getTagNameFromOpening = (
+			openingElement: TSESTree.JSXOpeningElement
+		) => {
+			const nameNode = openingElement.name;
+			if (nameNode.type === AST_NODE_TYPES.JSXIdentifier) {
+				return nameNode.name;
+			}
+			const rightmost = getRightmostJSXIdentifier(nameNode);
+			return rightmost ? rightmost.name : null;
+		};
+
+		const isProviderOrContext = (tagName: string) =>
+			tagName.endsWith("Provider") || tagName.endsWith("Context");
+
+		const isValueAttributeOnProvider = (node: TSESTree.Node) =>
+			node.type === AST_NODE_TYPES.JSXAttribute &&
+			node.name &&
+			node.name.type === AST_NODE_TYPES.JSXIdentifier &&
+			node.name.name === "value" &&
+			node.parent &&
+			node.parent.type === AST_NODE_TYPES.JSXOpeningElement &&
+			(() => {
+				const tagName = getTagNameFromOpening(node.parent);
+				return tagName !== null && isProviderOrContext(tagName);
+			})();
+
+		// Helper: Check whether the given node is inside a JSXAttribute "value"
+		// that belongs to a context-like component (i.e. tag name ends with Provider or Context).
+		const isContextProviderValueProp = (node: TSESTree.Node) => {
+			let current: TSESTree.Node | null | undefined = node.parent;
+			while (current) {
+				if (isValueAttributeOnProvider(current)) {
+					return true;
+				}
+				current = current.parent;
+			}
+			return false;
+		};
+
+		// Helper: Determine if a JSXElement is a custom component (tag name begins with an uppercase letter).
+		const isCustomJSXElement = (jsxElement: TSESTree.JSXElement | null) => {
+			if (
+				!jsxElement ||
+				!jsxElement.openingElement ||
+				!jsxElement.openingElement.name
+			) {
+				return false;
+			}
+			const nameNode = jsxElement.openingElement.name;
+			if (nameNode.type === AST_NODE_TYPES.JSXIdentifier) {
+				return /^[A-Z]/.test(nameNode.name);
+			}
+			const leftmost = getLeftmostJSXIdentifier(nameNode);
+			return leftmost !== null && /^[A-Z]/.test(leftmost.name);
+		};
+
+		// Helper: Find the nearest enclosing function (assumed to be the component).
+		const getComponentFunction = (node: TSESTree.Node | null) => {
+			let current: TSESTree.Node | null | undefined = node;
+			while (current) {
+				if (
+					current.type === AST_NODE_TYPES.FunctionDeclaration ||
+					current.type === AST_NODE_TYPES.FunctionExpression ||
+					current.type === AST_NODE_TYPES.ArrowFunctionExpression
+				) {
+					return current;
+				}
+				current = current.parent;
+			}
+			return null;
+		};
+
+		const findVariableForIdentifier = (identifier: TSESTree.Identifier) => {
+			let scope: TSESLint.Scope.Scope | null =
+				context.sourceCode.getScope(identifier);
+			while (scope) {
+				const found = scope.variables.find((variable) =>
+					variable.defs.some((def) => def.name === identifier)
+				);
+				if (found) {
+					return found;
+				}
+				scope = scope.upper ?? null;
+			}
+			return null;
+		};
+
+		// Analyze variable usage using ESLint scopes (no manual AST crawling).
+		// Only count a usage if it occurs inside a custom JSX element (and is not inside a context provider's "value" prop).
+		const classifyReference = (
+			reference: TSESLint.Scope.Reference,
+			declarationId: TSESTree.Identifier,
+			jsxUsageSet: Set<TSESTree.JSXElement>
+		) => {
+			const { identifier } = reference;
+
+			if (
+				identifier === declarationId ||
+				isContextProviderValueProp(identifier)
+			) {
+				return false;
+			}
+
+			const jsxAncestor = getJSXAncestor(identifier);
+			if (jsxAncestor && isCustomJSXElement(jsxAncestor)) {
+				jsxUsageSet.add(jsxAncestor);
+				return false;
+			}
+			return true;
+		};
+
+		const analyzeVariableUsage = (
+			declarationId: TSESTree.Identifier
+		): Usage => {
+			const variable = findVariableForIdentifier(declarationId);
+			if (!variable) {
+				return {
+					hasOutsideUsage: false,
+					jsxUsageSet: new Set<TSESTree.JSXElement>()
+				};
+			}
+
+			const jsxUsageSet = new Set<TSESTree.JSXElement>();
+			const hasOutsideUsage = variable.references.some((ref) =>
+				classifyReference(ref, declarationId, jsxUsageSet)
+			);
+
+			return {
+				hasOutsideUsage,
+				jsxUsageSet
+			};
+		};
+
+		// Manage hook-derived variables.
+		const componentHookVars = new WeakMap<ComponentFunction, Set<string>>();
+		const getHookSet = (componentFunction: ComponentFunction) => {
+			let hookSet = componentHookVars.get(componentFunction);
+			if (!hookSet) {
+				hookSet = new Set<string>();
+				componentHookVars.set(componentFunction, hookSet);
+			}
+			return hookSet;
+		};
+
+		const isRangeContained = (
+			refRange: [number, number],
+			nodeRange: [number, number]
+		) => refRange[0] >= nodeRange[0] && refRange[1] <= nodeRange[1];
+
+		const variableHasReferenceInRange = (
+			variable: TSESLint.Scope.Variable,
+			nodeRange: [number, number]
+		) =>
+			variable.references.some(
+				(reference) =>
+					reference.identifier.range !== undefined &&
+					isRangeContained(reference.identifier.range, nodeRange)
+			);
+
+		const hasHookDependency = (
+			node: TSESTree.Node,
+			hookSet: Set<string>
+		) => {
+			if (!node.range) {
+				return false;
+			}
+			const nodeRange = node.range;
+
+			let scope: TSESLint.Scope.Scope | null =
+				context.sourceCode.getScope(node);
+
+			while (scope) {
+				const hookVars = scope.variables.filter((variable) =>
+					hookSet.has(variable.name)
+				);
+				if (
+					hookVars.some((variable) =>
+						variableHasReferenceInRange(variable, nodeRange)
+					)
+				) {
+					return true;
+				}
+				scope = scope.upper ?? null;
+			}
+
+			return false;
+		};
+
+		const processUseStateDeclarator = (
+			node: TSESTree.VariableDeclarator
+		) => {
+			if (
+				!node.init ||
+				!isUseStateCall(node.init) ||
+				node.id.type !== AST_NODE_TYPES.ArrayPattern ||
+				node.id.elements.length < 2
+			) {
+				return false;
+			}
+
+			const [stateElem, setterElem] = node.id.elements;
+			if (
+				!stateElem ||
+				stateElem.type !== AST_NODE_TYPES.Identifier ||
+				!setterElem ||
+				setterElem.type !== AST_NODE_TYPES.Identifier
+			) {
+				return false;
+			}
+
+			const stateVarName = stateElem.name;
+			const setterVarName = setterElem.name;
+
+			const stateUsage = analyzeVariableUsage(stateElem);
+			const setterUsage = analyzeVariableUsage(setterElem);
+
+			const stateExclusivelySingleJSX =
+				!stateUsage.hasOutsideUsage &&
+				stateUsage.jsxUsageSet.size === 1;
+			const setterExclusivelySingleJSX =
+				!setterUsage.hasOutsideUsage &&
+				setterUsage.jsxUsageSet.size === 1;
+
+			if (!stateExclusivelySingleJSX || !setterExclusivelySingleJSX) {
+				return true;
+			}
+
+			const stateTarget = getSingleSetElement(stateUsage.jsxUsageSet);
+			const setterTarget = getSingleSetElement(setterUsage.jsxUsageSet);
+			if (stateTarget && stateTarget === setterTarget) {
+				context.report({
+					data: { setterVarName, stateVarName },
+					messageId: "stateAndSetterToChild",
+					node: node
+				});
+			}
+			return true;
+		};
+
+		const processGeneralVariable = (
+			node: TSESTree.VariableDeclarator,
+			componentFunction: ComponentFunction
+		) => {
+			if (!node.id || node.id.type !== AST_NODE_TYPES.Identifier) {
+				return;
+			}
+
+			const varName = node.id.name;
+			// Exempt variables that depend on hooks.
+			if (node.init) {
+				const hookSet = getHookSet(componentFunction);
+				if (hasHookDependency(node.init, hookSet)) {
+					return;
+				}
+			}
+			const usage = analyzeVariableUsage(node.id);
+			if (!usage.hasOutsideUsage && usage.jsxUsageSet.size === 1) {
+				const target = getSingleSetElement(usage.jsxUsageSet);
+				const componentName = getJSXElementName(target);
+				candidateVariables.push({
+					componentName,
+					node,
+					varName
+				});
+			}
+		};
+
+		return {
+			// At the end of the traversal, group candidate variables by the target component name.
+			"Program:exit"() {
+				const groups = new Map<string, CandidateVariable[]>();
+				candidateVariables.forEach((candidate) => {
+					const key = candidate.componentName;
+					const existing = groups.get(key);
+					if (existing) {
+						existing.push(candidate);
+					} else {
+						groups.set(key, [candidate]);
+					}
+				});
+				// Only report candidates for a given component type if there is exactly one candidate.
+				groups.forEach((candidates) => {
+					if (candidates.length !== 1) {
+						return;
+					}
+					const [candidate] = candidates;
+					if (!candidate) {
+						return;
+					}
+					context.report({
+						data: { varName: candidate.varName },
+						messageId: "variableToChild",
+						node: candidate.node
+					});
+				});
+			},
+			VariableDeclarator(node: TSESTree.VariableDeclarator) {
+				const componentFunction = getComponentFunction(node);
+				if (!componentFunction || !componentFunction.body) return;
+
+				// Record hook-derived variables (for hooks other than useState).
+				if (
+					node.init &&
+					node.id &&
+					node.id.type === AST_NODE_TYPES.Identifier &&
+					node.init.type === AST_NODE_TYPES.CallExpression &&
+					isHookCall(node.init)
+				) {
+					const hookSet = getHookSet(componentFunction);
+					hookSet.add(node.id.name);
+				}
+
+				// Case 1: useState destructuring (state & setter).
+				const wasUseState = processUseStateDeclarator(node);
+
+				// Case 2: General variable.
+				if (!wasUseState) {
+					processGeneralVariable(node, componentFunction);
+				}
+			}
+		};
+	},
+	defaultOptions: [],
+	meta: {
+		docs: {
+			description:
+				"Disallow variables that are only passed to a single custom child component. For useState, only report if both the state and its setter are exclusively passed to a single custom child. For general variables, only report if a given child receives exactly one such candidate – if two or more are passed to the same component type, they're assumed to be settings that belong on the parent."
+		},
+		messages: {
+			stateAndSetterToChild:
+				"State variable '{{stateVarName}}' and its setter '{{setterVarName}}' are only passed to a single custom child component. Consider moving the state into that component.",
+			variableToChild:
+				"Variable '{{varName}}' is only passed to a single custom child component. Consider moving it to that component."
+		},
+		schema: [],
+		type: "suggestion"
+	}
+};

package/src/rules/max-depth-extended.ts

@@ -0,0 +1,153 @@
+import { TSESLint, TSESTree } from "@typescript-eslint/utils";
+
+type Options = [number?];
+type MessageIds = "tooDeep";
+
+export const maxDepthExtended: TSESLint.RuleModule<MessageIds, Options> = {
+	create(context) {
+		const [option] = context.options;
+		const maxDepth = typeof option === "number" ? option : 1;
+		const functionStack: number[] = [];
+
+		// Helper to get ancestors of a node by walking its parent chain.
+		const getAncestors = (node: TSESTree.Node) => {
+			const ancestors: TSESTree.Node[] = [];
+			let current: TSESTree.Node | null | undefined = node.parent;
+			while (current) {
+				ancestors.push(current);
+				current = current.parent;
+			}
+			return ancestors;
+		};
+
+		// Check if a block only contains a single early exit: return or throw.
+		const isEarlyExitBlock = (node: TSESTree.BlockStatement) => {
+			if (node.body.length !== 1) {
+				return false;
+			}
+			const [first] = node.body;
+			if (!first) {
+				return false;
+			}
+			return (
+				first.type === "ReturnStatement" ||
+				first.type === "ThrowStatement"
+			);
+		};
+
+		const isFunctionBody = (node: TSESTree.BlockStatement) => {
+			const ancestors = getAncestors(node);
+			const [parent] = ancestors;
+			return (
+				parent &&
+				(parent.type === "FunctionDeclaration" ||
+					parent.type === "FunctionExpression" ||
+					parent.type === "ArrowFunctionExpression") &&
+				node === parent.body
+			);
+		};
+
+		const incrementCurrentDepth = () => {
+			if (functionStack.length === 0) {
+				return null;
+			}
+			const index = functionStack.length - 1;
+			const currentDepth = functionStack[index];
+			if (typeof currentDepth !== "number") {
+				return null;
+			}
+			const nextDepth = currentDepth + 1;
+			functionStack[index] = nextDepth;
+			return nextDepth;
+		};
+
+		const decrementCurrentDepth = () => {
+			if (functionStack.length === 0) {
+				return;
+			}
+			const index = functionStack.length - 1;
+			const currentDepth = functionStack[index];
+			if (typeof currentDepth !== "number") {
+				return;
+			}
+			functionStack[index] = currentDepth - 1;
+		};
+
+		// Report if the current depth exceeds the allowed maximum.
+		const checkDepth = (node: TSESTree.BlockStatement, depth: number) => {
+			if (depth > maxDepth) {
+				context.report({
+					data: { depth, maxDepth },
+					messageId: "tooDeep",
+					node
+				});
+			}
+		};
+
+		return {
+			ArrowFunctionExpression() {
+				functionStack.push(0);
+			},
+			"ArrowFunctionExpression:exit"() {
+				functionStack.pop();
+			},
+			BlockStatement(node: TSESTree.BlockStatement) {
+				// Do not count if this block is the body of a function.
+				if (isFunctionBody(node)) {
+					return;
+				}
+
+				// Skip blocks that only have an early exit.
+				if (isEarlyExitBlock(node)) {
+					return;
+				}
+
+				const depth = incrementCurrentDepth();
+				if (depth !== null) {
+					checkDepth(node, depth);
+				}
+			},
+			"BlockStatement:exit"(node: TSESTree.BlockStatement) {
+				if (isFunctionBody(node)) {
+					return;
+				}
+
+				if (isEarlyExitBlock(node)) {
+					return;
+				}
+
+				decrementCurrentDepth();
+			},
+			FunctionDeclaration() {
+				functionStack.push(0);
+			},
+			"FunctionDeclaration:exit"() {
+				functionStack.pop();
+			},
+			FunctionExpression() {
+				functionStack.push(0);
+			},
+			"FunctionExpression:exit"() {
+				functionStack.pop();
+			}
+		};
+	},
+	defaultOptions: [1],
+	meta: {
+		docs: {
+			description:
+				"disallow too many nested blocks except when the block only contains an early exit (return or throw)"
+		},
+		messages: {
+			tooDeep:
+				"Blocks are nested too deeply ({{depth}}). Maximum allowed is {{maxDepth}} or an early exit."
+		},
+		schema: [
+			{
+				// Accepts a single number as the maximum allowed depth.
+				type: "number"
+			}
+		],
+		type: "suggestion"
+	}
+};

package/src/rules/{max-jsx-nesting.js → max-jsx-nesting.ts}

@@ -1,60 +1,59 @@
-export default {
-	meta: {
-		type: "suggestion",
-		docs: {
-			description:
-				"Warn when JSX elements are nested too deeply, suggesting refactoring into a separate component.",
-			recommended: false
-		},
-		// The rule accepts a single numeric option (minimum 1)
-		schema: [
-			{
-				type: "number",
-				minimum: 1
-			}
-		],
-		messages: {
-			tooDeeplyNested:
-				"JSX element is nested too deeply ({{level}} levels, allowed is {{maxAllowed}} levels). Consider refactoring into a separate component."
-		}
-	},
+import { TSESLint, TSESTree } from "@typescript-eslint/utils";
+
+type Options = [number];
+type MessageIds = "tooDeeplyNested";
+
+const isJSXAncestor = (node: TSESTree.Node) =>
+	node.type === "JSXElement" || node.type === "JSXFragment";
+
+export const maxJSXNesting: TSESLint.RuleModule<MessageIds, Options> = {
 	create(context) {
-		// At this point, the provided option is guaranteed to be a number >= 1.
-		const maxAllowed = context.options[0];
+		const [option] = context.options;
+		const maxAllowed = typeof option === "number" ? option : 1;
 
 		/**
 		 * Calculates the JSX nesting level for the given node by traversing the node.parent chain.
-		 * The level is computed by counting the current node (level 1) plus each ancestor
-		 * that is a JSXElement or JSXFragment.
-		 * @param {ASTNode} node The JSX element node.
-		 * @returns {number} The nesting level.
 		 */
-		function getJSXNestingLevel(node) {
+		const getJSXNestingLevel = (node: TSESTree.Node) => {
 			let level = 1; // count the current node as level 1
-			let current = node.parent;
+			let current: TSESTree.Node | null | undefined = node.parent;
 			while (current) {
-				if (
-					current.type === "JSXElement" ||
-					current.type === "JSXFragment"
-				) {
-					level++;
-				}
+				level += isJSXAncestor(current) ? 1 : 0;
 				current = current.parent;
 			}
 			return level;
-		}
+		};
 
 		return {
-			JSXElement(node) {
+			JSXElement(node: TSESTree.JSXElement) {
 				const level = getJSXNestingLevel(node);
 				if (level > maxAllowed) {
 					context.report({
-						node,
+						data: { level, maxAllowed },
 						messageId: "tooDeeplyNested",
-						data: { level, maxAllowed }
+						node
 					});
 				}
 			}
 		};
+	},
+	defaultOptions: [1],
+	meta: {
+		docs: {
+			description:
+				"Warn when JSX elements are nested too deeply, suggesting refactoring into a separate component."
+		},
+		messages: {
+			tooDeeplyNested:
+				"JSX element is nested too deeply ({{level}} levels, allowed is {{maxAllowed}} levels). Consider refactoring into a separate component."
+		},
+		// The rule accepts a single numeric option (minimum 1)
+		schema: [
+			{
+				minimum: 1,
+				type: "number"
+			}
+		],
+		type: "suggestion"
 	}
 };