eslint-node-test 0.0.1

package/rules/rule/unicorn-listeners.js

@@ -0,0 +1,65 @@
+import toEslintListener from './to-eslint-listener.js';
+
+/**
+@import {EslintListers, ListenerType, Listener} from './to-eslint-create.js'
+*/
+
+class UnicornListeners {
+	#context;
+	#listeners = new Map();
+
+	constructor(context) {
+		this.#context = context;
+	}
+
+	#addEventListener(selectors, listener) {
+		const listeners = this.#listeners;
+		for (const selector of selectors) {
+			if (listeners.has(selector)) {
+				listeners.get(selector).push(listener);
+			} else {
+				listeners.set(selector, [listener]);
+			}
+		}
+	}
+
+	/**
+	@param {ListenerType | ListenerType[]} selectorOrSelectors
+	@param {Listener} listener
+	*/
+	on(selectorOrSelectors, listener) {
+		const selectors = Array.isArray(selectorOrSelectors) ? selectorOrSelectors : [selectorOrSelectors];
+		this.#addEventListener(selectors, listener);
+	}
+
+	/**
+	@param {ListenerType | ListenerType[]} selectorOrSelectors
+	@param {Listener} listener
+	*/
+	onExit(selectorOrSelectors, listener) {
+		const selectors = Array.isArray(selectorOrSelectors) ? selectorOrSelectors : [selectorOrSelectors];
+		this.#addEventListener(selectors.map(selector => `${selector}:exit`), listener);
+	}
+
+	/**
+	@returns {EslintListers}
+	*/
+	toEslintListeners() {
+		const eslintListeners = {};
+
+		for (const [selector, listeners] of this.#listeners) {
+			eslintListeners[selector] = toEslintListener(
+				this.#context,
+				function * (...listenerArguments) {
+					for (const listener of listeners) {
+						yield listener(...listenerArguments);
+					}
+				},
+			);
+		}
+
+		return eslintListeners;
+	}
+}
+
+export default UnicornListeners;

package/rules/rule/utilities.js

@@ -0,0 +1,26 @@
+const isIterable = object => typeof object?.[Symbol.iterator] === 'function';
+
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornReportFixer} from './to-eslint-rule-fixer.js';
+@import {UnicornProblems, UnicornProblem} from './to-eslint-problem.js';
+*/
+
+/**
+Iterate ESLint fix or ESLint problem
+
+@template {UnicornReportFixer | UnicornProblems} ValueType
+
+@param {ValueType} value
+@returns {IterableIterator<ValueType extends UnicornReportFixer ? ESLint.Rule.Fix : UnicornProblem>}
+*/
+export function * iterateFixOrProblems(value) {
+	if (!isIterable(value)) {
+		yield value;
+		return;
+	}
+
+	for (const element of value) {
+		yield * iterateFixOrProblems(element);
+	}
+}

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 {
+	resolveImports,
+	parseTestCall,
+	getTestTitle,
+	getTestCallback,
+} from './utils/node-test.js';
+import {escapeString} from './utils/index.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, escapeString(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/escape-string.js

@@ -0,0 +1,24 @@
+import jsesc from 'jsesc';
+
+/**
+Escape string and wrap the result in quotes.
+
+@param {string} string - The string to be quoted.
+@param {string} [quote] - The quote character.
+@returns {string} - The quoted and escaped string.
+*/
+export default function escapeString(string, quote = '\'') {
+	/* c8 ignore start */
+	if (typeof string !== 'string') {
+		throw new TypeError('Unexpected string.');
+	}
+	/* c8 ignore end */
+
+	return jsesc(string, {
+		quotes: quote === '"' ? 'double' : 'single',
+		wrap: true,
+		es6: true,
+		minimal: true,
+		lowercaseHex: 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,16 @@
+export {
+	isParenthesized,
+	getParentheses,
+	getParenthesizedRange,
+} from './parentheses/parentheses.js';
+
+export {default as containsSuspensionPoint} from './contains-suspension-point.js';
+export {default as escapeString} from './escape-string.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,28 @@
+import {isUnknownType} from './types.js';
+
+// Best-effort check whether a TypeScript type is a promise. Returns `true`/`false` when known, `undefined` when indeterminate.
+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;
+}
+
+export default isPromiseType;