@shivaedev/quality 0.27.1 → 0.28.1

package/src/rules/stories/noExpect.ts

@@ -0,0 +1,39 @@
+import ts from "typescript";
+import { isTestSupport } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+import { memberName, nodesWhere, syntaxFindings, unwrapped } from "./syntax.ts";
+
+const MESSAGE =
+	"Calls expect in test-support. Return the engine's observed state from the verb and put the expectation in the spec; throw if an action cannot run.";
+
+function assertionReference(expression: ts.Expression, names: ReadonlySet<string>): boolean {
+	const node = unwrapped(expression);
+	if (ts.isIdentifier(node)) {
+		return names.has(node.text);
+	}
+	return (
+		memberName(node) === "expect"
+		|| ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) && assertionReference(node.expression, names))
+	);
+}
+
+function assertionsIn(source: ts.SourceFile): readonly ts.Node[] {
+	const names = new Set(["expect"]);
+	for (const statement of source.statements) {
+		const bindings = ts.isImportDeclaration(statement) ? statement.importClause?.namedBindings : undefined;
+		if (bindings !== undefined && ts.isNamedImports(bindings)) {
+			for (const element of bindings.elements) {
+				if ((element.propertyName ?? element.name).text === "expect") {
+					names.add(element.name.text);
+				}
+			}
+		}
+	}
+	return nodesWhere(source, (node) => ts.isCallExpression(node) && assertionReference(node.expression, names));
+}
+
+export const noExpect = defineRule({
+	check: ({ sources }) => sources.filter((file) => isTestSupport(file.path)).flatMap((file) => syntaxFindings(file, assertionsIn, MESSAGE)),
+	description: "Test-support performs actions and exposes observations; specs own expectations.",
+	id: "tests/no-expect-in-support",
+});

package/src/rules/stories/noLimitImports.ts

@@ -0,0 +1,80 @@
+import ts from "typescript";
+import { defineRule } from "#rule.ts";
+import { isSpec, memberName, nodesWhere, syntaxFindings, unwrapped } from "./syntax.ts";
+
+const MESSAGE =
+	"Imports a MAX_* constant from a limits module. Tell a story about the observed behavior instead of asserting a copy of the implementation's cap.";
+
+const LIMITS_MODULE = /(?:^|[/#])limits(?:\.[cm]?[jt]s)?(?:\/|$)/u;
+const MAX_CONSTANT = /^MAX_/u;
+
+function literalLimitsImport(expression: ts.Expression): boolean {
+	const node = unwrapped(expression);
+	if (ts.isAwaitExpression(node)) {
+		return literalLimitsImport(node.expression);
+	}
+	return (
+		ts.isCallExpression(node)
+		&& node.expression.kind === ts.SyntaxKind.ImportKeyword
+		&& node.arguments[0] !== undefined
+		&& ts.isStringLiteralLike(node.arguments[0])
+		&& LIMITS_MODULE.test(node.arguments[0].text)
+	);
+}
+
+function capBinding(binding: ts.BindingElement): boolean {
+	if (binding.dotDotDotToken !== undefined) {
+		return false;
+	}
+	const name = binding.propertyName ?? binding.name;
+	if (ts.isComputedPropertyName(name)) {
+		return ts.isStringLiteralLike(name.expression) && MAX_CONSTANT.test(name.expression.text);
+	}
+	return (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) && MAX_CONSTANT.test(name.text);
+}
+
+function capImports(source: ts.SourceFile): readonly ts.Node[] {
+	const namespaces = new Set<string>();
+	const imports = source.statements.flatMap((statement) => {
+		if (
+			!(ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier) && LIMITS_MODULE.test(statement.moduleSpecifier.text))
+		) {
+			return [];
+		}
+		const bindings = statement.importClause?.namedBindings;
+		if (bindings !== undefined && ts.isNamespaceImport(bindings)) {
+			namespaces.add(bindings.name.text);
+		}
+		return bindings !== undefined && ts.isNamedImports(bindings)
+			? bindings.elements.filter((element) => MAX_CONSTANT.test((element.propertyName ?? element.name).text))
+			: [];
+	});
+	const dynamic = nodesWhere(source, ts.isVariableDeclaration).flatMap<ts.Node>((node) => {
+		if (!ts.isVariableDeclaration(node) || node.initializer === undefined || !literalLimitsImport(node.initializer)) {
+			return [];
+		}
+		if (ts.isIdentifier(node.name)) {
+			namespaces.add(node.name.text);
+			return [];
+		}
+		return ts.isObjectBindingPattern(node.name) ? node.name.elements.filter(capBinding) : [];
+	});
+	return [
+		...imports,
+		...dynamic,
+		...nodesWhere(
+			source,
+			(node) =>
+				(ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node))
+				&& ts.isIdentifier(node.expression)
+				&& namespaces.has(node.expression.text)
+				&& MAX_CONSTANT.test(memberName(node) ?? ""),
+		),
+	];
+}
+
+export const noLimitImports = defineRule({
+	check: ({ sources }) => sources.filter((file) => isSpec(file.path)).flatMap((file) => syntaxFindings(file, capImports, MESSAGE)),
+	description: "Stories prove behavior instead of importing implementation caps from limits modules.",
+	id: "tests/no-limit-imports",
+});

