@shivaedev/quality 0.36.0 → 0.39.0

package/src/rule.ts

@@ -1,4 +1,4 @@
-import type { Bivariant } from "@shivaedev/types/bivariant.ts";
+import type { Bivariant } from "@shivaedev/types/Bivariant.ts";
 import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { describeIssue, type StandardSchemaV1 } from "./standardSchema.ts";
 

package/src/rules/builtIn.ts

@@ -17,6 +17,7 @@ import { noTestCode } from "#rules/imports/noTestCode.ts";
 import { importsResolvable } from "#rules/imports/resolvable.ts";
 import { importsRuntime } from "#rules/imports/runtime.ts";
 import { authSql } from "#rules/stories/authSql.ts";
+import { storyEngine } from "#rules/stories/engine.ts";
 import { httpStatus } from "#rules/stories/httpStatus.ts";
 import { namedValues } from "#rules/stories/namedValues.ts";
 import { noExpect } from "#rules/stories/noExpect.ts";
@@ -75,6 +76,7 @@ export const builtInRules = [
 	testsColocated,
 	storySetup,
 	storySpecs,
+	storyEngine,
 	queueSql,
 	authSql,
 	noExpect,

package/src/rules/stories/engine.ts

@@ -0,0 +1,56 @@
+import ts from "typescript";
+import { importGraph } from "#imports/graph.ts";
+import { packageOf } from "#imports/workspace.ts";
+import { testName } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+import { storyOrigins } from "./origins.ts";
+import { storyPrerequisites } from "./prerequisites.ts";
+import { nodesWhere, unwrapped } from "./syntax.ts";
+import { storyUsesInputs } from "./usesInputs.ts";
+
+function ignoresEngine(call: ts.CallExpression, checker: ts.TypeChecker): boolean {
+	const traits = call.arguments[1];
+	const given = traits === undefined ? undefined : unwrapped(traits);
+	const body = call.arguments[2];
+	return (
+		given !== undefined
+		&& ts.isArrayLiteralExpression(given)
+		&& given.elements.length === 0
+		&& (body === undefined || storyUsesInputs(body, checker) === false)
+	);
+}
+
+export const storyEngine = defineRule({
+	check: async (inputs) => {
+		const graph = await importGraph(inputs);
+		const exempt = await storyPrerequisites(inputs, graph.packages);
+		const origins = storyOrigins(inputs, graph);
+		return inputs.sources.flatMap((file) => {
+			const name = testName(file.path);
+			const owner = packageOf(graph.packages, file.path);
+			if (
+				name === undefined
+				|| name.modifiers.some((modifier) => modifier === "unit" || modifier === "typecheck")
+				|| exempt.has(owner?.directory ?? "")
+			) {
+				return [];
+			}
+			const source = origins.source(file.path);
+			if (source === undefined) {
+				return [];
+			}
+			const stories = nodesWhere(
+				source,
+				(node) => ts.isCallExpression(node) && origins.origin(node.expression) === "story" && ignoresEngine(node, origins.checker),
+			);
+			return stories.map((story) => ({
+				file: file.path,
+				line: source.getLineAndCharacterOfPosition(story.getStart(source)).line + 1,
+				message: `Declares a story without traits whose body never references its verbs, its story or its test context. Drive the engine through one of the kit's verbs or traits. If the code under test is pure, move the test to ${name.stem}.unit.${name.kind}${name.extension}, which reaches no engine and mocks nothing. See https://github.com/ShivaeDev/platform/tree/main/packages/quality#story-tests.`,
+			}));
+		});
+	},
+	description:
+		"A story without traits references its kit's verbs, its story or its test context; pure tests belong in .unit files that reach no engine and mock nothing.",
+	id: "tests/story-engine",
+});

package/src/rules/stories/importOrigin.ts

@@ -0,0 +1,20 @@
+function moduleOrigin(from: string | undefined) {
+	if (from === "vitest" || from === "@effect/vitest") {
+		return "vitest";
+	}
+	return from === "@shivaedev/test-story" || from === "@shivaedev/test-story/server/storyKit.ts" ? "stories" : undefined;
+}
+
+export function importOrigin(from: string | undefined, name?: string) {
+	const namespace = moduleOrigin(from);
+	if (name === undefined) {
+		return namespace;
+	}
+	if (name === "storyKit" && namespace === "stories") {
+		return "factory";
+	}
+	if ((name === "describe" || name === "suite") && namespace === "vitest") {
+		return "suite";
+	}
+	return (name === "it" || name === "test") && namespace === "vitest" ? "plain" : undefined;
+}

package/src/rules/stories/namedValues.ts

@@ -1,15 +1,42 @@
 import ts from "typescript";
 import { defineRule } from "#rule.ts";
-import { isSpec, memberName, nodesWhere, numericValue, syntaxFindings } from "./syntax.ts";
+import { isSpec, memberName, nodesWhere, numericValue, syntaxFindings, unwrapped } from "./syntax.ts";
 
 const MESSAGE =
 	"Passes a numeric literal to toBe or toHaveLength. Assert the observed items, or give the expected value a domain name before asserting it.";
 
+function codeSubject(expression: ts.Expression): boolean {
+	const value = unwrapped(expression);
+	if (!(ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value))) {
+		return false;
+	}
+	let root = unwrapped(value.expression);
+	while ((ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root)) && memberName(root) === "not") {
+		root = unwrapped(root.expression);
+	}
+	if (!ts.isCallExpression(root)) {
+		return false;
+	}
+	const callee = unwrapped(root.expression);
+	const receiver = ts.isPropertyAccessExpression(callee) ? unwrapped(callee.expression) : callee;
+	const expect = ts.isIdentifier(receiver) && receiver.text === "expect" && (receiver === callee || memberName(callee) === "soft");
+	const argument = root.arguments[0];
+	if (!expect || argument === undefined) {
+		return false;
+	}
+	const subject = unwrapped(argument);
+	return ["status", "code", "exitCode"].includes(ts.isIdentifier(subject) ? subject.text : (memberName(subject) ?? ""));
+}
+
 function numericAssertion(node: ts.Node): boolean {
 	return (
 		ts.isCallExpression(node)
 		&& ["toBe", "toHaveLength"].includes(memberName(node.expression) ?? "")
-		&& node.arguments.some((argument) => numericValue(argument) !== undefined)
+		&& !codeSubject(node.expression)
+		&& node.arguments.some((argument) => {
+			const value = numericValue(argument);
+			return value !== undefined && value !== 0;
+		})
 	);
 }
 

