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

package/rules/shared/test-modifier-rule.js

@@ -0,0 +1,92 @@
+import {
+	resolveImports,
+	parseTestCall,
+	findModifier,
+	getTestOptions,
+	findEnabledOptionsProperty,
+} from '../utils/node-test.js';
+
+/*
+Shared logic for rules that disallow a single test modifier (`only`/`skip`/`todo`).
+
+A modifier can be applied two ways in `node:test`:
+- As a chained property: `test.only(…)`.
+- As an options-object property: `test('title', {only: true}, () => {})`.
+*/
+
+/**
+@param {{
+	modifier: 'only' | 'skip' | 'todo',
+	description: string,
+	errorMessage: string,
+	recommended: 'unopinionated' | boolean,
+}} options
+@returns {import('eslint').Rule.RuleModule}
+*/
+export default function createTestModifierRule({modifier, description, errorMessage, recommended}) {
+	const MESSAGE_ID_ERROR = `no-${modifier}-test/error`;
+	const MESSAGE_ID_SUGGESTION = `no-${modifier}-test/suggestion`;
+	const messages = {
+		[MESSAGE_ID_ERROR]: errorMessage,
+		[MESSAGE_ID_SUGGESTION]: `Remove \`.${modifier}\`.`,
+	};
+
+	/** @param {import('eslint').Rule.RuleContext} context */
+	const create = context => {
+		const {sourceCode} = context;
+		const imports = resolveImports(context);
+		if (!imports.isTestFile) {
+			return;
+		}
+
+		context.on('CallExpression', node => {
+			const parsed = parseTestCall(node, imports);
+			if (!parsed) {
+				return;
+			}
+
+			const modifierNode = findModifier(parsed.modifiers, modifier);
+			if (modifierNode) {
+				return {
+					node: modifierNode,
+					messageId: MESSAGE_ID_ERROR,
+					suggest: [
+						{
+							messageId: MESSAGE_ID_SUGGESTION,
+							/** @param {import('eslint').Rule.RuleFixer} fixer */
+							fix(fixer) {
+								const dotToken = sourceCode.getTokenBefore(modifierNode);
+								return fixer.removeRange([sourceCode.getRange(dotToken)[0], sourceCode.getRange(modifierNode)[1]]);
+							},
+						},
+					],
+				};
+			}
+
+			const property = findEnabledOptionsProperty(getTestOptions(node), modifier);
+			if (property) {
+				return {
+					node: property,
+					messageId: MESSAGE_ID_ERROR,
+				};
+			}
+		});
+	};
+
+	return {
+		create,
+		meta: {
+			type: 'problem',
+			docs: {
+				description,
+				recommended,
+			},
+			hasSuggestions: true,
+			schema: [],
+			messages,
+			languages: [
+				'js/js',
+			],
+		},
+	};
+}

package/rules/test-title-format.js