package/src/rules/stories/queueSql.ts

@@ -0,0 +1,18 @@
+import { defineRule } from "#rule.ts";
+import { sqlTexts } from "./sqlText.ts";
+
+const QUEUE_SCHEMA = /\bpgboss\b"?\s*\./iu;
+
+export const queueSql = defineRule({
+	check: async (inputs) =>
+		(await sqlTexts(inputs))
+			.filter((query) => QUEUE_SCHEMA.test(query.text))
+			.map((query) => ({
+				file: query.file,
+				line: query.line,
+				message:
+					"SQL mentions pgboss. Use the app's public queue definitions and let workers process jobs; apps never edit or purge queue tables, and there is no queue-purge API by design.",
+			})),
+	description: "Apps never read, edit or purge pg-boss's private queue schema.",
+	id: "boundaries/queue-sql",
+});

package/src/rules/stories/specHelpers.ts

@@ -0,0 +1,10 @@
+import { defineRule } from "#rule.ts";
+import { isSpec, syntaxFindings, topLevelHelpers } from "./syntax.ts";
+
+const MESSAGE = "Declares a top-level helper in a spec. Move the action into the story kit's verbs or the setup into its traits in test-support/.";
+
+export const specHelpers = defineRule({
+	check: ({ sources }) => sources.filter((file) => isSpec(file.path)).flatMap((file) => syntaxFindings(file, topLevelHelpers, MESSAGE)),
+	description: "Specs state expectations; story-kit traits and verbs in test-support own helpers.",
+	id: "tests/spec-helpers",
+});

package/src/rules/stories/sqlText.ts