package/src/rules/stories/noExpect.ts

@@ -1,6 +1,8 @@
 import ts from "typescript";
+import { importGraph } from "#imports/graph.ts";
 import { isTestSupport } from "#naming/testName.ts";
 import { defineRule } from "#rule.ts";
+import { registersTests } from "./registersTests.ts";
 import { memberName, nodesWhere, syntaxFindings, unwrapped } from "./syntax.ts";
 
 const MESSAGE =
@@ -33,7 +35,17 @@ function assertionsIn(source: ts.SourceFile): readonly ts.Node[] {
 }
 
 export const noExpect = defineRule({
-	check: ({ sources }) => sources.filter((file) => isTestSupport(file.path)).flatMap((file) => syntaxFindings(file, assertionsIn, MESSAGE)),
+	check: async (inputs) => {
+		const support = inputs.sources.filter((file) => isTestSupport(file.path));
+		if (support.length === 0) {
+			return [];
+		}
+		const graph = await importGraph(inputs);
+		const imported = new Set(graph.edges.flatMap((edge) => (edge.kind === "import" && edge.to.kind === "file" ? [edge.to.path] : [])));
+		return support.flatMap((file) =>
+			syntaxFindings(file, (source) => (!imported.has(file.path) && registersTests(source) ? [] : assertionsIn(source)), MESSAGE),
+		);
+	},
 	description: "Test-support performs actions and exposes observations; specs own expectations.",
 	id: "tests/no-expect-in-support",
 });

package/src/rules/stories/origins.ts

@@ -2,7 +2,9 @@ import { join } from "node:path";
 import ts from "typescript";
 import type { ImportGraph } from "#imports/graph.ts";
 import type { RuleInputs } from "#rule.ts";
+import { importOrigin } from "./importOrigin.ts";
 import { storyProgram } from "./program.ts";
+import { returnValues } from "./returnValues.ts";
 
 type Origin = "factory" | "kit" | "story" | "plain" | "suite" | "vitest" | "stories" | "function" | undefined;
 
@@ -15,24 +17,6 @@ function importFrom(node: ts.Node): string | undefined {
 	return undefined;
 }
 
