eslint-node-test 0.0.1

package/rules/ast/is-member-expression.js

@@ -0,0 +1,98 @@
+/* eslint-disable complexity */
+/**
+@param {
+	{
+		property?: string,
+		properties?: string[],
+		object?: string,
+		objects?: string[],
+		optional?: boolean,
+		computed?: boolean
+	} | string | string[]
+} [options]
+@returns {string}
+*/
+export default function isMemberExpression(node, options) {
+	if (node?.type !== 'MemberExpression') {
+		return false;
+	}
+
+	if (typeof options === 'string') {
+		options = {properties: [options]};
+	}
+
+	if (Array.isArray(options)) {
+		options = {properties: options};
+	}
+
+	let {
+		property,
+		properties,
+		object,
+		objects,
+		optional,
+		computed,
+	} = {
+		property: '',
+		properties: [],
+		object: '',
+		...options,
+	};
+
+	if (property) {
+		properties = [property];
+	}
+
+	if (object) {
+		objects = [object];
+	}
+
+	if (
+		(optional === true && (node.optional !== optional))
+		|| (
+			optional === false
+			// `node.optional` can be `undefined` in some parsers
+			&& node.optional
+		)
+	) {
+		return false;
+	}
+
+	if (
+		Array.isArray(properties)
+		&& properties.length > 0
+	) {
+		if (
+			node.property.type !== 'Identifier'
+			|| !properties.includes(node.property.name)
+		) {
+			return false;
+		}
+
+		computed ??= false;
+	}
+
+	if (
+		(computed === true && (node.computed !== computed))
+		|| (
+			computed === false
+			// `node.computed` can be `undefined` in some parsers
+			&& node.computed
+		)
+	) {
+		return false;
+	}
+
+	if (
+		Array.isArray(objects)
+		&& objects.length > 0
+		&& (
+			node.object.type !== 'Identifier'
+			|| !objects.includes(node.object.name)
+		)
+	) {
+		return false;
+	}
+
+	return true;
+}

package/rules/ast/is-method-call.js

@@ -0,0 +1,62 @@
+import isMemberExpression from './is-member-expression.js';
+import {isCallExpression} from './call-or-new-expression.js';
+
+/**
+@param {
+	{
+		// `isCallExpression` options
+		argumentsLength?: number,
+		minimumArguments?: number,
+		maximumArguments?: number,
+		optionalCall?: boolean,
+		allowSpreadElement?: boolean,
+
+		// `isMemberExpression` options
+		method?: string,
+		methods?: string[],
+		object?: string,
+		objects?: string[],
+		optionalMember?: boolean,
+		computed?: boolean
+	} | string | string[]
+} [options]
+@returns {string}
+*/
+export default function isMethodCall(node, options) {
+	if (typeof options === 'string') {
+		options = {methods: [options]};
+	}
+
+	if (Array.isArray(options)) {
+		options = {methods: options};
+	}
+
+	const {
+		optionalCall,
+		optionalMember,
+		method,
+		methods,
+	} = {
+		method: '',
+		methods: [],
+		...options,
+	};
+
+	return (
+		isCallExpression(node, {
+			argumentsLength: options.argumentsLength,
+			minimumArguments: options.minimumArguments,
+			maximumArguments: options.maximumArguments,
+			allowSpreadElement: options.allowSpreadElement,
+			optional: optionalCall,
+		})
+		&& isMemberExpression(node.callee, {
+			object: options.object,
+			objects: options.objects,
+			computed: options.computed,
+			property: method,
+			properties: methods,
+			optional: optionalMember,
+		})
+	);
+}

package/rules/ast/literal.js

@@ -0,0 +1,32 @@
+export function isLiteral(node, value) {
+	if (node?.type !== 'Literal') {
+		return false;
+	}
+
+	return node.value === value;
+}
+
+const isStringLiteral = node => node?.type === 'Literal' && typeof node.value === 'string';
+
+// A node whose value is always a string: a string literal or any template literal.
+export const isStringExpression = node => isStringLiteral(node) || node?.type === 'TemplateLiteral';
+
+export const isBooleanLiteral = (node, value) =>
+	node?.type === 'Literal'
+	&& typeof node.value === 'boolean'
+	&& (value === undefined || node.value === value);
+
+export const getStaticStringValue = node => {
+	if (isStringLiteral(node)) {
+		return node.value;
+	}
+
+	if (
+		node?.type === 'TemplateLiteral'
+		&& node.expressions.length === 0
+	) {
+		return node.quasis[0].value.cooked;
+	}
+};
+
+export const isRegexLiteral = node => node.type === 'Literal' && Boolean(node.regex);

package/rules/ast/loop-types.js