@@ -0,0 +1,100 @@
+import ts from "typescript";
+import type { RuleInputs } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+import { unwrapped } from "./syntax.ts";
+
+export interface SqlText {
+	readonly file: string;
+	readonly line: number;
+	readonly text: string;
+}
+
+const SQL_START =
+	/^\s*(?:(?:--[^\n]*\n|\/\*[\s\S]*?\*\/)\s*)*(?:select|with|insert|update|delete|truncate|alter|drop|create|grant|revoke|comment)\b/iu;
+const SQL_CALLEE = /^(?:sql|query|execute|exec|raw)(?:\.|$)|\.(?:sql|unsafe|query|execute|exec|raw)$/iu;
+
+function interpolation(node: ts.Expression): string {
+	if (ts.isStringLiteralLike(node)) {
+		return node.text;
+	}
+	return ts.isCallExpression(node) && node.arguments.every(ts.isStringLiteralLike)
+		? node.arguments
+				.filter(ts.isStringLiteralLike)
+				.map((argument) => argument.text)
+				.join(".")
+		: " ? ";
+}
+
+function templateText(node: ts.TemplateLiteral): string {
+	return ts.isNoSubstitutionTemplateLiteral(node)
+		? node.text
+		: node.head.text + node.templateSpans.map((span) => interpolation(span.expression) + span.literal.text).join("");
+}
+
+function textOf(expression: ts.Expression): string | undefined {
+	const node = unwrapped(expression);
+	if (ts.isStringLiteralLike(node)) {
+		return node.text;
+	}
+	if (ts.isTemplateExpression(node)) {
+		return templateText(node);
+	}
+	if (ts.isObjectLiteralExpression(node)) {
+		const query = node.properties.find((property) => ts.isPropertyAssignment(property) && property.name.getText() === "text");
+		return query !== undefined && ts.isPropertyAssignment(query) ? textOf(query.initializer) : undefined;
+	}
+	if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+		return `${textOf(node.left) ?? " ? "}${textOf(node.right) ?? " ? "}`;
+	}
+	return undefined;
+}
+
+function queryAt(node: ts.Node, source: ts.SourceFile): string | undefined {
+	let text: string | undefined;
+	let explicit = false;
+	if (ts.isTaggedTemplateExpression(node)) {
+		text = templateText(node.template);
+		explicit = SQL_CALLEE.test(node.tag.getText(source));
+	} else if (ts.isCallExpression(node)) {
+		text = node.arguments[0] === undefined ? undefined : textOf(node.arguments[0]);
+		explicit = SQL_CALLEE.test(node.expression.getText(source));
+	} else if (ts.isVariableDeclaration(node) && node.initializer !== undefined) {
+		text = textOf(node.initializer);
+	}
+	return text !== undefined && (explicit || SQL_START.test(text)) ? text : undefined;
+}
+
+function queriesIn(file: string, source: ts.SourceFile): readonly SqlText[] {
+	const queries: SqlText[] = [];
+	function visit(node: ts.Node): void {
+		const text = queryAt(node, source);
+		if (text !== undefined) {
+			queries.push({ file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1, text });
+			return;
+		}
+		if (!ts.isTaggedTemplateExpression(node)) {
+			ts.forEachChild(node, visit);
+		}
+	}
+	visit(source);
+	return queries;
+}
+
+export async function sqlTexts(inputs: RuleInputs): Promise<readonly SqlText[]> {
+	const code = inputs.sources.flatMap((file) => {
+		const source = parse(file);
+		return source === undefined ? [] : queriesIn(file.path, source);
+	});
+	const sql = await Promise.all(
+		inputs.files
+			.filter((file) => file.endsWith(".sql"))
+			.map(async (file) => {
+				const text = inputs.sources.find((source) => source.path === file)?.text ?? (await inputs.readText(file));
+				if (text === undefined) {
+					throw new Error(`Cannot read SQL file ${file}. Restore the file or repair its read permissions.`);
+				}
+				return { file, line: 1, text };
+			}),
+	);
+	return [...code, ...sql];
+}

package/src/rules/stories/supportImports.ts

