@cjser/eslint-node-test 0.2.0-cjser.2

package/rules/prefer-equality-assertion.js

@@ -0,0 +1,124 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} from './utils/node-test.js';
+import {isParenthesized, getParenthesizedRange} from './utils/index.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID = 'prefer-equality-assertion';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `{{replacement}}` over `{{method}}` with a `{{operator}}` comparison for a clearer failure message.',
+};
+
+// Comparison operators and the assertion that preserves their semantics.
+const OPERATOR_TO_METHOD = new Map([
+	['===', 'strictEqual'],
+	['!==', 'notStrictEqual'],
+	['==', 'equal'],
+	['!=', 'notEqual'],
+]);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const parsed = parseAssertionCall(node, imports);
+		// Only the truthiness assertions (`assert(…)` / `assert.ok(…)`) benefit.
+		if (parsed?.method !== 'ok' || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		const [rawArgument] = node.arguments;
+		// Unwrap TypeScript casts (`(a === b) as boolean`) so the comparison is still recognized.
+		const argument = rawArgument && unwrapTypeScriptExpression(rawArgument);
+		if (argument?.type !== 'BinaryExpression') {
+			return;
+		}
+
+		if (
+			parsed.isStrict
+			&& (
+				argument.operator === '=='
+				|| argument.operator === '!='
+			)
+		) {
+			return;
+		}
+
+		const replacement = OPERATOR_TO_METHOD.get(argument.operator);
+		if (!replacement) {
+			return;
+		}
+
+		const {callee} = node;
+		const method = callee.type === 'MemberExpression' ? callee.property.name : 'ok';
+
+		const problem = {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method, replacement, operator: argument.operator},
+		};
+
+		// Skip the autofix when it would be unsafe: extra parentheses or a comment inside
+		// the comparison would be mangled by the rewrite, and a bare named import (`ok`)
+		// cannot be rewritten to an unimported `strictEqual`.
+		const isBareNamedImport = callee.type === 'Identifier' && !imports.assertNamespace.has(callee.name);
+		if (
+			isBareNamedImport
+			|| isParenthesized(argument, context)
+			|| sourceCode.getCommentsInside(argument).length > 0
+		) {
+			return problem;
+		}
+
+		problem.fix = function * (fixer) {
+			// `assert.ok(…)` / `t.assert.ok(…)` rewrite just the method, while the bare
+			// `assert(…)` namespace function becomes `assert.strictEqual(…)`.
+			yield callee.type === 'MemberExpression'
+				? fixer.replaceText(callee.property, replacement)
+				: fixer.replaceText(callee, `${callee.name}.${replacement}`);
+
+			// Split the comparison into two arguments: `left === right` -> `left, right`.
+			// Use the parenthesized ranges so parenthesized operands stay intact.
+			const leftEnd = getParenthesizedRange(argument.left, context)[1];
+			const rightStart = getParenthesizedRange(argument.right, context)[0];
+			yield fixer.replaceTextRange([leftEnd, rightStart], ', ');
+		};
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer an equality assertion over a truthiness assertion on a comparison.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-hooks-on-top.js