@@ -0,0 +1,86 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestTitle,
+	getStaticString,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'test-title-format/mismatch';
+
+const messages = {
+	[MESSAGE_ID]: 'Test title does not match the required format: `{{format}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const formatOption = context.options[0]?.format;
+	if (!formatOption) {
+		return;
+	}
+
+	let titleRegExp;
+	try {
+		titleRegExp = new RegExp(formatOption, 'v');
+	} catch (error) {
+		throw new Error(`Invalid \`format\` option for \`test-title-format\`: ${error.message}`, {cause: error});
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed || parsed.kind === 'hook') {
+			return;
+		}
+
+		const titleNode = getTestTitle(node, context);
+		if (!titleNode) {
+			return;
+		}
+
+		const titleValue = getStaticString(titleNode, context);
+		if (titleValue === undefined) {
+			return;
+		}
+
+		if (!titleRegExp.test(titleValue)) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+				data: {format: String(titleRegExp)},
+			};
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require test titles to match a configured pattern.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					format: {
+						type: 'string',
+						description: 'A regular expression pattern that test titles must match.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/test-title.js

@@ -0,0 +1,139 @@
+import quoteJsString from '@cjser/quote-js-string';
+import {
+	resolveImports,
+	parseTestCall,
+	getTestTitle,
+	getTestCallback,
+} from './utils/node-test.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID_MISSING = 'test-title/missing';
+const MESSAGE_ID_NOT_STRING = 'test-title/not-string';
+const MESSAGE_ID_EMPTY = 'test-title/empty';
+const MESSAGE_ID_WHITESPACE = 'test-title/whitespace';
+
+const messages = {
+	[MESSAGE_ID_MISSING]: 'Test must have a title.',
+	[MESSAGE_ID_NOT_STRING]: 'Test title must be a string.',
+	[MESSAGE_ID_EMPTY]: 'Test title must not be empty.',
+	[MESSAGE_ID_WHITESPACE]: 'Test title must not have leading or trailing whitespace.',
+};
+
+/*
+Validate the resolved static title string of a `titleNode` (a string `Literal` or `TemplateLiteral`).
+Returns a problem for an empty or untrimmed title, or `undefined` when it is fine or not statically
+resolvable.
+*/
+function getStaticTitleProblem(titleNode) {
+	let titleValue;
+	if (titleNode.type === 'Literal') {
+		titleValue = titleNode.value;
+	} else if (titleNode.type === 'TemplateLiteral' && titleNode.expressions.length === 0) {
+		titleValue = titleNode.quasis[0].value.cooked;
+	} else {
+		// A template literal with expressions or some other dynamic node — can't validate.
+		return;
+	}
+
+	if (titleValue === null || titleValue === undefined) {
+		return;
+	}
+
+	if (titleValue.trim() === '') {
+		return {
+			node: titleNode,
+			messageId: MESSAGE_ID_EMPTY,
+		};
+	}
+
+	if (titleValue !== titleValue.trim()) {
+		const trimmed = titleValue.trim();
+		// Preserve the original string delimiter; a template literal (no expressions here) becomes
+		// a normal single-quoted string.
+		const quote = titleNode.type === 'Literal' ? titleNode.raw[0] : '\'';
+		return {
+			node: titleNode,
+			messageId: MESSAGE_ID_WHITESPACE,
+			fix: fixer => fixer.replaceText(titleNode, quoteJsString(trimmed, quote)),
+		};
+	}
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed || parsed.kind === 'hook') {
+			return;
+		}
+
+		const firstArgument = node.arguments[0];
+
+		// No arguments at all — truly empty call, skip.
+		if (!firstArgument) {
+			return;
+		}
+
+		// If the first argument is the implementation (callback), title is missing.
+		const callback = getTestCallback(node);
+		if (callback && callback === firstArgument) {
+			return {
+				node,
+				messageId: MESSAGE_ID_MISSING,
+			};
+		}
+
+		// First arg is an options object (possibly TypeScript-wrapped) with no preceding string title.
+		if (unwrapTypeScriptExpression(firstArgument).type === 'ObjectExpression') {
+			return {
+				node,
+				messageId: MESSAGE_ID_MISSING,
+			};
+		}
+
+		const titleNode = getTestTitle(node, context);
+
+		// First argument exists but is not a string (e.g. a number, boolean).
+		if (!titleNode) {
+			// If first argument is a function or identifier pointing to a fn, that's already handled above.
+			// For non-string literals (numbers, booleans, null), report.
+			if (
+				firstArgument.type === 'Literal'
+				&& typeof firstArgument.value !== 'string'
+			) {
+				return {
+					node: firstArgument,
+					messageId: MESSAGE_ID_NOT_STRING,
+				};
+			}
+
+			// Dynamic/computed title — can't validate statically, skip.
+			return;
+		}
+
+		return getStaticTitleProblem(titleNode);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require tests to have a title.',
+			recommended: true,
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/utils/contains-suspension-point.js

@@ -0,0 +1,35 @@
+import {isFunction} from '../ast/index.js';
+
+/**
+Check whether `node` or any of its descendants, excluding nested functions, is a suspension point (`await`, `for await…of`, or `yield`).
+
+Nested functions are not descended into, since their suspension points belong to a different function.
+
+@param {import('estree').Node} node
+@param {import('eslint').SourceCode['visitorKeys']} visitorKeys
+@returns {boolean}
+*/
+export default function containsSuspensionPoint(node, visitorKeys) {
+	if (
+		node.type === 'AwaitExpression'
+		|| node.type === 'YieldExpression'
+		|| (node.type === 'ForOfStatement' && node.await)
+	) {
+		return true;
+	}
+
+	if (isFunction(node)) {
+		return false;
+	}
+
+	for (const key of visitorKeys[node.type] ?? []) {
+		const child = node[key];
+		for (const childNode of Array.isArray(child) ? child : [child]) {
+			if (childNode?.type && containsSuspensionPoint(childNode, visitorKeys)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}

package/rules/utils/get-comments.js

@@ -0,0 +1,15 @@
+/**
+Get all comments in the file, regardless of language. JavaScript/TypeScript expose them via `sourceCode.getAllComments()`, while non-JavaScript languages (for example CSS via `@eslint/css`) expose them on `sourceCode.comments`. Some plugins like `@html-eslint` have `getAllComments()` but it returns `[]` — in that case we fall back to `sourceCode.comments`.
+
+@param {import('eslint').Rule.RuleContext} context
+@returns {Array<object>}
+*/
+export default function getComments(context) {
+	const {sourceCode} = context;
+	const fromGetAllComments = sourceCode.getAllComments?.();
+	if (fromGetAllComments?.length) {
+		return fromGetAllComments;
+	}
+
+	return sourceCode.comments ?? [];
+}

package/rules/utils/get-documentation-url.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import packageJson from '../../package.json' with {type: 'json'};
+
+const repoUrl = 'https://github.com/sindresorhus/eslint-node-test';
+
+export default function getDocumentationUrl(filename) {
+	const ruleName = path.basename(filename, '.js');
+	return `${repoUrl}/blob/v${packageJson.version}/docs/rules/${ruleName}.md`;
+}

package/rules/utils/get-enclosing-function.js

@@ -0,0 +1,18 @@
+import isFunction from '../ast/is-function.js';
+
+/**
+Walk up the ancestor chain to the nearest enclosing function node.
+Returns `undefined` if the program root is reached first.
+
+@param {import('estree').Node} node
+@returns {import('estree').Function | undefined}
+*/
+export default function getEnclosingFunction(node) {
+	for (let current = node.parent; current; current = current.parent) {
+		if (isFunction(current)) {
+			return current;
+		}
+	}
+
+	return undefined;
+}

package/rules/utils/index.js

@@ -0,0 +1,15 @@
+export {
+	isParenthesized,
+	getParentheses,
+	getParenthesizedRange,
+} from './parentheses/parentheses.js';
+
+export {default as containsSuspensionPoint} from './contains-suspension-point.js';
+export {default as getComments} from './get-comments.js';
+export {default as isPromiseType} from './is-promise-type.js';
+export {default as isSameReference} from './is-same-reference.js';
+export {default as isValueNotUsable} from './is-value-not-usable.js';
+export {default as unwrapTypeScriptExpression, isTypeScriptExpressionWrapper} from './unwrap-typescript-expression.js';
+export {isUnknownType} from './types.js';
+export {default as isConditionalBranch} from './is-conditional-branch.js';
+export {default as getEnclosingFunction} from './get-enclosing-function.js';

package/rules/utils/is-conditional-branch.js

@@ -0,0 +1,37 @@
+/*
+Whether `child` sits in a conditionally-executed branch of its parent `ancestor`, as opposed to the
+always-evaluated condition/test. Covers `if`/ternary (consequent or alternate), logical `&&`/`||`/`??`
+(the short-circuited right side), and `switch` (a case body). Pass `includeLoops` to also treat a
+loop body as conditional, since it may run zero times.
+*/
+export default function isConditionalBranch(ancestor, child, {includeLoops = false} = {}) {
+	switch (ancestor.type) {
+		case 'IfStatement':
+		case 'ConditionalExpression': {
+			// Only the consequent/alternate are conditional; the test always runs.
+			return child !== ancestor.test;
+		}
+
+		case 'LogicalExpression': {
+			// Only the right-hand side is conditional (it may be short-circuited).
+			return child === ancestor.right;
+		}
+
+		case 'SwitchCase': {
+			// The case body is conditional; the case's test expression is not.
+			return ancestor.consequent.includes(child);
+		}
+
+		case 'WhileStatement':
+		case 'DoWhileStatement':
+		case 'ForStatement':
+		case 'ForInStatement':
+		case 'ForOfStatement': {
+			return includeLoops && child === ancestor.body;
+		}
+
+		default: {
+			return false;
+		}
+	}
+}

package/rules/utils/is-promise-type.js

@@ -0,0 +1,26 @@
+import {isUnknownType} from './types.js';
+
+// Best-effort check whether a TypeScript type is a promise. Returns `true`/`false` when known, `undefined` when indeterminate.
+export default function isPromiseType(type, checker) {
+	type = checker.getNonNullableType(type);
+
+	if (isUnknownType(type)) {
+		return;
+	}
+
+	if (type.isUnion()) {
+		const results = type.types.map(type => isPromiseType(type, checker));
+
+		if (results.every(Boolean)) {
+			return true;
+		}
+
+		if (results.every(result => result === false)) {
+			return false;
+		}
+
+		return;
+	}
+
+	return checker.getPromisedTypeOfPromise(type) !== undefined;
+}

package/rules/utils/is-same-reference.js

@@ -0,0 +1,179 @@
+import {getStaticValue} from '@eslint-community/eslint-utils';
+
+// Copied from https://github.com/eslint/eslint/blob/94ba68d76a6940f68ff82eea7332c6505f93df76/lib/rules/utils/ast-utils.js#L392
+
+/**
+Gets the property name of a given node.
+The node can be a MemberExpression, a Property, or a MethodDefinition.
+
+If the name is dynamic, this returns `null`.
+
+For examples:
+
+	a.b		   // => "b"
+	a["b"]		// => "b"
+	a['b']		// => "b"
+	a[`b`]		// => "b"
+	a[100]		// => "100"
+	a[b]		  // => null
+	a["a" + "b"]  // => null
+	a[tag`b`]	 // => null
+	a[`${b}`]	 // => null
+
+	let a = {b: 1}			// => "b"
+	let a = {["b"]: 1}		// => "b"
+	let a = {['b']: 1}		// => "b"
+	let a = {[`b`]: 1}		// => "b"
+	let a = {[100]: 1}		// => "100"
+	let a = {[b]: 1}		  // => null
+	let a = {["a" + "b"]: 1}  // => null
+	let a = {[tag`b`]: 1}	 // => null
+	let a = {[`${b}`]: 1}	 // => null
+@param {ASTNode} node The node to get.
+@returns {string|undefined} The property name if static. Otherwise, undefined.
+*/
+function getStaticPropertyName(node) {
+	/* c8 ignore next 3 */
+	while (node?.type === 'ChainExpression') {
+		node = node.expression;
+	}
+
+	let property;
+
+	switch (node?.type) {
+		case 'MemberExpression': {
+			property = node.property;
+			break;
+		}
+
+		// Only reachable when use this to get class/object member key
+		/* c8 ignore next */
+		case 'Property':
+		case 'MethodDefinition': {
+			/* c8 ignore next 2 */
+			property = node.key;
+			break;
+		}
+
+			// No default
+	}
+
+	if (property) {
+		if (property.type === 'Identifier' && !node.computed) {
+			return property.name;
+		}
+
+		const staticResult = getStaticValue(property);
+		if (!staticResult) {
+			return;
+		}
+
+		return String(staticResult.value);
+	}
+}
+
+/**
+Check if two literal nodes are the same value.
+@param {ASTNode} left The Literal node to compare.
+@param {ASTNode} right The other Literal node to compare.
+@returns {boolean} `true` if the two literal nodes are the same value.
+*/
+function equalLiteralValue(left, right) {
+	// RegExp literal.
+	if (left.regex || right.regex) {
+		return Boolean(left.regex
+			&& right.regex
+			&& left.regex.pattern === right.regex.pattern
+			&& left.regex.flags === right.regex.flags);
+	}
+
+	// BigInt literal.
+	if (left.bigint || right.bigint) {
+		return left.bigint === right.bigint;
+	}
+
+	return left.value === right.value;
+}
+
+/**
+Unwrap ChainExpression (`?.`) and TypeScript expression wrapper (`as`, `satisfies`, `<Type>`, or `!`) nodes.
+@param {ASTNode} node The node to unwrap.
+@returns {ASTNode} The unwrapped node.
+*/
+function unwrapNode(node) {
+	while (
+		[
+			'ChainExpression',
+			'TSAsExpression',
+			'TSSatisfiesExpression',
+			'TSTypeAssertion',
+			'TSNonNullExpression',
+		].includes(node.type)
+	) {
+		node = node.expression;
+	}
+
+	return node;
+}
+
+/**
+Check if two expressions reference the same value. For example:
+	a = a
+	a.b = a.b
+	a[0] = a[0]
+	a['b'] = a['b']
+@param {ASTNode} left The left side of the comparison.
+@param {ASTNode} right The right side of the comparison.
+@returns {boolean} `true` if both sides match and reference the same value.
+*/
+export default function isSameReference(left, right) {
+	left = unwrapNode(left);
+	right = unwrapNode(right);
+
+	if (left.type !== right.type) {
+		return false;
+	}
+
+	switch (left.type) {
+		case 'Super':
+		case 'ThisExpression': {
+			return true;
+		}
+
+		case 'Identifier':
+		case 'PrivateIdentifier': {
+			return left.name === right.name;
+		}
+
+		case 'Literal': {
+			return equalLiteralValue(left, right);
+		}
+
+		case 'MemberExpression': {
+			const nameA = getStaticPropertyName(left);
+
+			// `x.y = x["y"]`
+			if (nameA !== undefined) {
+				return (
+					isSameReference(left.object, right.object)
+					&& nameA === getStaticPropertyName(right)
+				);
+			}
+
+			/*
+			`x[0] = x[0]`
+			`x[y] = x[y]`
+			`x.y = x.y`
+			*/
+			return (
+				left.computed === right.computed
+				&& isSameReference(left.object, right.object)
+				&& isSameReference(left.property, right.property)
+			);
+		}
+
+		default: {
+			return false;
+		}
+	}
+}

package/rules/utils/is-value-not-usable.js

@@ -0,0 +1,5 @@
+import {isExpressionStatement} from '../ast/index.js';
+
+export default function isValueNotUsable(node) {
+	return isExpressionStatement(node.parent);
+}