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

package/rules/require-throws-expectation.js

@@ -0,0 +1,65 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'require-throws-expectation';
+
+const messages = {
+	[MESSAGE_ID]: '`{{method}}()` accepts any thrown value. Pass an error matcher (error class, `RegExp`, validation object, or function) as the second argument.',
+};
+
+const THROWS_METHODS = new Set(['throws', 'rejects']);
+
+/** @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 parsed = parseAssertionCall(node, imports);
+		if (!parsed || !THROWS_METHODS.has(parsed.method) || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		// Only the single-argument form lacks a matcher. A spread could expand to one.
+		if (node.arguments.length !== 1 || node.arguments[0].type === 'SpreadElement') {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: parsed.method},
+		};
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require an error matcher for `assert.throws()`/`assert.rejects()`.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/require-throws-validator-return-true.js

@@ -0,0 +1,156 @@
+import {getStaticValue} from '@eslint-community/eslint-utils';
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID = 'require-throws-validator-return-true';
+
+const messages = {
+	[MESSAGE_ID]: 'Validator function passed to `assert.{{method}}()` must return the boolean value `true`.',
+};
+
+const THROWS_METHODS = new Set(['throws', 'rejects']);
+const NON_TRUE_NODE_TYPES = new Set([
+	'ArrayExpression',
+	'ArrowFunctionExpression',
+	'ClassExpression',
+	'FunctionExpression',
+	'NewExpression',
+	'ObjectExpression',
+	'TemplateLiteral',
+]);
+
+function isAssertionCall(node, imports) {
+	node = unwrapTypeScriptExpression(node);
+	return node.type === 'CallExpression' && parseAssertionCall(node, imports) !== undefined;
+}
+
+function isPromiseStaticCall(node) {
+	return node.type === 'CallExpression'
+		&& node.callee.type === 'MemberExpression'
+		&& !node.callee.computed
+		&& node.callee.object.type === 'Identifier'
+		&& node.callee.object.name === 'Promise'
+		&& node.callee.property.type === 'Identifier';
+}
+
+function canReturnTrue(node, context, imports) {
+	if (!node) {
+		return false;
+	}
+
+	node = unwrapTypeScriptExpression(node);
+
+	if (isAssertionCall(node, imports)) {
+		return false;
+	}
+
+	if (isPromiseStaticCall(node)) {
+		return false;
+	}
+
+	const staticValue = getStaticValue(node, context.sourceCode.getScope(node));
+	if (staticValue) {
+		return staticValue.value === true;
+	}
+
+	// Any other expression (identifier, call, member access, conditional, …) could resolve to `true`.
+	return !NON_TRUE_NODE_TYPES.has(node.type);
+}
+
+function hasReturnTrue(functionBody, context, imports) {
+	function walk(node) {
+		if (node.type === 'ReturnStatement') {
+			return canReturnTrue(node.argument, context, imports);
+		}
+
+		if (node !== functionBody && isFunction(node)) {
+			return false;
+		}
+
+		for (const key of context.sourceCode.visitorKeys[node.type] ?? []) {
+			const child = node[key];
+			for (const childNode of Array.isArray(child) ? child : [child]) {
+				if (childNode?.type && walk(childNode)) {
+					return true;
+				}
+			}
+		}
+
+		return false;
+	}
+
+	return walk(functionBody);
+}
+
+function canValidatorReturnTrue(validator, context, imports) {
+	if (validator.async || validator.generator) {
+		return false;
+	}
+
+	if (validator.body.type !== 'BlockStatement') {
+		return canReturnTrue(validator.body, context, imports);
+	}
+
+	return hasReturnTrue(validator.body, context, imports);
+}
+
+/** @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 parsed = parseAssertionCall(node, imports);
+		if (!parsed || !THROWS_METHODS.has(parsed.method) || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		const validator = unwrapTypeScriptExpression(node.arguments[1]);
+		if (!validator || !isFunction(validator)) {
+			return;
+		}
+
+		if (canValidatorReturnTrue(validator, context, imports)) {
+			return;
+		}
+
+		return {
+			node: validator,
+			messageId: MESSAGE_ID,
+			data: {method: parsed.method},
+		};
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require validator functions in `assert.throws()`/`assert.rejects()` to return `true`.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/require-top-level-describe.js

@@ -0,0 +1,89 @@
+import {resolveImports, parseTestCall, createSuiteDepthTracker} from './utils/node-test.js';
+
+const MESSAGE_ID_NOT_WRAPPED = 'require-top-level-describe/not-wrapped';
+const MESSAGE_ID_TOO_MANY = 'require-top-level-describe/too-many';
+
+const messages = {
+	[MESSAGE_ID_NOT_WRAPPED]: 'A {{kind}} must be placed inside a top-level `describe`.',
+	[MESSAGE_ID_TOO_MANY]: 'There should be no more than {{max}} top-level `describe` blocks in a file.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const maxTopLevelDescribes = context.options[0]?.maxTopLevelDescribes;
+
+	const tracker = createSuiteDepthTracker();
+	let topLevelDescribeCount = 0;
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		let problem;
+		if (tracker.depth === 0) {
+			if (parsed.kind === 'test' || parsed.kind === 'hook') {
+				problem = {
+					node,
+					messageId: MESSAGE_ID_NOT_WRAPPED,
+					data: {kind: parsed.kind === 'hook' ? 'hook' : 'test'},
+				};
+			} else if (parsed.kind === 'suite') {
+				topLevelDescribeCount += 1;
+				if (maxTopLevelDescribes !== undefined && topLevelDescribeCount > maxTopLevelDescribes) {
+					problem = {
+						node,
+						messageId: MESSAGE_ID_TOO_MANY,
+						data: {max: maxTopLevelDescribes},
+					};
+				}
+			}
+		}
+
+		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: 'Require tests and hooks to be inside a top-level `describe`.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					maxTopLevelDescribes: {
+						type: 'integer',
+						minimum: 1,
+						description: 'The maximum number of top-level `describe` blocks allowed in a file.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/rule/index.js

@@ -0,0 +1,9 @@
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornCreate} from './to-eslint-create.js';
+@import {UnicornRule} from './to-eslint-rule.js';
+@import {UnicornContext} from './unicorn-context.js';
+@import {TSESTree as Estree} from '@typescript-eslint/types';
+*/
+
+export {default as toEslintRules} from './to-eslint-rules.js';