@@ -0,0 +1,75 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-hooks-on-top';
+
+const messages = {
+	[MESSAGE_ID]: 'Hook `{{name}}` should come before any test or `describe` in its scope.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Stack of scopes; each tracks whether a test/suite has appeared in it yet.
+	const scopeStack = [{seenTest: false}];
+	const pushedCalls = new Set();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		const scope = scopeStack.at(-1);
+
+		let problem;
+		if (parsed.kind === 'hook' && scope.seenTest) {
+			problem = {
+				node,
+				messageId: MESSAGE_ID,
+				data: {name: parsed.name},
+			};
+		}
+
+		if (parsed.kind === 'test' || parsed.kind === 'suite') {
+			scope.seenTest = true;
+
+			const callback = getTestCallback(node);
+			if (callback) {
+				scopeStack.push({seenTest: false});
+				pushedCalls.add(node);
+			}
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		if (!pushedCalls.has(node)) {
+			return;
+		}
+
+		pushedCalls.delete(node);
+		scopeStack.pop();
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require hooks to be declared before the tests in their scope.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-lowercase-title.js

@@ -0,0 +1,119 @@
+import {resolveImports, parseTestCall, getTestTitle} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-lowercase-title';
+
+const messages = {
+	[MESSAGE_ID]: 'Start the title with a lowercase letter.',
+};
+
+/** Get the static text at the start of a title node, or `undefined` if there is none. */
+const getLeadingText = node => {
+	if (node.type === 'Literal' && typeof node.value === 'string') {
+		return node.value;
+	}
+
+	// `` `text ${x}` `` — the text before the first expression. Empty if it starts with `${…}`.
+	if (node.type === 'TemplateLiteral') {
+		return node.quasis[0].value.cooked || undefined;
+	}
+
+	return undefined;
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {ignore, allowedPrefixes} = context.options[0];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'test' && parsed?.kind !== 'suite') {
+			return;
+		}
+
+		if (ignore.includes(parsed.name)) {
+			return;
+		}
+
+		const titleNode = getTestTitle(node, context);
+		if (!titleNode) {
+			return;
+		}
+
+		const leadingText = getLeadingText(titleNode);
+		if (!leadingText) {
+			return;
+		}
+
+		if (allowedPrefixes.some(prefix => leadingText.startsWith(prefix))) {
+			return;
+		}
+
+		const firstCharacter = leadingText[0];
+		if (!/\p{Uppercase_Letter}/u.test(firstCharacter)) {
+			return;
+		}
+
+		const problem = {
+			node: titleNode,
+			messageId: MESSAGE_ID,
+		};
+
+		// The first content character sits right after the opening quote/backtick.
+		const start = sourceCode.getRange(titleNode)[0] + 1;
+		// Skip the fix when the first character is written as a Unicode/hex escape, so the
+		// raw source does not start with the letter itself and replacing it would corrupt the escape.
+		if (sourceCode.getText(titleNode)[1] === firstCharacter) {
+			problem.fix = fixer => fixer.replaceTextRange([start, start + 1], firstCharacter.toLowerCase());
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce lowercase test titles.',
+			recommended: false,
+		},
+		fixable: 'code',
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					ignore: {
+						type: 'array',
+						items: {
+							enum: ['test', 'it', 'describe', 'suite'],
+						},
+						uniqueItems: true,
+						description: 'Test functions whose titles are not checked.',
+					},
+					allowedPrefixes: {
+						type: 'array',
+						items: {
+							type: 'string',
+						},
+						uniqueItems: true,
+						description: 'Title prefixes that are allowed to start with an uppercase letter.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ignore: [], allowedPrefixes: []}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-mock-method.js

@@ -0,0 +1,115 @@
+import {resolveImports, createContextTracker, isGlobalMock} from './utils/node-test.js';
+import {isValueNotUsable} from './utils/index.js';
+
+const MESSAGE_ID_ERROR = 'prefer-mock-method/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-mock-method/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Prefer `{{base}}.method()` over assigning `{{base}}.fn()` to a property, so the original method is tracked and can be restored.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{base}}.method()`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	// The context `<ctx>.mock`.
+	const isContextMock = node =>
+		node.type === 'MemberExpression'
+		&& !node.computed
+		&& node.property.type === 'Identifier'
+		&& node.property.name === 'mock'
+		&& node.object.type === 'Identifier'
+		&& tracker.isContextName(node.object.name);
+
+	// Keep the context-name stack in sync as we enter and leave test callbacks.
+	context.on('CallExpression', node => {
+		tracker.update(node);
+	});
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+
+	context.on('AssignmentExpression', node => {
+		if (node.operator !== '=' || node.left.type !== 'MemberExpression' || node.right.type !== 'CallExpression') {
+			return;
+		}
+
+		const {callee} = node.right;
+		if (
+			callee.type !== 'MemberExpression'
+			|| callee.computed
+			|| callee.property.type !== 'Identifier'
+			|| callee.property.name !== 'fn'
+			|| (!isGlobalMock(callee.object, imports) && !isContextMock(callee.object))
+		) {
+			return;
+		}
+
+		const base = sourceCode.getText(callee.object);
+		const problem = {
+			node,
+			messageId: MESSAGE_ID_ERROR,
+			data: {base},
+		};
+
+		const {left} = node;
+		const mockArguments = node.right.arguments;
+
+		// Resolve the property name to a `mock.method` second argument.
+		let key;
+		if (!left.computed && left.property.type === 'Identifier') {
+			key = `'${left.property.name}'`;
+		} else if (left.computed) {
+			key = sourceCode.getText(left.property);
+		}
+
+		// Only suggest a rewrite for the simple cases: a resolvable key, at most one argument (the
+		// implementation, which becomes `mock.method`'s third argument), and no inner comments to drop.
+		// `<obj>.method = mock.fn()` evaluates to the mock function, but `mock.method(…)` returns the
+		// original method, so skip the suggestion when the assignment's value is used.
+		const canRewrite = key !== undefined
+			&& mockArguments.length <= 1
+			&& isValueNotUsable(node)
+			&& sourceCode.getCommentsInside(node).length === 0;
+
+		if (canRewrite) {
+			const objectText = sourceCode.getText(left.object);
+			const implementation = mockArguments.length === 1 ? `, ${sourceCode.getText(mockArguments[0])}` : '';
+			const replacement = `${base}.method(${objectText}, ${key}${implementation})`;
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data: {base},
+					fix: fixer => fixer.replaceText(node, replacement),
+				},
+			];
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer `mock.method()` over assigning `mock.fn()` to an object property.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-strict-assert.js

@@ -0,0 +1,82 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-strict-assert';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `{{replacement}}` over the legacy loose `{{method}}`.',
+};
+
+// Legacy loose (`==`) assertion methods and their strict equivalents.
+const LOOSE_TO_STRICT = new Map([
+	['equal', 'strictEqual'],
+	['notEqual', 'notStrictEqual'],
+	['deepEqual', 'deepStrictEqual'],
+	['notDeepEqual', 'notDeepStrictEqual'],
+]);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const assertion = parseAssertionCall(node, imports);
+		// In a strict-mode assert module the legacy methods already behave strictly, so leave them.
+		if (!assertion || assertion.isStrict || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		const replacement = LOOSE_TO_STRICT.get(assertion.method);
+		if (!replacement) {
+			return;
+		}
+
+		const problem = {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: assertion.method, replacement},
+		};
+
+		// Autofix only the member forms (`assert.equal`, `t.assert.equal`). A bare named
+		// import (`equal`) cannot be rewritten to `strictEqual` without also importing it,
+		// so leave it reported but unfixed.
+		if (assertion.methodNode && assertion.methodNode !== node.callee) {
+			problem.fix = fixer => fixer.replaceText(assertion.methodNode, replacement);
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer strict assertion methods over their legacy loose counterparts.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-test-context-assert.js

@@ -0,0 +1,162 @@
+import {findVariable} from '@eslint-community/eslint-utils';
+import {
+	resolveImports,
+	createContextTracker,
+	parseAssertionCall,
+} from './utils/node-test.js';
+
+const MESSAGE_ID_ERROR = 'prefer-test-context-assert/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-test-context-assert/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Prefer the test context `{{context}}.assert.{{method}}()` over the imported `node:assert`, so the runner ties the assertion to this test.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{context}}.assert.{{method}}()`.',
+};
+
+// Under `node:assert/strict` these loose methods behave as their strict counterparts.
+// `t.assert.*` exposes the non-strict functions, so preserve the behavior when converting.
+const LOOSE_TO_STRICT = new Map([
+	['equal', 'strictEqual'],
+	['notEqual', 'notStrictEqual'],
+	['deepEqual', 'deepStrictEqual'],
+	['notDeepEqual', 'notDeepStrictEqual'],
+]);
+
+function isImportedAssertCallee(callee, imports) {
+	if (
+		callee.type === 'Identifier'
+		&& (
+			imports.assertNamed.has(callee.name)
+			|| imports.assertNamespace.has(callee.name)
+		)
+	) {
+		return true;
+	}
+
+	if (
+		callee.type === 'MemberExpression'
+		&& !callee.computed
+		&& callee.object.type === 'Identifier'
+		&& (
+			imports.assertNamespace.has(callee.object.name)
+			|| imports.assertNamed.get(callee.object.name) === 'strict'
+		)
+	) {
+		return true;
+	}
+
+	return (
+		callee.type === 'MemberExpression'
+		&& !callee.computed
+		&& callee.object.type === 'MemberExpression'
+		&& !callee.object.computed
+		&& callee.object.object.type === 'Identifier'
+		&& callee.object.property.type === 'Identifier'
+		&& callee.object.property.name === 'strict'
+		&& imports.assertNamespace.has(callee.object.object.name)
+	);
+}
+
+function getAssertMethod(node, imports) {
+	const assertion = parseAssertionCall(node, imports);
+	if (!assertion || !isImportedAssertCallee(node.callee, imports)) {
+		return;
+	}
+
+	return (assertion.isStrict && LOOSE_TO_STRICT.get(assertion.method)) || assertion.method;
+}
+
+function isInsideCallback(node, callback, sourceCode) {
+	const [callbackStart, callbackEnd] = sourceCode.getRange(callback);
+	const [nodeStart] = sourceCode.getRange(node);
+
+	return nodeStart >= callbackStart && nodeStart < callbackEnd;
+}
+
+function isContextParameterInScope(name, callback, node, sourceCode) {
+	const parameter = callback.params[0];
+	if (parameter?.type !== 'Identifier') {
+		return false;
+	}
+
+	const variable = findVariable(sourceCode.getScope(node), name);
+	return variable?.defs.some(definition => definition.name === parameter) === true;
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	// Needs both: an imported `node:assert` to convert from, and `node:test` to provide a context.
+	if (!imports.hasAssert || !imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const contextName = tracker.current();
+		if (!contextName) {
+			return;
+		}
+
+		const callback = tracker.currentCallback();
+		if (
+			!callback
+			|| !isInsideCallback(node, callback, sourceCode)
+			|| !isContextParameterInScope(contextName, callback, node, sourceCode)
+		) {
+			return;
+		}
+
+		const method = getAssertMethod(node, imports);
+		if (!method) {
+			return;
+		}
+
+		const data = {context: contextName, method};
+
+		const problem = {
+			node: node.callee,
+			messageId: MESSAGE_ID_ERROR,
+			data,
+		};
+
+		// Replacing the whole callee would drop any comments inside it.
+		if (sourceCode.getCommentsInside(node.callee).length === 0) {
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data,
+					fix: fixer => fixer.replaceText(node.callee, `${contextName}.assert.${method}`),
+				},
+			];
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer the test context `t.assert` over the imported `node:assert`.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;