-function moduleOrigin(from: string | undefined): Origin {
-	if (from === "vitest" || from === "@effect/vitest") {
-		return "vitest";
-	}
-	return from === "@shivaedev/test-story" || from === "@shivaedev/test-story/server/storyKit.ts" ? "stories" : undefined;
-}
-
-function imported(name: string, from: string | undefined): Origin {
-	const namespace = moduleOrigin(from);
-	if (name === "storyKit" && namespace === "stories") {
-		return "factory";
-	}
-	if ((name === "describe" || name === "suite") && namespace === "vitest") {
-		return "suite";
-	}
-	return (name === "it" || name === "test") && namespace === "vitest" ? "plain" : undefined;
-}
-
 export function storyOrigins(inputs: RuleInputs, graph: ImportGraph) {
 	const program = storyProgram(inputs, graph);
 	const checker = program.getTypeChecker();
@@ -50,10 +34,10 @@ export function storyOrigins(inputs: RuleInputs, graph: ImportGraph) {
 
 	function declaration(node: ts.Node): Origin {
 		if (ts.isImportSpecifier(node)) {
-			return imported((node.propertyName ?? node.name).text, importFrom(node));
+			return importOrigin(importFrom(node), (node.propertyName ?? node.name).text);
 		}
 		if (ts.isNamespaceImport(node)) {
-			return moduleOrigin(importFrom(node));
+			return importOrigin(importFrom(node));
 		}
 		if (ts.isVariableDeclaration(node) || ts.isPropertyAssignment(node)) {
 			return node.initializer === undefined ? undefined : origin(node.initializer);
@@ -97,7 +81,7 @@ export function storyOrigins(inputs: RuleInputs, graph: ImportGraph) {
 			return receiver;
 		}
 		const from = receiver === "vitest" ? "vitest" : undefined;
-		return imported(name, receiver === "stories" ? "@shivaedev/test-story/server/storyKit.ts" : from);
+		return importOrigin(receiver === "stories" ? "@shivaedev/test-story/server/storyKit.ts" : from, name);
 	}
 
 	function identifier(node: ts.Identifier): Origin {
@@ -118,13 +102,21 @@ export function storyOrigins(inputs: RuleInputs, graph: ImportGraph) {
 		return expression(node);
 	}
 
+	function call(node: ts.CallExpression): Origin {
+		const callee = visit(node.expression);
+		if (callee === "function") {
+			const values = returnValues(checker.getResolvedSignature(node)?.declaration);
+			return values.length > 0 && values.every((value) => value !== undefined && visit(value) === "kit") ? "kit" : callee;
+		}
+		return callee === "factory" ? "kit" : callee;
+	}
+
 	function expression(node: ts.Node): Origin {
 		if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
 			return visit(node.expression);
 		}
 		if (ts.isCallExpression(node)) {
-			const callee = visit(node.expression);
-			return callee === "factory" ? "kit" : callee;
+			return call(node);
 		}
 		if (ts.isPropertyAccessExpression(node)) {
 			return member(node.expression, node.name.text) ?? symbol(checker.getSymbolAtLocation(node.name));
@@ -143,5 +135,5 @@ export function storyOrigins(inputs: RuleInputs, graph: ImportGraph) {
 		return result;
 	}
 
-	return { origin: visit, source: (path: string) => program.getSourceFile(join(inputs.root, path)) };
+	return { checker, origin: visit, source: (path: string) => program.getSourceFile(join(inputs.root, path)) };
 }

package/src/rules/stories/registersTests.ts

@@ -0,0 +1,78 @@
+import ts from "typescript";
+import { memberName, unwrapped } from "./syntax.ts";
+
+function vitestBindings(source: ts.SourceFile): ReadonlyMap<string, string> {
+	const names = new Map<string, string>();
+	for (const statement of source.statements) {
+		if (
+			!(
+				ts.isImportDeclaration(statement)
+				&& ts.isStringLiteral(statement.moduleSpecifier)
+				&& ["vitest", "@effect/vitest"].includes(statement.moduleSpecifier.text)
+			)
+		) {
+			continue;
+		}
+		const bindings = statement.importClause?.namedBindings;
+		if (bindings !== undefined && ts.isNamedImports(bindings)) {
+			for (const element of bindings.elements) {
+				names.set(element.name.text, (element.propertyName ?? element.name).text);
+			}
+		} else if (bindings !== undefined) {
+			names.set(bindings.name.text, "namespace");
+		}
+	}
+	return names;
+}
+
+function localBindings(source: ts.SourceFile): ReadonlyMap<string, ts.Expression> {
+	const bindings = new Map<string, ts.Expression>();
+	for (const statement of source.statements) {
+		if (ts.isVariableStatement(statement)) {
+			for (const declaration of statement.declarationList.declarations) {
+				if (ts.isIdentifier(declaration.name) && declaration.initializer !== undefined) {
+					bindings.set(declaration.name.text, declaration.initializer);
+				}
+			}
+		}
+	}
+	return bindings;
+}
+
+export function registersTests(source: ts.SourceFile): boolean {
+	const bindings = localBindings(source);
+	const imports = vitestBindings(source);
+	function registrar(expression: ts.Expression, seen = new Set<string>()): boolean {
+		const node = unwrapped(expression);
+		if (ts.isIdentifier(node)) {
+			if (seen.has(node.text)) {
+				return false;
+			}
+			seen.add(node.text);
+			const binding = bindings.get(node.text);
+			return ["it", "test", "describe"].includes(imports.get(node.text) ?? node.text) || (binding !== undefined && registrar(binding, seen));
+		}
+		if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+			const name = memberName(node);
+			return (
+				name === "it"
+				|| (ts.isIdentifier(node.expression) && imports.get(node.expression.text) === "namespace" && (name === "test" || name === "describe"))
+				|| registrar(node.expression, seen)
+			);
+		}
+		return ts.isCallExpression(node) && registrar(node.expression, seen);
+	}
+	return source.statements.some((statement) => {
+		if (!ts.isExpressionStatement(statement)) {
+			return false;
+		}
+		const call = unwrapped(statement.expression);
+		const title = ts.isCallExpression(call) ? call.arguments[0] : undefined;
+		return (
+			ts.isCallExpression(call)
+			&& title !== undefined
+			&& (ts.isStringLiteralLike(title) || ts.isTemplateExpression(title))
+			&& registrar(call.expression)
+		);
+	});
+}

package/src/rules/stories/returnValues.ts

@@ -0,0 +1,24 @@
+import ts from "typescript";
+
+export function returnValues(declaration: ts.Signature["declaration"]): readonly (ts.Expression | undefined)[] {
+	const body = declaration !== undefined && "body" in declaration ? declaration.body : undefined;
+	if (body === undefined) {
+		return [];
+	}
+	if (!ts.isBlock(body)) {
+		return [body];
+	}
+	const values: (ts.Expression | undefined)[] = [];
+	function visit(node: ts.Node): void {
+		if (ts.isFunctionLike(node)) {
+			return;
+		}
+		if (ts.isReturnStatement(node)) {
+			values.push(node.expression);
+			return;
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(body);
+	return values;
+}

package/src/rules/stories/specs.ts

@@ -38,6 +38,9 @@ function testShaped(call: ts.CallExpression, origin: OriginOf): boolean {
 
 function declarationScope(node: ts.Node, origin: OriginOf): boolean {
 	for (let current = node.parent; current !== undefined; current = current.parent) {
+		if (ts.isCallExpression(current) && origin(current.expression) === "story") {
+			return false;
+		}
 		if (ts.isFunctionLike(current) && (!ts.isCallExpression(current.parent) || origin(current.parent.expression) !== "suite")) {
 			return false;
 		}

package/src/rules/stories/usesInputs.ts

@@ -0,0 +1,38 @@
+import ts from "typescript";
+
+export function storyUsesInputs(body: ts.Expression, checker: ts.TypeChecker): boolean | undefined {
+	const declaration = checker.getTypeAtLocation(body).getCallSignatures()[0]?.declaration;
+	if (declaration === undefined || !("body" in declaration) || declaration.body === undefined) {
+		return undefined;
+	}
+	const inputs = new Set<ts.Symbol>();
+	function bind(name: ts.BindingName): void {
+		if (ts.isIdentifier(name)) {
+			const symbol = checker.getSymbolAtLocation(name);
+			if (symbol !== undefined) {
+				inputs.add(symbol);
+			}
+		} else {
+			for (const element of name.elements) {
+				if (ts.isBindingElement(element)) {
+					bind(element.name);
+				}
+			}
+		}
+	}
+	for (const parameter of declaration.parameters.slice(0, 2)) {
+		bind(parameter.name);
+	}
+	function references(node: ts.Node): boolean {
+		if (ts.isIdentifier(node)) {
+			const symbol = ts.isShorthandPropertyAssignment(node.parent)
+				? checker.getShorthandAssignmentValueSymbol(node.parent)
+				: checker.getSymbolAtLocation(node);
+			if (symbol !== undefined && inputs.has(symbol)) {
+				return true;
+			}
+		}
+		return ts.forEachChild(node, references) ?? false;
+	}
+	return references(declaration.body);
+}

package/src/testProjects.ts

@@ -55,9 +55,22 @@ export function testProjects(options: TestProjectsOptions = {}): TestUserConfig
 						...(coverage === true ? {} : coverage),
 					},
 				}),
-		project: ["unit", "dom"],
+		project: ["unit", "pure", "dom"],
 		projects: [
-			{ extends: true, test: { environment: "node", exclude: excluding(named("dom"), named("slow")), include: [named()], name: "unit" } },
+			{
+				extends: true,
+				test: { environment: "node", exclude: excluding(named("dom"), named("slow"), named("unit")), include: [named()], name: "unit" },
+			},
+			{
+				extends: true,
+				test: {
+					environment: "node",
+					exclude: excluding(),
+					include: [named("unit")],
+					name: "pure",
+					setupFiles: [fileURLToPath(import.meta.resolve("#unitIoGuard.config.ts"))],
+				},
+			},
 			{
 				extends: true,
 				test: {

package/src/unitIoGuard.config.ts

@@ -0,0 +1,72 @@
+import { createRequire, syncBuiltinESMExports } from "node:module";
+// Materialize Node's lazy stdio exports before guarding Socket construction.
+import "node:process";
+
+const load = createRequire(import.meta.url);
+const installed = Symbol.for("@shivaedev/quality/unitIoGuard");
+let loading = 0;
+
+function assertUnitIoAllowed(call: string, boundary: (...args: never[]) => unknown): void {
+	const worker: { readonly filepath?: string } | undefined = Reflect.get(globalThis, "__vitest_worker__");
+	const file = worker?.filepath;
+	if (loading > 0 || file === undefined || !/\.unit\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(file)) {
+		return;
+	}
+	const error = new Error(`Unit test ${file} cannot call ${call}; use a story through the package's kit for I/O.`);
+	Error.captureStackTrace(error, boundary);
+	const caller = error.stack
+		?.split("\n")
+		.slice(1)
+		.find((line) => !/node:(?:fs|internal\/fs)/u.test(line));
+	// Node and Vitest still need to load the unit's modules; only their own immediate calls may pass.
+	if (caller !== undefined && /node:internal\/modules\/|\/node_modules\/(?:\.pnpm\/[^/]+\/node_modules\/)?(?:vitest|@vitest|vite)\//u.test(caller)) {
+		return;
+	}
+	throw error;
+}
+
+function runAllowed<T>(run: () => T): T {
+	loading += 1;
+	try {
+		return run();
+	} finally {
+		loading -= 1;
+	}
+}
+
+function guardModule(name: string): void {
+	const module: Record<string, unknown> = load(name);
+	for (const key of Object.keys(module)) {
+		const original = module[key];
+		if (typeof original !== "function") {
+			continue;
+		}
+		const apply: NonNullable<ProxyHandler<typeof original>["apply"]> = (target, receiver, args) => {
+			assertUnitIoAllowed(`${name}.${key}`, apply);
+			return runAllowed(() => Reflect.apply(target, receiver, args));
+		};
+		const construct: NonNullable<ProxyHandler<typeof original>["construct"]> = (target, args, newTarget) => {
+			assertUnitIoAllowed(`${name}.${key}`, construct);
+			return runAllowed(() => Reflect.construct(target, args, newTarget));
+		};
+		Object.defineProperty(module, key, {
+			configurable: true,
+			enumerable: true,
+			value: new Proxy(original, { apply, construct }),
+			writable: true,
+		});
+	}
+}
+
+if (Reflect.get(globalThis, installed) !== true) {
+	Reflect.set(globalThis, installed, true);
+	for (const name of ["node:fs", "node:fs/promises", "node:net", "node:http", "node:https", "node:child_process", "node:worker_threads"]) {
+		guardModule(name);
+	}
+	const fetch = globalThis.fetch;
+	globalThis.fetch = function unitIoFetch(...args) {
+		assertUnitIoAllowed("fetch", unitIoFetch);
+		return fetch(...args);
+	};
+	syncBuiltinESMExports();
+}