package/rules/rule/to-eslint-create.js

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import createUnicornContext from './unicorn-context.js';
+import UnicornListeners from './unicorn-listeners.js';
+
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornContext} from './unicorn-context.js';
+@import {EslintListers, ListenerType, EslintListener} from './to-eslint-listener.js'
+*/
+
+/**
+@typedef {ESLint.Rule.RuleModule['create']} EslintCreate
+@typedef {(context: UnicornContext) => void} UnicornCreate
+*/
+
+/**
+Convert Unicorn style of `create` to ESLint style
+
+@param {UnicornCreate} unicornCreate
+@returns {EslintCreate}
+*/
+export default function toEslintCreate(unicornCreate) {
+	return eslintContext => {
+		const unicornListeners = new UnicornListeners(eslintContext);
+		const unicornContext = createUnicornContext(eslintContext, unicornListeners);
+
+		const result = unicornCreate(unicornContext);
+
+		assert.equal(result, undefined, `[${eslintContext.id}] Rule \`create\` function should return \`undefined\`, please use \`context.on()\` instead of return listeners.`);
+
+		const eslintListeners = unicornListeners.toEslintListeners();
+
+		return eslintListeners;
+	};
+}

package/rules/rule/to-eslint-listener.js

@@ -0,0 +1,52 @@
+import toEslintProblem from './to-eslint-problem.js';
+
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornContext} from './unicorn-context.js'
+@import {UnicornProblems} from './to-eslint-problem.js'
+*/
+
+/**
+@typedef {ESLint.Rule.RuleListener} EslintListers
+@typedef {keyof EslintListers} ListenerType
+@typedef {EslintListers[ListenerType]} EslintListener
+@typedef {(...listenerArguments: Parameters<EslintListener>) => UnicornProblems} UnicornRuleListen
+*/
+
+/**
+Report a listener's return value: `undefined` (the common case), a single problem object, or an array/iterable of problems (possibly nested). Kept generator-free — this runs for every visited node of every rule, and the overwhelming majority of calls report nothing.
+
+@param {ESLint.Rule.RuleContext} context
+@param {UnicornProblems} problems
+*/
+function reportProblems(context, problems) {
+	if (!problems) {
+		return;
+	}
+
+	// A single problem object is a plain object (not iterable), so report it directly.
+	if (typeof problems[Symbol.iterator] !== 'function') {
+		context.report(toEslintProblem(problems));
+		return;
+	}
+
+	for (const problem of problems) {
+		reportProblems(context, problem);
+	}
+}
+
+/**
+@param {UnicornContext} context
+@param {UnicornRuleListen[]} listeners
+@returns {EslintListener}
+*/
+export default function toEslintListener(context, listeners) {
+	// Forward positional arguments explicitly instead of a rest array, since this runs for every
+	// visited node and a rest/spread would allocate on each call. ESLint passes at most three
+	// arguments to a listener (`onCodePathSegmentLoop`); node listeners get a single `node`.
+	return (argument0, argument1, argument2) => {
+		for (const listener of listeners) {
+			reportProblems(context, listener(argument0, argument1, argument2));
+		}
+	};
+}

package/rules/rule/to-eslint-problem.js

