@shivaedev/quality 0.7.3 → 0.8.1

package/src/rules/files/folderNames.ts

@@ -0,0 +1,92 @@
+import { posix } from "node:path";
+import { Effect, Schema } from "effect";
+import ignore, { type Ignore } from "ignore";
+import { packageLayout } from "#naming/packageLayout.ts";
+import { KEBAB, PASCAL } from "#naming/words.ts";
+import { defineRule, type Finding } from "#rule.ts";
+
+const DEFAULT_TOOL_OWNED: readonly string[] = ["generated/", "migrations/"];
+
+const SNAKE = /^[a-z0-9]+(?:_[a-z0-9]+)*$/u;
+
+const CODE = /\.[cm]?[jt]sx?$/u;
+
+const FolderNamesOptions = Schema.Struct({
+	content: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+	toolOwned: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_TOOL_OWNED))),
+});
+
+function foldersIn(files: readonly string[]): readonly string[] {
+	const folders = new Set<string>();
+	for (const file of files) {
+		for (let folder = posix.dirname(file); folder !== "."; folder = posix.dirname(folder)) {
+			folders.add(folder);
+		}
+	}
+	return [...folders].sort();
+}
+
+function stemsIn(files: readonly string[]): ReadonlySet<string> {
+	return new Set(files.filter((file) => CODE.test(file)).map((file) => `${posix.dirname(file)}/${posix.basename(file).replace(CODE, "")}`));
+}
+
+function isModule(folder: string, stems: ReadonlySet<string>): boolean {
+	const name = posix.basename(folder);
+	return stems.has(`${folder}/${name}`) || stems.has(`${posix.dirname(folder)}/${name}`);
+}
+
+function packageMessage(name: string, packageName: string): string | undefined {
+	const expected = packageName.replace(/^@[^/]+\//u, "");
+	return name === expected ? undefined : `The folder of the package ${packageName} is named "${expected}", in kebab-case after the package name.`;
+}
+
+function groupMessage(name: string): string | undefined {
+	if (PASCAL.test(name)) {
+		return `"${name}" is PascalCase but holds no ${name}.ts or ${name}.tsx. A PascalCase folder is a module named after its main file: add that file, or name the folder in kebab-case.`;
+	}
+	return KEBAB.test(name.replace(/^\./u, ""))
+		? undefined
+		: `"${name}" groups files, so it is named in kebab-case, such as test-support/. A folder named after a file beside or inside it is a module and takes that file's name.`;
+}
+
+interface Context {
+	readonly content: Ignore;
+	readonly names: ReadonlyMap<string, string>;
+	readonly stems: ReadonlySet<string>;
+	readonly toolOwned: Ignore;
+}
+
+function messageFor(folder: string, context: Context): string | undefined {
+	const name = posix.basename(folder);
+	if (context.toolOwned.ignores(`${folder}/`) || isModule(folder, context.stems)) {
+		return undefined;
+	}
+	const packageName = context.names.get(folder);
+	if (packageName !== undefined) {
+		return packageMessage(name, packageName);
+	}
+	if (context.content.ignores(`${folder}/`)) {
+		return SNAKE.test(name) ? undefined : `"${name}" holds content, so it is named in snake_case, such as forest_path/.`;
+	}
+	return groupMessage(name);
+}
+
+export const folderNames = defineRule({
+	check: async ({ files, options, readText }) => {
+		const layout = await packageLayout({ files, readText });
+		const context: Context = {
+			content: ignore().add([...options.content]),
+			names: layout.names,
+			stems: stemsIn(files),
+			toolOwned: ignore().add([...options.toolOwned]),
+		};
+		return foldersIn(files).flatMap((folder): readonly Finding[] => {
+			const message = messageFor(folder, context);
+			return message === undefined ? [] : [{ file: folder, message }];
+		});
+	},
+	description:
+		"A package folder is named after its package, a module folder after its main file, a content folder in snake_case and every other folder in kebab-case.",
+	id: "files/folder-names",
+	options: Schema.toStandardSchemaV1(FolderNamesOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

package/src/rules/files/namedAfterExport.ts

@@ -0,0 +1,87 @@
+import { posix } from "node:path";
+import { Effect, Schema } from "effect";
+import ignore from "ignore";
+import { exportFits } from "#naming/exportFits.ts";
+import { mainExport } from "#naming/mainExport.ts";
+import { ownExports } from "#naming/ownExports.ts";
+import { type PackageLayout, packageLayout } from "#naming/packageLayout.ts";
+import { CAMEL, KEBAB, sameWord, wordsOf } from "#naming/words.ts";
+import { defineRule, type Finding, type SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+
+const DEFAULT_TOOL_OWNED: readonly string[] = ["*.config.*", "*.d.ts", "*.d.mts", "*.d.cts"];
+
+const TEST = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
+
+const SHEBANG = "#!";
+
+const SHAPES =
+	"The file name and the names of its folders spell the export, in any order, and the file's first letter follows the export's case: listItems in items/ is items/list.ts, ItemPanel is ItemPanel.tsx or item/Panel.tsx.";
+
+const NamedAfterExportOptions = Schema.Struct({
+	toolOwned: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_TOOL_OWNED))),
+});
+
+function stemOf(path: string): string {
+	return posix.basename(path).replace(/\.[^.]+$/u, "");
+}
+
+function repeated(stem: string, folders: readonly string[]): string | undefined {
+	if (folders.at(-1) === stem) {
+		return undefined;
+	}
+	const words = wordsOf(stem);
+	return folders.find((folder) => wordsOf(folder).some((word) => words.some((own) => sameWord(own, word))));
+}
+
+function nameFinding(file: SourceFile, stem: string, folders: readonly string[]): string | undefined {
+	const source = parse(file);
+	const exports = source === undefined ? [] : ownExports(source);
+	const [only] = exports;
+	if (only === undefined) {
+		return CAMEL.test(stem)
+			? undefined
+			: `"${stem}" exports nothing, so it is named in camelCase, such as setupTests.ts. A file that a package.json script or bin runs is kebab-case.`;
+	}
+	if (exports.length === 1 && only.constant) {
+		return `"${stem}" exports only the constant ${only.name}. Constants live in a topic file with related constants, such as limits.ts holding MAX_ITEMS and MAX_DEPTH.`;
+	}
+	if (exports.some((entry) => exportFits(entry.name, stem, folders))) {
+		return undefined;
+	}
+	const main = mainExport(exports);
+	if (main !== undefined) {
+		return `"${stem}" does not name its export ${main.name}. ${SHAPES} Rename the file or the export.`;
+	}
+	return CAMEL.test(stem)
+		? undefined
+		: `"${stem}" exports several things, so it is a topic file named in camelCase, such as limits.ts. Or split it so each file has one main export. ${SHAPES}`;
+}
+
+function findingsOf(file: SourceFile, layout: PackageLayout): readonly Finding[] {
+	const stem = stemOf(file.path);
+	const folders = layout.foldersOf(file.path);
+	if (layout.scripts.has(file.path) || file.text.startsWith(SHEBANG)) {
+		return KEBAB.test(stem)
+			? []
+			: [{ file: file.path, message: `"${stem}" is run as a script, so it is named in kebab-case, such as build-docs.ts.` }];
+	}
+	const folder = repeated(stem, folders);
+	const messages = [
+		nameFinding(file, stem, folders),
+		folder === undefined ? undefined : `"${stem}" repeats its folder "${folder}". The folder is the prefix: items/listItems.ts is items/list.ts.`,
+	];
+	return messages.flatMap((message) => (message === undefined ? [] : [{ file: file.path, message }]));
+}
+
+export const namedAfterExport = defineRule({
+	check: async ({ files, options, readText, sources }) => {
+		const layout = await packageLayout({ files, readText });
+		const toolOwned = ignore().add([...options.toolOwned]);
+		return sources.filter((file) => !(TEST.test(file.path) || toolOwned.ignores(file.path))).flatMap((file) => findingsOf(file, layout));
+	},
+	description:
+		"A file is named after its main export, with its folders as the prefix; a file of several exports is a camelCase topic file, and a script is kebab-case. Rename the file or the export; nothing renames them for you.",
+	id: "files/named-after-export",
+	options: Schema.toStandardSchemaV1(NamedAfterExportOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

package/src/rules/files/otherNames.ts

@@ -0,0 +1,118 @@
+import { posix } from "node:path";
+import { Effect, Schema } from "effect";
+import ignore, { type Ignore } from "ignore";
+import { CAMEL, KEBAB } from "#naming/words.ts";
+import { defineRule, type Finding, type SourceFile } from "#rule.ts";
+
+const DEFAULT_TOOL_OWNED: readonly string[] = [
+	".*",
+	"package.json",
+	"tsconfig*.json",
+	"biome.json",
+	"biome.jsonc",
+	"*.config.*",
+	"migrations/",
+	"generated/",
+];
+
+const CONVENTIONAL: ReadonlySet<string> = new Set(["AGENTS", "CHANGELOG", "CLAUDE", "CONTRIBUTING", "LICENSE", "README", "SECURITY", "SKILL"]);
+
+const KEBAB_KINDS: ReadonlySet<string> = new Set([
+	"avif",
+	"gif",
+	"grit",
+	"ico",
+	"jpeg",
+	"jpg",
+	"json",
+	"jsonc",
+	"md",
+	"mdx",
+	"otf",
+	"png",
+	"svg",
+	"ttf",
+	"webp",
+	"woff",
+	"woff2",
+]);
+
+const STYLESHEETS: ReadonlySet<string> = new Set(["css", "scss"]);
+
+const DOTTED_KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)*$/u;
+
+const SNAKE = /^[a-z0-9]+(?:_[a-z0-9]+)*$/u;
+
+const STYLESHEET_IMPORT = /["'](?<stylesheet>\.{1,2}\/[^"'\n]+\.s?css)["']/gu;
+
+const CODE = /\.[cm]?[jt]sx?$/u;
+
+const OtherNamesOptions = Schema.Struct({
+	content: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+	toolOwned: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_TOOL_OWNED))),
+});
+
+function importers(sources: readonly SourceFile[]): ReadonlyMap<string, readonly string[]> {
+	const found = new Map<string, string[]>();
+	for (const source of sources) {
+		for (const match of source.text.matchAll(STYLESHEET_IMPORT)) {
+			const target = posix.normalize(posix.join(posix.dirname(source.path), match.groups?.stylesheet ?? ""));
+			found.set(target, [...new Set([...(found.get(target) ?? []), source.path])]);
+		}
+	}
+	return found;
+}
+
+function stylesheetMessage(path: string, stem: string, importedBy: readonly string[]): string | undefined {
+	const [only] = importedBy;
+	if (importedBy.length === 1 && only !== undefined) {
+		const owner = posix.basename(only).replace(CODE, "");
+		return stem === owner ? undefined : `"${stem}" is styling for ${posix.basename(only)} alone, so it is named ${owner}${posix.extname(path)}.`;
+	}
+	return KEBAB.test(stem) ? undefined : `"${stem}" is a shared stylesheet, so it is named in kebab-case, such as form-controls.css.`;
+}
+
+interface Context {
+	readonly content: Ignore;
+	readonly stylesheets: ReadonlyMap<string, readonly string[]>;
+	readonly toolOwned: Ignore;
+}
+
+function messageFor(path: string, context: Context): string | undefined {
+	const name = posix.basename(path);
+	const kind = posix.extname(name).slice(1);
+	const stem = name.slice(0, name.length - kind.length - 1);
+	if (kind === "" || context.toolOwned.ignores(path) || CONVENTIONAL.has(stem)) {
+		return undefined;
+	}
+	if (context.content.ignores(path)) {
+		return SNAKE.test(stem) ? undefined : `"${name}" is content, so it is named in snake_case, such as forest_path.json.`;
+	}
+	if (STYLESHEETS.has(kind)) {
+		return stylesheetMessage(path, stem, context.stylesheets.get(path) ?? []);
+	}
+	if (kind === "prisma") {
+		return CAMEL.test(stem) ? undefined : `"${name}" is a Prisma schema, so it is named in camelCase, such as schema.prisma.`;
+	}
+	return KEBAB_KINDS.has(kind) && !DOTTED_KEBAB.test(stem)
+		? `"${name}" is named in kebab-case, such as release-notes.md. Only conventional names such as README.md and CHANGELOG.md are upper case.`
+		: undefined;
+}
+
+export const otherNames = defineRule({
+	check: ({ files, options, sources }) => {
+		const context: Context = {
+			content: ignore().add([...options.content]),
+			stylesheets: importers(sources),
+			toolOwned: ignore().add([...options.toolOwned]),
+		};
+		return files.flatMap((path): readonly Finding[] => {
+			const message = messageFor(path, context);
+			return message === undefined ? [] : [{ file: path, message }];
+		});
+	},
+	description:
+		"Documents, data, assets and GritQL files are kebab-case, a stylesheet that one component imports is named after it, a Prisma schema is camelCase and content is snake_case.",
+	id: "files/other-names",
+	options: Schema.toStandardSchemaV1(OtherNamesOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

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

@@ -0,0 +1,34 @@
+import { Effect, Schema } from "effect";
+import ignore from "ignore";
+import { testName } from "#naming/testName.ts";
+import { defineRule, type Finding } from "#rule.ts";
+
+const MIRROR_FOLDERS: ReadonlySet<string> = new Set(["__tests__", "spec", "test", "tests"]);
+
+const TestsColocatedOptions = Schema.Struct({
+	suites: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+});
+
+function findingOf(path: string): readonly Finding[] {
+	const name = testName(path);
+	const mirror = name?.folder.split("/").find((folder) => MIRROR_FOLDERS.has(folder));
+	if (name === undefined || mirror === undefined) {
+		return [];
+	}
+	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.`,
+		},
+	];
+}
+
+export const testsColocated = defineRule({
+	check: ({ files, options }) => {
+		const suites = ignore().add([...options.suites]);
+		return files.filter((path) => !suites.ignores(path)).flatMap(findingOf);
+	},
+	description: "A test sits beside the code it covers, not in a test, tests, __tests__ or spec folder, unless that folder is a declared suite.",
+	id: "tests/colocated",
+	options: Schema.toStandardSchemaV1(TestsColocatedOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

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

@@ -0,0 +1,78 @@
+import { posix } from "node:path";
+import { Effect, Schema } from "effect";
+import ignore from "ignore";
+import { ENVIRONMENTS, type TestName, testName } from "#naming/testName.ts";
+import { CAMEL } from "#naming/words.ts";
+import { defineRule, type Finding, type SourceFile } from "#rule.ts";
+import { usesDom } from "#rules/test-names/usesDom.ts";
+
+const ENVIRONMENT_NAMES: ReadonlySet<string> = new Set(ENVIRONMENTS);
+
+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.";
+
+const TestsFollowOptions = Schema.Struct({
+	suites: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+});
+
+function siblingsIn(files: readonly string[]): ReadonlySet<string> {
+	return new Set(files.filter((file) => CODE.test(file) && testName(file) === undefined).map((file) => file.replace(CODE, "")));
+}
+
+function suffixMessage(file: string, name: TestName): string | undefined {
+	const [first, ...rest] = name.modifiers;
+	if (first === undefined || (rest.length === 0 && ENVIRONMENT_NAMES.has(first))) {
+		return undefined;
+	}
+	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}`;
+	}
+	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 placeMessage(file: string, name: TestName, siblings: ReadonlySet<string>): string | undefined {
+	const covered = siblings.has(`${name.folder}/${name.stem}`);
+	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}.`;
+	}
+	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 CAMEL.test(name.stem) ? undefined : `"${file}" names its behaviour in camelCase, such as checkoutFlow.spec${name.extension}.`;
+}
+
+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.`;
+}
+
+function findingsOf(source: SourceFile, siblings: ReadonlySet<string>): readonly Finding[] {
+	const name = testName(source.path);
+	if (name === undefined) {
+		return [];
+	}
+	const file = posix.basename(source.path);
+	const messages = [suffixMessage(file, name), placeMessage(file, name, siblings), environmentMessage(file, name, source)];
+	return messages.flatMap((message) => (message === undefined ? [] : [{ file: source.path, message }]));
+}
+
+export const testsFollow = defineRule({
+	check: ({ files, options, sources }) => {
+		const suites = ignore().add([...options.suites]);
+		const siblings = siblingsIn(files);
+		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.",
+	id: "tests/follow",
+	options: Schema.toStandardSchemaV1(TestsFollowOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
+});

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

@@ -0,0 +1,22 @@
+import ts from "typescript";
+import type { SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+
+const DOM_GLOBALS: ReadonlySet<string> = new Set(["document", "window"]);
+
+const TESTING_LIBRARY = "@testing-library/";
+
+function touchesDom(node: ts.Node): boolean {
+	if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+		return node.moduleSpecifier.text.startsWith(TESTING_LIBRARY);
+	}
+	if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && DOM_GLOBALS.has(node.expression.text)) {
+		return true;
+	}
+	return ts.forEachChild(node, touchesDom) ?? false;
+}
+
+export function usesDom(file: SourceFile): boolean {
+	const source = parse(file);
+	return source === undefined ? false : touchesDom(source);
+}

package/src/vitest.ts

@@ -1,22 +1,25 @@
 import { defaultExclude, type TestUserConfig } from "vitest/config";
+import type { Environment } from "#naming/testName.ts";
 
-const TEST = "**/*.test.?(c|m)[jt]s?(x)";
-const DOM = "**/*.dom.test.?(c|m)[jt]s?(x)";
-const SLOW = "**/*.slow.test.?(c|m)[jt]s?(x)";
-const TYPECHECK = "**/*.typecheck.test.?(c|m)[jt]s?(x)";
-const TYPECHECK_ALONE = "**/typecheck.test.?(c|m)[jt]s?(x)";
+const EXTENSION = "?(c|m)[jt]s?(x)";
 
-function excluding(...patterns: readonly string[]): string[] {
-	return [...defaultExclude, TYPECHECK, TYPECHECK_ALONE, ...patterns];
+const TYPECHECK_ALONE = `**/typecheck.test.${EXTENSION}`;
+
+function named(environment?: Environment): string {
+	return environment === undefined ? `**/*.@(test|spec).${EXTENSION}` : `**/*.${environment}.@(test|spec).${EXTENSION}`;
+}
+
+function excluding(exclude: readonly string[], ...patterns: readonly string[]): string[] {
+	return [...defaultExclude, named("typecheck"), TYPECHECK_ALONE, ...exclude, ...patterns];
 }
 
-export function testProjects(): TestUserConfig {
+export function testProjects({ exclude = [] }: { readonly exclude?: readonly string[] } = {}): TestUserConfig {
 	return {
 		project: ["unit", "dom"],
 		projects: [
-			{ extends: true, test: { environment: "node", exclude: excluding(DOM, SLOW), include: [TEST], name: "unit" } },
-			{ extends: true, test: { environment: "happy-dom", exclude: excluding(SLOW), include: [DOM], name: "dom" } },
-			{ extends: true, test: { environment: "node", exclude: excluding(), include: [SLOW], name: "slow" } },
+			{ extends: true, test: { environment: "node", exclude: excluding(exclude, named("dom"), named("slow")), include: [named()], name: "unit" } },
+			{ extends: true, test: { environment: "happy-dom", exclude: excluding(exclude, named("slow")), include: [named("dom")], name: "dom" } },
+			{ extends: true, test: { environment: "node", exclude: excluding(exclude), include: [named("slow")], name: "slow" } },
 		],
 	};
 }