@shivaedev/quality 0.29.1 → 0.31.0

package/src/rules/stories/unitSyntax.ts

@@ -0,0 +1,95 @@
+import ts from "typescript";
+
+export interface Stand {
+	readonly line: number;
+	readonly what: string;
+	readonly why: "mocks" | "provides";
+}
+
+const MOCKS: ReadonlySet<string> = new Set([
+	"doMock",
+	"fn",
+	"hoisted",
+	"importActual",
+	"importMock",
+	"mock",
+	"mocked",
+	"mockObject",
+	"setSystemTime",
+	"spyOn",
+	"stubEnv",
+	"stubGlobal",
+	"useFakeTimers",
+]);
+
+const VITEST: ReadonlySet<string> = new Set(["vitest", "@effect/vitest"]);
+
+const EFFECT_MODULE = /^effect\/(?<name>[A-Z]\w*)$/u;
+
+interface Name {
+	readonly module: string;
+	readonly path: readonly string[];
+}
+
+function bindingOf(module: string, imported: readonly string[]): Name {
+	const name = EFFECT_MODULE.exec(module)?.groups?.name;
+	return name === undefined ? { module, path: imported } : { module: "effect", path: [name, ...imported] };
+}
+
+function importsOf(source: ts.SourceFile): ReadonlyMap<string, Name> {
+	const bound = new Map<string, Name>();
+	for (const statement of source.statements) {
+		if (!(ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier))) {
+			continue;
+		}
+		const module = statement.moduleSpecifier.text;
+		const bindings = statement.importClause?.namedBindings;
+		if (bindings !== undefined && ts.isNamespaceImport(bindings)) {
+			bound.set(bindings.name.text, bindingOf(module, []));
+		}
+		for (const element of bindings !== undefined && ts.isNamedImports(bindings) ? bindings.elements : []) {
+			bound.set(element.name.text, bindingOf(module, [(element.propertyName ?? element.name).text]));
+		}
+	}
+	return bound;
+}
+
+function qualified(node: ts.Expression, bound: ReadonlyMap<string, Name>): Name | undefined {
+	if (ts.isIdentifier(node)) {
+		return bound.get(node.text) ?? (node.text === "vi" ? { module: "vitest", path: ["vi"] } : undefined);
+	}
+	const receiver = ts.isPropertyAccessExpression(node) ? qualified(node.expression, bound) : undefined;
+	return receiver === undefined || !ts.isPropertyAccessExpression(node) ? undefined : { ...receiver, path: [...receiver.path, node.name.text] };
+}
+
+function standOf({ module, path }: Name): Stand["why"] | undefined {
+	const [head = "", member = "", ...rest] = path;
+	if (rest.length > 0) {
+		return undefined;
+	}
+	if (VITEST.has(module) && head === "vi" && MOCKS.has(member)) {
+		return "mocks";
+	}
+	if (module === "@effect/vitest" && ((head === "layer" && member === "") || (head === "it" && member === "layer"))) {
+		return "provides";
+	}
+	const provides = (head === "Effect" && member.startsWith("provide")) || ((head === "Layer" || head === "ManagedRuntime") && member !== "");
+	return module === "effect" && provides ? "provides" : undefined;
+}
+
+export function standIns(source: ts.SourceFile): readonly Stand[] {
+	const bound = importsOf(source);
+	const found = new Map<string, Stand>();
+	function visit(node: ts.Node): void {
+		const called = ts.isIdentifier(node) && ts.isCallExpression(node.parent) && node.parent.expression === node;
+		const name = ts.isPropertyAccessExpression(node) || (called && ts.isIdentifier(node)) ? qualified(node, bound) : undefined;
+		const why = name === undefined ? undefined : standOf(name);
+		const key = name === undefined ? "" : `${name.module}#${name.path.join(".")}`;
+		if (why !== undefined && !found.has(key)) {
+			found.set(key, { line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1, what: node.getText(source), why });
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return [...found.values()];
+}

package/src/rules/stories/unitTests.ts

@@ -0,0 +1,86 @@
+import { labelOf, outgoing, type Reached, type Trail, walkFrom } from "#imports/fences/reach.ts";
+import type { ImportEdge, ImportGraph } from "#imports/graph.ts";
+import { packageNameOf } from "#imports/resolve.ts";
+import { isTestSupport } from "#naming/testName.ts";
+import type { Finding, SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+import { usesDom } from "#rules/test-names/usesDom.ts";
+import { engineOf } from "./engineOf.ts";
+import { type Stand, standIns } from "./unitSyntax.ts";
+
+const RELATIVE = /^[./#]/u;
+
+const KIT = "Drive the engine through the package's story kit in a story, or, if the code under test is pure,";
+
+function runtimeEdges(graph: ImportGraph): ReadonlyMap<string, readonly ImportEdge[]> {
+	const packages = graph.unresolved
+		.filter((request) => request.missing === undefined && !RELATIVE.test(request.specifier))
+		.map((request) => ({ ...request, to: { kind: "external" as const, package: packageNameOf(request.specifier), specifier: request.specifier } }));
+	return outgoing([...graph.edges, ...packages].filter((edge) => edge.kind === "import" && !edge.type));
+}
+
+function repair(path: readonly string[]): string {
+	const [, first, ...rest] = path;
+	if (first === undefined || rest.length === 0) {
+		return "remove that import from the .unit file.";
+	}
+	return isTestSupport(first)
+		? `give the .unit file fixtures from a test-support module that reaches no engine instead of ${first}.`
+		: `split ${first}: move the pure code under test into its own module that reaches no engine, and test that module in the .unit file.`;
+}
+
+function reachFinding(file: string, reached: Reached): Finding {
+	return {
+		file,
+		line: reached.line,
+		message: `Is a unit test but reaches ${engineOf(reached.target) ?? "an engine"} (${labelOf(reached.target)}) through ${reached.path.join(" -> ")}. A unit test reaches no engine, directly or through what it imports. ${KIT} ${repair(reached.path)}`,
+	};
+}
+
+function standMessage(stand: Stand): string {
+	return stand.why === "mocks"
+		? `mocks with ${stand.what}. A unit test calls real code with real values and stands nothing in for a collaborator.`
+		: `provides services with ${stand.what}. A unit test runs only requirement-free code, such as Effect.runSync on an Effect that needs nothing.`;
+}
+
+function where(file: string, module: string, trail: Trail): string {
+	return module === file ? "" : ` in ${module}, which it imports through ${trail.path.join(" -> ")},`;
+}
+
+function syntaxFindings(file: string, module: string, trail: Trail, source: SourceFile | undefined): readonly Finding[] {
+	const syntax = source === undefined ? undefined : parse(source);
+	if (source === undefined || syntax === undefined) {
+		return [];
+	}
+	function line(own: number): number {
+		return module === file ? own : trail.line;
+	}
+	const stands = standIns(syntax).map((stand) => ({
+		file,
+		line: line(stand.line),
+		message: `Is a unit test but${where(file, module, trail)} ${standMessage(stand)} ${KIT} test it in the .unit file without stand-ins.`,
+	}));
+	const dom = usesDom(source)
+		? [
+				{
+					file,
+					line: line(1),
+					message: `Is a unit test but${where(file, module, trail)} uses the DOM. A unit test runs without one. ${KIT} test it in the .unit file without the DOM.`,
+				},
+			]
+		: [];
+	return [...stands, ...dom];
+}
+
+export function unitTests(graph: ImportGraph, sources: readonly SourceFile[]): (file: string) => readonly Finding[] {
+	const edgesFrom = runtimeEdges(graph);
+	const byPath = new Map(sources.map((source) => [source.path, source]));
+	return (file) => {
+		const walked = walkFrom(file, edgesFrom, (endpoint) => engineOf(endpoint) !== undefined);
+		const checked = [...walked.visited].filter(([module]) => module === file || isTestSupport(module));
+		return [
+			...[...walked.reached].sort((a, b) => a.line - b.line).map((reached) => reachFinding(file, reached)),
+			...checked.flatMap(([module, trail]) => syntaxFindings(file, module, trail, byPath.get(module))),
+		];
+	};
+}

package/src/rules/test-names/colocated.ts

@@ -15,10 +15,11 @@ function findingOf(path: string): readonly Finding[] {
 	if (name === undefined || mirror === undefined) {
 		return [];
 	}
+	const modifiers = name.modifiers.map((modifier) => `.${modifier}`).join("");
 	return [
 		{
 			file: path,
-			message: `Sits in the test folder "${mirror}/". A test sits beside the file it covers, as ${name.stem}.test${name.extension} beside ${name.stem}.ts, or as a <behaviour>.spec${name.extension} in the folder it covers. A folder of tests that cover several packages is a suite in the "suites" option.`,
+			message: `Sits in the test folder "${mirror}/". A test sits beside the file it covers, as ${name.stem}${modifiers}.test${name.extension} beside ${name.stem}.ts, or as a <behaviour>${modifiers}.spec${name.extension} in the folder it covers. A folder of tests that cover several packages is a suite in the "suites" option.`,
 		},
 	];
 }

package/src/rules/test-names/follow.ts

@@ -13,7 +13,7 @@ const FIXTURE_SUFFIXES: ReadonlySet<string> = new Set(["integration", "postgres"
 const CODE = /\.[cm]?[jt]sx?$/u;
 
 const GRAMMAR =
-	"A test file is <file>[.<environment>].test.ts beside its file or <behaviour>[.<environment>].spec.ts in the folder it covers, with at most one environment of dom, slow and typecheck.";
+	"A test file is <file>[.<modifier>].test.ts beside its file or <behaviour>[.<modifier>].spec.ts in the folder it covers, with at most one modifier of dom, slow, typecheck and unit.";
 
 const TestsFollowOptions = Schema.Struct({
 	suites: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
@@ -28,6 +28,9 @@ function suffixMessage(file: string, name: TestName): string | undefined {
 	if (first === undefined || (rest.length === 0 && ENVIRONMENT_NAMES.has(first))) {
 		return undefined;
 	}
+	if (name.modifiers.includes("unit") && name.modifiers.includes("dom")) {
+		return `"${file}" is both a unit and a DOM test, but a unit test runs without the DOM. Drive the DOM through the package's story kit in ${name.stem}.dom.${name.kind}${name.extension}, or keep only pure code in ${name.stem}.unit.${name.kind}${name.extension}.`;
+	}
 	const fixture = name.modifiers.find((modifier) => FIXTURE_SUFFIXES.has(modifier));
 	if (fixture !== undefined) {
 		return `".${fixture}" is not a test environment. A test that needs a database or a running app takes it from the app's test fixture and is named like any other test. ${GRAMMAR}`;
@@ -35,24 +38,32 @@ function suffixMessage(file: string, name: TestName): string | undefined {
 	return `"${file}" has the suffixes ".${name.modifiers.join(".")}". ${GRAMMAR} An aspect of a module gets its own file in the module's folder, or a .spec.`;
 }
 
+function suffixOf(name: TestName): string {
+	const [only, ...rest] = name.modifiers;
+	return only !== undefined && rest.length === 0 && ENVIRONMENT_NAMES.has(only) ? `.${only}` : "";
+}
+
 function placeMessage(file: string, name: TestName, siblings: ReadonlySet<string>): string | undefined {
 	const covered = siblings.has(`${name.folder}/${name.stem}`);
+	const test = `${suffixOf(name)}.test${name.extension}`;
+	const spec = `checkoutFlow${suffixOf(name)}.spec${name.extension}`;
 	if (name.kind === "test") {
 		return covered
 			? undefined
-			: `"${file}" follows no file: ${name.stem}.test${name.extension} sits beside ${name.stem}.ts in the same folder. A test that covers the folder as a whole is a <behaviour>.spec${name.extension}, such as checkoutFlow.spec${name.extension}.`;
+			: `"${file}" follows no file: ${name.stem}${test} sits beside ${name.stem}.ts in the same folder. A test that covers the folder as a whole is a <behaviour>.spec${name.extension}, such as ${spec}.`;
 	}
 	if (covered) {
-		return `"${file}" shares its name with ${name.stem}.ts. A .spec names a behaviour of its folder, such as checkoutFlow.spec${name.extension}; a test of ${name.stem}.ts is ${name.stem}.test${name.extension}.`;
+		return `"${file}" shares its name with ${name.stem}.ts. A .spec names a behaviour of its folder, such as ${spec}; a test of ${name.stem}.ts is ${name.stem}${test}.`;
 	}
-	return CAMEL.test(name.stem) ? undefined : `"${file}" names its behaviour in camelCase, such as checkoutFlow.spec${name.extension}.`;
+	return CAMEL.test(name.stem) ? undefined : `"${file}" names its behaviour in camelCase, such as ${spec}.`;
 }
 
 function environmentMessage(file: string, name: TestName, source: SourceFile): string | undefined {
 	if (name.modifiers.includes("dom") || name.modifiers.includes("typecheck") || !usesDom(source)) {
 		return undefined;
 	}
-	return `"${file}" uses the DOM, so it is ${name.stem}.dom.${name.kind}${name.extension} and runs in the dom project.`;
+	const unit = name.modifiers.includes("unit") ? ", not a unit test, and drives the DOM through the package's story kit" : "";
+	return `"${file}" uses the DOM, so it is ${name.stem}.dom.${name.kind}${name.extension}${unit} and runs in the dom project.`;
 }
 
 function findingsOf(source: SourceFile, siblings: ReadonlySet<string>): readonly Finding[] {
@@ -72,7 +83,7 @@ export const testsFollow = defineRule({
 		return sources.filter((source) => !suites.ignores(source.path)).flatMap((source) => findingsOf(source, siblings));
 	},
 	description:
-		"A .test file follows the file beside it, a .spec names a behaviour of its folder, the only suffix is one environment of dom, slow and typecheck, and a test that uses the DOM is a .dom test.",
+		"A .test file follows the file beside it, a .spec names a behaviour of its folder, the only suffix is one modifier of dom, slow, typecheck and unit, and a test that uses the DOM is a .dom test.",
 	id: "tests/follow",
 	options: Schema.toStandardSchemaV1(TestsFollowOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
 });