@@ -0,0 +1,9 @@
+const loopTypes = [
+	'DoWhileStatement',
+	'ForInStatement',
+	'ForOfStatement',
+	'ForStatement',
+	'WhileStatement',
+];
+
+export default loopTypes;

package/rules/consistent-modifier-style.js

@@ -0,0 +1,95 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestOptions,
+	findOptionsProperty,
+	MODIFIERS,
+} from './utils/node-test.js';
+
+const MESSAGE_ID_PREFER_CHAINED = 'consistent-modifier-style/prefer-chained';
+const MESSAGE_ID_PREFER_OPTIONS = 'consistent-modifier-style/prefer-options';
+
+const messages = {
+	[MESSAGE_ID_PREFER_CHAINED]: 'Use the chained modifier `.{{modifier}}` instead of the `{{modifier}}` option.',
+	[MESSAGE_ID_PREFER_OPTIONS]: 'Use the `{{modifier}}` option instead of the chained `.{{modifier}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {style} = context.options[0];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		// Only tests and suites have `.only`/`.skip`/`.todo`; hooks have no chained modifier form.
+		if (parsed.kind === 'hook') {
+			return;
+		}
+
+		if (style === 'chained') {
+			// Flag modifiers expressed through the options object, but only `modifier: true`. A string
+			// reason (`{skip: 'why'}`), `false`, or a dynamic value has no equivalent chained form.
+			const options = getTestOptions(node);
+			const problems = [];
+			for (const modifier of MODIFIERS) {
+				const property = findOptionsProperty(options, modifier);
+				if (property?.value.type === 'Literal' && property.value.value === true) {
+					problems.push({
+						node: property,
+						messageId: MESSAGE_ID_PREFER_CHAINED,
+						data: {modifier},
+					});
+				}
+			}
+
+			return problems;
+		}
+
+		// `style === 'options'` — flag chained modifiers. `parsed.modifiers` includes any member
+		// after the test binding, so restrict to the real modifiers (`only`/`skip`/`todo`).
+		return parsed.modifiers
+			.filter(modifier => MODIFIERS.has(modifier.name))
+			.map(modifier => ({
+				node: modifier,
+				messageId: MESSAGE_ID_PREFER_OPTIONS,
+				data: {modifier: modifier.name},
+			}));
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent style for test modifiers.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					style: {
+						enum: ['chained', 'options'],
+						description: 'Whether modifiers should be chained (`test.skip()`) or passed as options (`{skip: true}`).',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{style: 'chained'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-context-name.js

@@ -0,0 +1,75 @@
+import {
+	resolveImports,
+	parseTestCall,
+	createContextTracker,
+	getTestCallback,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-context-name';
+
+const messages = {
+	[MESSAGE_ID]: 'Name the test context parameter `{{expected}}` instead of `{{actual}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const expected = context.options[0].name;
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		const isSubtest = tracker.isSubtestCall(node);
+		const isTest = parseTestCall(node, imports)?.kind === 'test';
+		tracker.update(node);
+
+		if (!isTest && !isSubtest) {
+			return;
+		}
+
+		const parameter = getTestCallback(node)?.params[0];
+		if (parameter?.type === 'Identifier' && parameter.name !== expected) {
+			return {
+				node: parameter,
+				messageId: MESSAGE_ID,
+				data: {expected, actual: parameter.name},
+			};
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent name for the test context parameter.',
+			recommended: 'unopinionated',
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					name: {
+						type: 'string',
+						description: 'The required name for the test context parameter.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{name: 't'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-filename.js

@@ -0,0 +1,70 @@
+import {resolveImports} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-filename';
+
+const messages = {
+	[MESSAGE_ID]: 'Test file name `{{name}}` does not match the required pattern `{{pattern}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const filename = context.physicalFilename ?? context.filename;
+	// No real file (for example, linting stdin), so there is nothing to check.
+	if (!filename || filename === '<input>' || filename === '<text>') {
+		return;
+	}
+
+	const {pattern} = context.options[0];
+
+	let patternRegExp;
+	try {
+		patternRegExp = new RegExp(pattern, 'v');
+	} catch (error) {
+		throw new Error(`Invalid \`pattern\` option for \`consistent-test-filename\`: ${error.message}`, {cause: error});
+	}
+
+	const name = filename.split(/[/\\]/).pop();
+	if (patternRegExp.test(name)) {
+		return;
+	}
+
+	context.on('Program', node => ({
+		node,
+		messageId: MESSAGE_ID,
+		data: {name, pattern},
+	}));
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent test file name pattern.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					pattern: {
+						type: 'string',
+						description: 'A regular expression the test file name must match.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{pattern: String.raw`\.test\.[cm]?[jt]sx?$`}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-it.js

@@ -0,0 +1,86 @@
+import {resolveImports, parseTestCall, createSuiteDepthTracker} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-it';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `{{expected}}` over `{{actual}}` {{location}}.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {fn: topLevelName, withinDescribe: withinDescribeName} = context.options[0];
+
+	const tracker = createSuiteDepthTracker();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		let problem;
+		if (parsed.kind === 'test') {
+			const inDescribe = tracker.depth > 0;
+			const expected = inDescribe ? withinDescribeName : topLevelName;
+			if (parsed.name !== expected) {
+				problem = {
+					node,
+					messageId: MESSAGE_ID,
+					data: {
+						expected,
+						actual: parsed.name,
+						location: inDescribe ? 'inside a `describe`' : 'at the top level',
+					},
+				};
+			}
+		}
+
+		if (parsed.kind === 'suite') {
+			tracker.enterSuite(node);
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.exitSuite(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce consistent use of `test` or `it`.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					fn: {
+						enum: ['test', 'it'],
+						description: 'The name to use for top-level test cases.',
+					},
+					withinDescribe: {
+						enum: ['test', 'it'],
+						description: 'The name to use for test cases inside a `describe`.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{fn: 'test', withinDescribe: 'it'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/fix/index.js

@@ -0,0 +1,5 @@
+export {default as removeArgument, getArgumentRemovalRange} from './remove-argument.js';
+export {
+	replaceMemberExpressionProperty,
+	removeMemberExpressionProperty,
+} from './replace-member-expression-property.js';

package/rules/fix/remove-argument.js

@@ -0,0 +1,58 @@
+import {isCommaToken} from '@eslint-community/eslint-utils';
+import {getParentheses} from '../utils/index.js';
+
+/**
+@import {TSESTree as ESTree} from '@typescript-eslint/types';
+@import * as ESLint from 'eslint';
+*/
+
+/**
+@param {ESTree.CallExpressionArgument} node
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {Array<number>}
+*/
+function getArgumentRemovalRange(node, context) {
+	const callOrNewExpression = node.parent;
+	const index = callOrNewExpression.arguments.indexOf(node);
+	const parentheses = getParentheses(node, context);
+	const firstToken = parentheses[0] || node;
+	const lastToken = parentheses.at(-1) || node;
+	const {sourceCode} = context;
+
+	let [start] = sourceCode.getRange(firstToken);
+	let [, end] = sourceCode.getRange(lastToken);
+
+	if (callOrNewExpression.arguments.length === 1) {
+		// The only argument: also drop a dangling trailing comma if present (`fn(a,)`).
+		const tokenAfter = sourceCode.getTokenAfter(lastToken);
+		if (isCommaToken(tokenAfter)) {
+			[, end] = sourceCode.getRange(tokenAfter);
+		}
+	} else if (index === 0) {
+		// First of several: remove it through the following comma and the gap after it, so
+		// `fn(a, b)` becomes `fn(b)` rather than `fn( b)`.
+		const commaToken = sourceCode.getTokenAfter(lastToken);
+		const nextArgumentToken = sourceCode.getTokenAfter(commaToken);
+		[end] = sourceCode.getRange(nextArgumentToken);
+	} else {
+		// Otherwise remove the comma that precedes it.
+		const commaToken = sourceCode.getTokenBefore(firstToken);
+		[start] = sourceCode.getRange(commaToken);
+	}
+
+	return [start, end];
+}
+
+/**
+@param {ESLint.Rule.RuleFixer} fixer
+@param {ESTree.CallExpressionArgument} node
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {ESLint.Rule.Fix}
+*/
+export default function removeArgument(fixer, node, context) {
+	return fixer.removeRange(getArgumentRemovalRange(node, context));
+}
+
+export {
+	getArgumentRemovalRange,
+};

package/rules/fix/replace-member-expression-property.js

@@ -0,0 +1,25 @@
+import {getParenthesizedRange} from '../utils/index.js';
+
+/**
+@import {TSESTree as ESTree} from '@typescript-eslint/types';
+@import * as ESLint from 'eslint';
+*/
+
+/**
+@param {ESTree.MemberExpression} memberExpression - The `MemberExpression` to fix.
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@param {string} text
+@returns {ESLint.Rule.ReportFixer}
+*/
+export function replaceMemberExpressionProperty(fixer, memberExpression, context, text) {
+	const [, start] = getParenthesizedRange(memberExpression.object, context);
+	const [, end] = context.sourceCode.getRange(memberExpression);
+	return fixer.replaceTextRange([start, end], text);
+}
+
+/**
+@param {ESTree.MemberExpression} memberExpression - The `MemberExpression` to fix.
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {ESLint.Rule.ReportFixer}
+*/
+export const removeMemberExpressionProperty = (fixer, memberExpression, context) => replaceMemberExpressionProperty(fixer, memberExpression, context, '');