@@ -0,0 +1,31 @@
+import { Effect, Schema } from "effect";
+import { importGraph } from "#imports/graph.ts";
+import { isTestSupport } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+import { matchesAny } from "./matchesAny.ts";
+
+const SupportImportsOptions = Schema.Struct({
+	modules: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+});
+
+export const supportImports = defineRule({
+	check: async ({ options, ...inputs }) => {
+		if (!inputs.sources.some((file) => isTestSupport(file.path))) {
+			return [];
+		}
+		const graph = await importGraph(inputs);
+		return graph.edges
+			.filter(
+				(edge) => isTestSupport(edge.from) && edge.to.kind === "file" && !isTestSupport(edge.to.path) && !matchesAny(edge.to.path, options.modules),
+			)
+			.map((edge) => ({
+				file: edge.from,
+				line: edge.line,
+				message: `Test-support imports "${edge.specifier}" outside its allowed public surface. Drive the app through its host, schemas or queue definitions; list those public module paths in tests/support-imports.options.modules in the repository's quality config.`,
+				subject: edge.specifier,
+			}));
+	},
+	description: "Test-support reaches repository modules only through the public surface named by the repository's module allowlist.",
+	id: "tests/support-imports",
+	options: Schema.toStandardSchemaV1(SupportImportsOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

package/src/rules/stories/syntax.ts

@@ -0,0 +1,80 @@
+import ts from "typescript";
+import { isTestSupport, testName } from "#naming/testName.ts";
+import type { Finding, SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+
+export function isSpec(path: string): boolean {
+	return testName(path)?.kind === "spec" && !isTestSupport(path);
+}
+
+export function unwrapped(node: ts.Expression): ts.Expression {
+	return ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)
+		? unwrapped(node.expression)
+		: node;
+}
+
+export function memberName(node: ts.Expression): string | undefined {
+	const value = unwrapped(node);
+	if (ts.isPropertyAccessExpression(value)) {
+		return value.name.text;
+	}
+	return ts.isElementAccessExpression(value) && ts.isStringLiteralLike(value.argumentExpression) ? value.argumentExpression.text : undefined;
+}
+
+export function numericValue(node: ts.Expression): number | undefined {
+	const value = unwrapped(node);
+	if (ts.isNumericLiteral(value)) {
+		return Number(value.text);
+	}
+	if (ts.isPrefixUnaryExpression(value) && (value.operator === ts.SyntaxKind.MinusToken || value.operator === ts.SyntaxKind.PlusToken)) {
+		const operand = numericValue(value.operand);
+		return operand === undefined ? undefined : operand * (value.operator === ts.SyntaxKind.MinusToken ? -1 : 1);
+	}
+	return undefined;
+}
+
+export function findingAt(source: ts.SourceFile, node: ts.Node, message: string): Finding {
+	return { file: source.fileName, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1, message };
+}
+
+export function nodesWhere(source: ts.SourceFile, accepts: (node: ts.Node) => boolean): readonly ts.Node[] {
+	const found: ts.Node[] = [];
+	function visit(node: ts.Node): void {
+		if (accepts(node)) {
+			found.push(node);
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return found;
+}
+
+export function topLevelHelpers(source: ts.SourceFile): readonly ts.Node[] {
+	return source.statements.flatMap<ts.Node>((statement) => {
+		if (ts.isFunctionDeclaration(statement)) {
+			return statement.body === undefined ? [] : [statement.name ?? statement];
+		}
+		return ts.isVariableStatement(statement)
+			? statement.declarationList.declarations.flatMap((declaration) => {
+					const value = declaration.initializer === undefined ? undefined : unwrapped(declaration.initializer);
+					return value !== undefined && functionValue(value) ? [declaration.name] : [];
+				})
+			: [];
+	});
+}
+
+function functionValue(value: ts.Expression): boolean {
+	const node = unwrapped(value);
+	if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+		return true;
+	}
+	if (!ts.isCallExpression(node)) {
+		return false;
+	}
+	return ["fn", "fnUntraced"].includes(memberName(node.expression) ?? "") || (ts.isCallExpression(node.expression) && functionValue(node.expression));
+}
+
+export function syntaxFindings(file: SourceFile, select: (source: ts.SourceFile) => readonly ts.Node[], message: string): readonly Finding[] {
+	const source = parse(file);
+	return source === undefined ? [] : select(source).map((node) => findingAt(source, node, message));
+}

package/src/testProjects.ts

@@ -12,7 +12,7 @@ function named(environment?: Environment): string {
 }
 
 function excluding(...patterns: readonly string[]): string[] {
-	return [...defaultExclude, named("typecheck"), TYPECHECK_ALONE, ...patterns];
+	return [...defaultExclude, "**/.worktrees/**", named("typecheck"), TYPECHECK_ALONE, ...patterns];
 }
 
 export interface TestProjectsOptions {