eslint-plugin-ocavue 0.2.0 → 0.3.0

package/README.md

@@ -21,6 +21,9 @@ export default [
     plugins: { ocavue },
     rules: {
       'ocavue/no-implicit-arrow-linebreak': 'error',
+      'ocavue/prefer-constant-function': 'error',
+      'ocavue/prefer-noop': 'error',
+      'ocavue/prefer-sleep': 'error',
       'ocavue/prefer-while-true': 'error',
     },
   },
@@ -35,9 +38,9 @@ Disallow a linebreak between `=>` and an implicit arrow function body. Unlike [`
 
 ```js
 // Incorrect
-const items = Array.from({ length: count }, (_, index) =>
-  createItem(index === 0 ? 'first item label' : `item number ${index}`),
-)
+const items = Array.from({ length: count }, (_, index) => {
+  return createItem(index === 0 ? 'first item label' : `item number ${index}`)
+})
 
 // Correct
 const short = (index) => createItem(`item number ${index}`)
@@ -50,13 +53,85 @@ const items = Array.from({ length: count }, (_, index) => {
 
 When a comment sits between `=>` and the body, the rule reports without autofixing so the fix never drops a comment.
 
+### `prefer-constant-function`
+
+Enforce `returnTrue`, `returnFalse` and `returnNull` from [`@ocavue/utils`](https://github.com/ocavue/utils) instead of inline functions such as `() => true`, `() => false` and `() => null`.
+
+```js
+// Incorrect
+const all = items.filter(() => true)
+
+// Correct (what the suggestion produces)
+import { returnTrue } from '@ocavue/utils'
+
+const all = items.filter(returnTrue)
+```
+
+The rule offers an editor suggestion, not an autofix. `returnFalse` returns the literal type `false`, while TypeScript infers `() => false` as `() => boolean`, so the swap can narrow an inferred type:
+
+```ts
+const [open, setOpen] = useState(() => false) // open: boolean
+const [open, setOpen] = useState(returnFalse) // open: false, so setOpen(true) is a type error
+```
+
+The rule uses the same `checkDependency` option, skip conditions and import handling as [`prefer-noop`](#prefer-noop).
+
+### `prefer-noop`
+
+Enforce `noop` from [`@ocavue/utils`](https://github.com/ocavue/utils) instead of inline empty functions such as `() => {}`, `() => undefined` and `function () {}`. A shared `noop` reads as intent ("do nothing on purpose") and avoids creating a new function on every render or call.
+
+```js
+// Incorrect
+;<button onClick={() => {}} />
+
+// Correct (what the fixer produces)
+import { noop } from '@ocavue/utils'
+
+;<button onClick={noop} />
+```
+
+The rule only runs when the nearest `package.json` of the linted file lists `@ocavue/utils` in `dependencies`, `devDependencies` or `peerDependencies`, or when the file already imports `@ocavue/utils`. Set `checkDependency: false` to run it in every file:
+
+```js
+export default [
+  {
+    rules: {
+      'ocavue/prefer-noop': ['error', { checkDependency: false }],
+    },
+  },
+]
+```
+
+The rule skips functions where the swap could change runtime behavior: `async` functions, generators, named function expressions, methods, and functions with default values or destructuring in their parameters.
+
+The fixer adds `noop` to an existing `import { ... } from '@ocavue/utils'`, or adds a new import. It reports without autofixing when the function holds a comment, when another binding named `noop` is in scope, or when the file is not an ES module.
+
+### `prefer-sleep`
+
+Enforce `sleep` from [`@ocavue/utils`](https://github.com/ocavue/utils) instead of a `new Promise` that only resolves after `setTimeout`.
+
+```js
+// Incorrect
+await new Promise((resolve) => setTimeout(resolve, 100))
+await new Promise((resolve) => setTimeout(() => resolve(), 100))
+
+// Correct (what the fixer produces)
+import { sleep } from '@ocavue/utils'
+
+await sleep(100)
+```
+
+The rule also matches `globalThis.setTimeout` and `window.setTimeout`, block bodies, and `new Promise<void>` in TypeScript. It skips promises that resolve with a value, pass extra arguments to `setTimeout`, or compute the delay from the executor's parameters.
+
+The rule uses the same `checkDependency` option and import handling as [`prefer-noop`](#prefer-noop).
+
 ### `prefer-while-true`
 
 Enforce `while (true)` instead of `for (;;)` for infinite loops. Rules such as [`no-constant-condition`](https://eslint.org/docs/latest/rules/no-constant-condition) (with `checkLoops: "all"`) and [`@typescript-eslint/no-unnecessary-condition`](https://typescript-eslint.io/rules/no-unnecessary-condition) report `while (true)` but not `for (;;)`, so people often rewrite the loop as `for (;;)` to silence them. That only hides the infinite loop from the linter: the code still loops forever. This rule removes that workaround. `while (true)` also reads more clearly than `for (;;)`.
 
 ```js
 // Incorrect
-for (;;) {
+while (true) {
   step()
 }
 

package/dist/index.d.ts

@@ -6,6 +6,9 @@ declare const plugin: {
   };
   rules: {
     'no-implicit-arrow-linebreak': import("eslint").Rule.RuleModule;
+    'prefer-constant-function': import("eslint").Rule.RuleModule;
+    'prefer-noop': import("eslint").Rule.RuleModule;
+    'prefer-sleep': import("eslint").Rule.RuleModule;
     'prefer-while-true': import("eslint").Rule.RuleModule;
   };
 };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";cAOM"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";cAUM"}

package/dist/index.js

@@ -1,40 +1,438 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region package.json
+var version = "0.3.0";
+//#endregion
+//#region src/rules/no-implicit-arrow-linebreak.ts
+const rule$4 = {
+	meta: {
+		type: "layout",
+		fixable: "code",
+		docs: {
+			description: "disallow a linebreak between `=>` and an implicit arrow function body, fixing it to a block body with `return`",
+			url: "https://github.com/ocavue/eslint-plugin-ocavue#no-implicit-arrow-linebreak"
+		},
+		messages: { linebreak: "Implicit arrow body must not start on a new line. Use a block body with `return` instead." },
+		schema: []
+	},
+	create(context) {
+		const sourceCode = context.sourceCode;
+		return { ArrowFunctionExpression(node) {
+			if (node.body.type === "BlockStatement") return;
+			const arrowToken = sourceCode.getTokenBefore(node.body, { filter: (token) => token.type === "Punctuator" && token.value === "=>" });
+			if (!arrowToken) return;
+			const firstBodyToken = sourceCode.getTokenAfter(arrowToken);
+			const lastToken = sourceCode.getLastToken(node);
+			if (!firstBodyToken || !lastToken) return;
+			if (arrowToken.loc.end.line === firstBodyToken.loc.start.line) return;
+			const canFix = !sourceCode.commentsExistBetween(arrowToken, firstBodyToken);
+			context.report({
+				node: node.body,
+				messageId: "linebreak",
+				fix: canFix ? (fixer) => {
+					const bodyText = sourceCode.text.slice(firstBodyToken.range[0], lastToken.range[1]);
+					return fixer.replaceTextRange([arrowToken.range[1], lastToken.range[1]], ` { return ${bodyText} }`);
+				} : void 0
+			});
+		} };
+	}
+};
+//#endregion
+//#region src/utils/constant-function.ts
+function getConstantValue(node) {
+	if (node.type === "Literal") {
+		switch (node.raw) {
+			case "true":
+			case "false":
+			case "null": return node.raw;
+		}
+		return;
+	}
+	if (node.type === "Identifier" && node.name === "undefined") return "undefined";
+	if (node.type === "UnaryExpression" && node.operator === "void" && node.argument.type === "Literal") return "undefined";
+}
+function getReturnedValue(node) {
+	const body = node.body;
+	if (body.type !== "BlockStatement") return getConstantValue(body);
+	if (body.body.length === 0) return "undefined";
+	if (body.body.length === 1) {
+		const statement = body.body[0];
+		if (statement.type === "ReturnStatement") return statement.argument ? getConstantValue(statement.argument) : "undefined";
+	}
+}
+/**
+* Returns true when the function can be swapped with a function reference
+* without changing runtime behavior.
+*/
+function isReplaceable(node) {
+	if (node.async || node.generator) return false;
+	if (node.typeParameters) return false;
+	if (!node.params.every((param) => {
+		return param.type === "Identifier" || param.type === "RestElement" && param.argument.type === "Identifier";
+	})) return false;
+	if (node.type === "FunctionExpression") {
+		if (node.id) return false;
+		const parent = node.parent;
+		if (parent.type === "Property" && (parent.method || parent.kind !== "init")) return false;
+		if (parent.type === "MethodDefinition") return false;
+		if (parent.type === "NewExpression" && parent.callee === node) return false;
+	}
+	return true;
+}
+/**
+* Returns the value that an inline function always returns, such as
+* `'true'` for `() => true` or `'undefined'` for `() => {}`. Returns
+* `undefined` when the function does more than that, or when replacing it
+* could change runtime behavior.
+*/
+function getConstantFunctionValue(node) {
+	return isReplaceable(node) ? getReturnedValue(node) : void 0;
+}
+//#endregion
+//#region src/utils/has-dependency.ts
+const cache = /* @__PURE__ */ new Map();
+function readPackageJson(dir) {
+	let text;
+	try {
+		text = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+	} catch {
+		return;
+	}
+	try {
+		const json = JSON.parse(text);
+		return json && typeof json === "object" ? json : {};
+	} catch {
+		return {};
+	}
+}
+function findNearestPackageJson(startDir) {
+	const visited = [];
+	let dir = startDir;
+	let result = null;
+	while (true) {
+		const cached = cache.get(dir);
+		if (cached !== void 0) {
+			result = cached;
+			break;
+		}
+		visited.push(dir);
+		const pkg = readPackageJson(dir);
+		if (pkg) {
+			result = pkg;
+			break;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	for (const visitedDir of visited) cache.set(visitedDir, result);
+	return result;
+}
+/**
+* Returns true when the nearest `package.json` of `filename` lists
+* `packageName` in `dependencies`, `devDependencies` or `peerDependencies`.
+*
+* A package never depends on itself, so this returns false inside the
+* package named `packageName`.
+*/
+function hasDependency(filename, packageName) {
+	if (!path.isAbsolute(filename)) return false;
+	const pkg = findNearestPackageJson(path.dirname(filename));
+	if (!pkg || pkg.name === packageName) return false;
+	return [
+		pkg.dependencies,
+		pkg.devDependencies,
+		pkg.peerDependencies
+	].some((deps) => deps != null && typeof deps === "object" && Object.hasOwn(deps, packageName));
+}
+//#endregion
+//#region src/utils/package-import.ts
+const UTILS_PACKAGE = "@ocavue/utils";
+const packageRuleSchema = [{
+	type: "object",
+	properties: { checkDependency: { type: "boolean" } },
+	additionalProperties: false
+}];
+function getImportKind(node) {
+	return node.importKind;
+}
+function getImportedName(specifier) {
+	const imported = specifier.imported;
+	return imported.type === "Identifier" ? imported.name : String(imported.value);
+}
+/**
+* Returns the value `import` declarations of `packageName` in the program.
+*/
+function getPackageImports(program, packageName) {
+	return program.body.filter((statement) => {
+		return statement.type === "ImportDeclaration" && statement.source.value === packageName && getImportKind(statement) !== "type";
+	});
+}
+/**
+* Returns true when the linted file can import from `packageName`: the
+* nearest `package.json` depends on it, or the file already imports it. The
+* `checkDependency: false` option skips the check.
+*/
+function isPackageAvailable(context, packageName) {
+	if ((context.options[0] ?? {}).checkDependency === false) return true;
+	return hasDependency(context.physicalFilename, packageName) || getPackageImports(context.sourceCode.ast, packageName).length > 0;
+}
+function findVariable(scope, name) {
+	for (let current = scope; current; current = current.upper) {
+		const variable = current.set.get(name);
+		if (variable) return variable;
+	}
+}
+/**
+* Creates a fix that replaces `node` and makes sure `name` is imported from
+* `packageName`. Returns `undefined` when the fix is not safe: the file is
+* not an ES module, the node holds comments, or another binding already uses
+* the name.
+*/
+function createImportFix({ context, node, name, packageName, replace }) {
+	const sourceCode = context.sourceCode;
+	const program = sourceCode.ast;
+	if (context.languageOptions.sourceType !== "module") return;
+	if (sourceCode.getCommentsInside(node).length > 0) return;
+	const scope = sourceCode.getScope(node);
+	const packageImports = getPackageImports(program, packageName);
+	for (const declaration of packageImports) for (const specifier of declaration.specifiers) {
+		if (specifier.type !== "ImportSpecifier" || getImportKind(specifier) === "type" || getImportedName(specifier) !== name) continue;
+		const local = specifier.local.name;
+		if (findVariable(scope, local)?.defs[0]?.node === specifier) return (fixer) => fixer.replaceText(node, replace(local));
+	}
+	if (findVariable(scope, name)) return;
+	if (sourceCode.scopeManager.globalScope?.through.some((reference) => reference.identifier.name === name)) return;
+	const replacement = replace(name);
+	const namedImport = packageImports.find((declaration) => {
+		return declaration.specifiers.some((specifier) => specifier.type === "ImportSpecifier");
+	});
+	if (namedImport) {
+		const lastSpecifier = namedImport.specifiers.at(-1);
+		return (fixer) => [fixer.replaceText(node, replacement), fixer.insertTextAfter(lastSpecifier, `, ${name}`)];
+	}
+	const importText = `import { ${name} } from '${packageName}'`;
+	const lastImport = program.body.findLast((statement) => statement.type === "ImportDeclaration");
+	if (lastImport) {
+		const semicolon = sourceCode.getText(lastImport).endsWith(";") ? ";" : "";
+		return (fixer) => [fixer.replaceText(node, replacement), fixer.insertTextAfter(lastImport, `\n${importText}${semicolon}`)];
+	}
+	const firstStatement = program.body.find((statement) => {
+		return !(statement.type === "ExpressionStatement" && typeof statement.directive === "string");
+	});
+	if (!firstStatement) return;
+	return (fixer) => [fixer.replaceText(node, replacement), fixer.insertTextBefore(firstStatement, `${importText}\n`)];
+}
+//#endregion
+//#region src/rules/prefer-constant-function.ts
+const FUNCTION_NAMES = {
+	true: "returnTrue",
+	false: "returnFalse",
+	null: "returnNull"
+};
+const rule$3 = {
+	meta: {
+		type: "suggestion",
+		hasSuggestions: true,
+		docs: {
+			description: "enforce `returnTrue`, `returnFalse` and `returnNull` from `@ocavue/utils` instead of inline functions",
+			url: "https://github.com/ocavue/eslint-plugin-ocavue#prefer-constant-function"
+		},
+		messages: {
+			preferConstantFunction: "Use `{{name}}` from `@ocavue/utils` instead of an inline function.",
+			replaceWithConstantFunction: "Replace with `{{name}}` from `@ocavue/utils`."
+		},
+		schema: packageRuleSchema
+	},
+	create(context) {
+		if (!isPackageAvailable(context, "@ocavue/utils")) return {};
+		function check(node) {
+			const value = getConstantFunctionValue(node);
+			const name = value && FUNCTION_NAMES[value];
+			if (!name) return;
+			const fix = createImportFix({
+				context,
+				node,
+				name,
+				packageName: UTILS_PACKAGE,
+				replace: (local) => local
+			});
+			context.report({
+				node,
+				messageId: "preferConstantFunction",
+				data: { name },
+				suggest: fix ? [{
+					messageId: "replaceWithConstantFunction",
+					data: { name },
+					fix
+				}] : []
+			});
+		}
+		return {
+			ArrowFunctionExpression: check,
+			FunctionExpression: check
+		};
+	}
+};
+//#endregion
+//#region src/rules/prefer-noop.ts
+const rule$2 = {
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "enforce `noop` from `@ocavue/utils` instead of inline empty functions",
+			url: "https://github.com/ocavue/eslint-plugin-ocavue#prefer-noop"
+		},
+		messages: { preferNoop: "Use `noop` from `@ocavue/utils` instead of an inline empty function." },
+		schema: packageRuleSchema
+	},
+	create(context) {
+		if (!isPackageAvailable(context, "@ocavue/utils")) return {};
+		function check(node) {
+			if (getConstantFunctionValue(node) !== "undefined") return;
+			context.report({
+				node,
+				messageId: "preferNoop",
+				fix: createImportFix({
+					context,
+					node,
+					name: "noop",
+					packageName: UTILS_PACKAGE,
+					replace: (local) => local
+				})
+			});
+		}
+		return {
+			ArrowFunctionExpression: check,
+			FunctionExpression: check
+		};
+	}
+};
+//#endregion
+//#region src/rules/prefer-sleep.ts
+function isFunction(node) {
+	return node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression";
+}
+/**
+* Returns true when `name` refers to a global variable, not a local binding.
+*/
+function isGlobal(scope, name) {
+	const variable = findVariable(scope, name);
+	return !variable || variable.defs.length === 0;
+}
+/**
+* Returns the only expression that a function body evaluates, for bodies
+* such as `x`, `{ x }` and `{ return x }`.
+*/
+function getOnlyExpression(node) {
+	const body = node.body;
+	if (body.type !== "BlockStatement") return body;
+	if (body.body.length !== 1) return;
+	const statement = body.body[0];
+	if (statement.type === "ExpressionStatement") return statement.expression;
+	if (statement.type === "ReturnStatement" && statement.argument) return statement.argument;
+}
+function isIdentifier(node, name) {
+	return node.type === "Identifier" && node.name === name;
+}
+/**
+* Returns true for `setTimeout`, `globalThis.setTimeout` and
+* `window.setTimeout`.
+*/
+function isSetTimeout(node, scope) {
+	if (node.type === "Identifier") return node.name === "setTimeout" && isGlobal(scope, "setTimeout");
+	return node.type === "MemberExpression" && !node.computed && isIdentifier(node.property, "setTimeout") && node.object.type === "Identifier" && (node.object.name === "globalThis" || node.object.name === "window") && isGlobal(scope, node.object.name);
+}
+/**
+* Returns true for `resolve` and `() => resolve()`.
+*/
+function isResolveCallback(node, resolve) {
+	if (isIdentifier(node, resolve)) return true;
+	if (!isFunction(node) || node.async || node.generator || node.params.length > 0) return false;
+	const expression = getOnlyExpression(node);
+	return expression?.type === "CallExpression" && isIdentifier(expression.callee, resolve) && expression.arguments.length === 0;
+}
+/**
+* Returns true for no type argument, `<void>` and `<undefined>`.
+*/
+function hasVoidTypeArgument(node) {
+	const typeArguments = node.typeArguments;
+	if (!typeArguments) return true;
+	return typeArguments.params.length === 1 && (typeArguments.params[0].type === "TSVoidKeyword" || typeArguments.params[0].type === "TSUndefinedKeyword");
+}
 //#endregion
 //#region src/index.ts
 const plugin = {
 	meta: {
 		name: "eslint-plugin-ocavue",
-		version: "0.2.0"
+		version
 	},
 	rules: {
-		"no-implicit-arrow-linebreak": {
+		"no-implicit-arrow-linebreak": rule$4,
+		"prefer-constant-function": rule$3,
+		"prefer-noop": rule$2,
+		"prefer-sleep": {
 			meta: {
-				type: "layout",
+				type: "suggestion",
 				fixable: "code",
 				docs: {
-					description: "disallow a linebreak between `=>` and an implicit arrow function body, fixing it to a block body with `return`",
-					url: "https://github.com/ocavue/eslint-plugin-ocavue#no-implicit-arrow-linebreak"
+					description: "enforce `sleep` from `@ocavue/utils` instead of `new Promise` with `setTimeout`",
+					url: "https://github.com/ocavue/eslint-plugin-ocavue#prefer-sleep"
 				},
-				messages: { linebreak: "Implicit arrow body must not start on a new line. Use a block body with `return` instead." },
-				schema: []
+				messages: { preferSleep: "Use `sleep` from `@ocavue/utils` instead of `new Promise` with `setTimeout`." },
+				schema: packageRuleSchema
 			},
 			create(context) {
+				if (!isPackageAvailable(context, "@ocavue/utils")) return {};
 				const sourceCode = context.sourceCode;
-				return { ArrowFunctionExpression(node) {
-					if (node.body.type === "BlockStatement") return;
-					const arrowToken = sourceCode.getTokenBefore(node.body, { filter: (token) => token.type === "Punctuator" && token.value === "=>" });
-					if (!arrowToken) return;
-					const firstBodyToken = sourceCode.getTokenAfter(arrowToken);
-					const lastToken = sourceCode.getLastToken(node);
-					if (!firstBodyToken || !lastToken) return;
-					if (arrowToken.loc.end.line === firstBodyToken.loc.start.line) return;
-					const canFix = !sourceCode.commentsExistBetween(arrowToken, firstBodyToken);
+				/**
+				* Returns the delay expression of `new Promise((resolve) =>
+				* setTimeout(resolve, delay))`, or `undefined` when the node does not
+				* match.
+				*/
+				function getDelay(node) {
+					if (node.type !== "NewExpression" || !isIdentifier(node.callee, "Promise") || node.arguments.length !== 1 || !hasVoidTypeArgument(node)) return;
+					if (!isGlobal(sourceCode.getScope(node), "Promise")) return;
+					const executor = node.arguments[0];
+					if (!isFunction(executor) || executor.async || executor.generator) return;
+					if (!executor.params.every((param) => param.type === "Identifier")) return;
+					const resolveParam = executor.params[0];
+					if (resolveParam?.type !== "Identifier") return;
+					const call = getOnlyExpression(executor);
+					if (call?.type !== "CallExpression" || call.optional) return;
+					const executorScope = sourceCode.getScope(executor);
+					if (!isSetTimeout(call.callee, executorScope)) return;
+					const [callback, delay] = call.arguments;
+					if (call.arguments.length !== 2 || !delay || delay.type === "SpreadElement") return;
+					if (!isResolveCallback(callback, resolveParam.name)) return;
+					if (executorScope.variables.some((variable) => {
+						return variable.references.some((reference) => {
+							const range = reference.identifier.range;
+							return range[0] >= delay.range[0] && range[1] <= delay.range[1];
+						});
+					})) return;
+					if (executor.type === "FunctionExpression" && sourceCode.getTokens(delay).some((token) => {
+						return token.value === "this" || token.value === "arguments";
+					})) return;
+					return delay;
+				}
+				return { NewExpression(node) {
+					const delay = getDelay(node);
+					if (!delay) return;
+					const delayText = sourceCode.getText(delay);
 					context.report({
-						node: node.body,
-						messageId: "linebreak",
-						fix: canFix ? (fixer) => {
-							const bodyText = sourceCode.text.slice(firstBodyToken.range[0], lastToken.range[1]);
-							return fixer.replaceTextRange([arrowToken.range[1], lastToken.range[1]], ` { return ${bodyText} }`);
-						} : void 0
+						node,
+						messageId: "preferSleep",
+						fix: createImportFix({
+							context,
+							node,
+							name: "sleep",
+							packageName: UTILS_PACKAGE,
+							replace: (local) => {
+								return delay.type === "SequenceExpression" ? `${local}((${delayText}))` : `${local}(${delayText})`;
+							}
+						})
 					});
 				} };
 			}