@@ -0,0 +1,36 @@
+import toEslintFixer from './to-eslint-rule-fixer.js';
+
+/**
+@import * as ESLint from 'eslint';
+*/
+
+/**
+@typedef {Parameters<ESLint.Rule.RuleContext['report']>[0]} EslintProblem
+@typedef {EslintProblem} UnicornProblem
+@typedef {EslintProblem | undefined | EslintProblem[] | IterableIterator<EslintProblem>} UnicornProblems
+*/
+
+/**
+@param {UnicornProblem} unicornProblem
+@returns {EslintProblem}
+*/
+export default function toEslintProblem(unicornProblem) {
+	const eslintProblem = {...unicornProblem};
+
+	if (unicornProblem.fix) {
+		eslintProblem.fix = toEslintFixer(unicornProblem.fix);
+	}
+
+	if (Array.isArray(unicornProblem.suggest)) {
+		eslintProblem.suggest = unicornProblem.suggest.map(unicornSuggest => ({
+			...unicornSuggest,
+			fix: toEslintFixer(unicornSuggest.fix),
+			data: {
+				...unicornProblem.data,
+				...unicornSuggest.data,
+			},
+		}));
+	}
+
+	return eslintProblem;
+}

package/rules/rule/to-eslint-rule-fixer.js

@@ -0,0 +1,47 @@
+import {iterateFixOrProblems} from './utilities.js';
+
+/**
+@import * as ESLint from 'eslint';
+*/
+
+class FixAbortError extends Error {
+	name = 'FixAbortError';
+}
+
+const fixOptions = {
+	abort() {
+		throw new FixAbortError('Fix aborted.');
+	},
+};
+
+/**
+@typedef {ESLint.Rule.ReportFixer | undefined} EslintReportFixer
+@typedef {EslintReportFixer | IterableIterator<EslintReportFixer>} UnicornReportFixer
+@typedef {(fixer: ESLint.Rule.RuleFixer, options: typeof fixOptions) => UnicornReportFixer} UnicornRuleFixer
+*/
+
+/**
+Convert Unicorn style fix function to ESLint style fix function
+
+@param {UnicornRuleFixer} fix
+@returns {ESLint.Rule.RuleFixer}
+*/
+export default function toEslintRuleFixer(fix) {
+	/** @param {UnicornReportFixer} fixer */
+	return fixer => {
+		const unicornReport = fix(fixer, fixOptions);
+
+		const eslintReport = iterateFixOrProblems(unicornReport);
+
+		try {
+			return [...eslintReport];
+		} catch (error) {
+			if (error instanceof FixAbortError) {
+				return;
+			}
+
+			/* c8 ignore next */
+			throw error;
+		}
+	};
+}

package/rules/rule/to-eslint-rule.js

@@ -0,0 +1,36 @@
+import getDocumentationUrl from '../utils/get-documentation-url.js';
+import toEslintCreate from './to-eslint-create.js';
+
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornCreate} from './to-eslint-create.js';
+*/
+
+/**
+@typedef {ESLint.Rule.RuleModule & {
+	create: UnicornCreate
+}} UnicornRule
+*/
+
+/**
+Convert Unicorn rule to ESLint rule
+
+@param {string} ruleId
+@param {UnicornRule} unicornRule
+@returns {ESLint.Rule.RuleModule}
+*/
+export default function toEslintRule(ruleId, unicornRule) {
+	return {
+		meta: {
+			// If there are no options, add `[]` so ESLint can validate that no data is passed to the rule.
+			// https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-schema.md
+			schema: [],
+			...unicornRule.meta,
+			docs: {
+				...unicornRule.meta.docs,
+				url: getDocumentationUrl(ruleId),
+			},
+		},
+		create: toEslintCreate(unicornRule.create),
+	};
+}

package/rules/rule/to-eslint-rules.js

@@ -0,0 +1,8 @@
+import toEslintRule from './to-eslint-rule.js';
+
+export default function toEslintRules(rules) {
+	return Object.fromEntries(Object.entries(rules).map(([ruleId, rule]) => [
+		ruleId,
+		toEslintRule(ruleId, rule),
+	]));
+}

package/rules/rule/unicorn-context.js

@@ -0,0 +1,34 @@
+/**
+@import * as ESLint from 'eslint';
+@import {UnicornListeners, ListenerType, Listener} from './to-eslint-create.js'
+*/
+
+/**
+@typedef {(type: ListenerType | ListenerType[], listener: Listener) => ReturnType<Listener>} UnicornRuleListen
+@typedef {ESLint.Rule.RuleContext & {
+	on: UnicornRuleListen
+	onExit: UnicornRuleListen
+}} UnicornContext
+*/
+
+/**
+Create a better `Context` object with `on` and `onExit` method to add listeners
+
+@param {ESLint.Rule.RuleContext} eslintContext
+@param {UnicornListeners} listeners
+@returns {UnicornContext}
+*/
+export default function createUnicornContext(eslintContext, listeners) {
+	/** @type {UnicornContext} */
+	const context = new Proxy(eslintContext, {
+		get(target, property, receiver) {
+			if (property === 'on' || property === 'onExit') {
+				return listeners[property].bind(listeners);
+			}
+
+			return Reflect.get(target, property, receiver);
+		},
+	});
+
+	return context;
+}

package/rules/rule/unicorn-listeners.js

@@ -0,0 +1,56 @@
+import toEslintListener from './to-eslint-listener.js';
+
+/**
+@import {EslintListers, ListenerType, Listener} from './to-eslint-create.js'
+*/
+
+export default 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, listeners);
+		}
+
+		return eslintListeners;
+	}
+}

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);
+	}
+}