@shivaedev/quality 0.21.1 → 0.22.0

package/src/exceptions/declaration.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+import { type Decoded, decodeWith } from "#decoded.ts";
+import { ConsumerDeclaration } from "#rules/suppressions/biome/ConsumerDeclaration.ts";
+
+const FILE = /^(?!\.\/)(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^*!?[\]{}\\]+$/u;
+
+export const ExceptionDeclaration = Schema.Struct({
+	files: Schema.NonEmptyArray(Schema.NonEmptyString),
+	reason: Schema.String.check(Schema.isPattern(/\S/u, { expected: "a reason that says why the exception is permanent" })),
+	rules: Schema.NonEmptyArray(Schema.NonEmptyString),
+	subject: Schema.optionalKey(Schema.NonEmptyString),
+}).check(
+	Schema.makeFilter(
+		({ files, reason, rules, subject }) =>
+			rules.every((rule) => {
+				if (rule.startsWith("biome/")) {
+					return (
+						subject === undefined
+						&& (rule === "biome/files/includes" || files.every((file) => FILE.test(file)))
+						&& Schema.is(ConsumerDeclaration)({ includes: files, reason, rule: rule.slice(6) })
+					);
+				}
+				return files.every((file) => FILE.test(file));
+			}),
+		{
+			message:
+				"Exceptions name explicit repository files and individual rules. Biome rules use biome/lint/<group>/<rule> or biome/assist/<group>/<action>, without a subject. Only biome/files/includes accepts ** and named directory exclusions.",
+		},
+	),
+);
+
+export type ExceptionDeclaration = typeof ExceptionDeclaration.Type;
+
+const standard = Schema.toStandardSchemaV1(Schema.Array(ExceptionDeclaration), { parseOptions: { errors: "all", onExcessProperty: "error" } });
+
+export function decodeExceptions(value: unknown): Promise<Decoded<readonly ExceptionDeclaration[]>> {
+	return decodeWith(standard, value);
+}

package/src/exceptions/migrateBiome.ts

@@ -0,0 +1,78 @@
+import ts from "typescript";
+import type { Declaration } from "#rules/suppressions/biome/declarations.ts";
+
+function nameOf(property: ts.ObjectLiteralElementLike): string | undefined {
+	return ts.isPropertyAssignment(property) && ts.isStringLiteral(property.name) ? property.name.text : undefined;
+}
+
+function strip(node: ts.Expression, paths: readonly (readonly string[])[]): ts.Expression {
+	if (!ts.isObjectLiteralExpression(node)) {
+		return node;
+	}
+	const properties = node.properties.flatMap((property) => {
+		const name = nameOf(property);
+		const matching = paths.filter((path) => path[0] === name);
+		if (!ts.isPropertyAssignment(property) || matching.length === 0) {
+			return [property];
+		}
+		if (matching.some((path) => path.length === 1)) {
+			return [];
+		}
+		const value = strip(
+			property.initializer,
+			matching.map((path) => path.slice(1)),
+		);
+		return ts.isObjectLiteralExpression(value) && value.properties.length === 0
+			? []
+			: [ts.factory.updatePropertyAssignment(property, property.name, value)];
+	});
+	return ts.factory.updateObjectLiteralExpression(node, properties);
+}
+
+function settingPath(rule: string): readonly string[] {
+	const [tool = "", group = "", name = ""] = rule.split("/");
+	return tool === "files" ? ["files", "includes"] : [tool === "lint" ? "linter" : "assist", tool === "lint" ? "rules" : "actions", group, name];
+}
+
+export function migrateBiome(text: string, file: string, declarations: readonly Declaration[]): string {
+	const source = ts.parseJsonText(file, text);
+	const root = source.statements[0]?.expression;
+	if (ts.parseConfigFileTextToJson(file, text).error !== undefined || root === undefined || !ts.isObjectLiteralExpression(root)) {
+		throw new Error(`Cannot migrate invalid Biome config ${file}. Repair it, then run quality exceptions migrate again.`);
+	}
+	const globals = declarations.filter((entry) => entry.rule === "files/includes");
+	const stripped = strip(
+		root,
+		globals.map((entry) => settingPath(entry.rule)),
+	);
+	if (!ts.isObjectLiteralExpression(stripped)) {
+		throw new Error(`Cannot migrate ${file}.`);
+	}
+	const properties = stripped.properties.flatMap((property) => {
+		if (nameOf(property) !== "overrides" || !ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+			return [property];
+		}
+		const overrides = property.initializer.elements.flatMap((override) => {
+			if (!ts.isObjectLiteralExpression(override)) {
+				return [override];
+			}
+			const includes = override.properties.find((item) => nameOf(item) === "includes");
+			const paths =
+				includes !== undefined && ts.isPropertyAssignment(includes) && ts.isArrayLiteralExpression(includes.initializer)
+					? includes.initializer.elements.filter(ts.isStringLiteral).map((item) => item.text)
+					: ["**"];
+			const matching = declarations.filter(
+				(entry) => entry.rule !== "files/includes" && entry.includes.length === paths.length && entry.includes.every((path) => paths.includes(path)),
+			);
+			const updated = strip(
+				override,
+				matching.map((entry) => settingPath(entry.rule)),
+			);
+			return ts.isObjectLiteralExpression(updated) && updated.properties.every((item) => nameOf(item) === "includes") ? [] : [updated];
+		});
+		return overrides.length === 0
+			? []
+			: [ts.factory.updatePropertyAssignment(property, property.name, ts.factory.updateArrayLiteralExpression(property.initializer, overrides))];
+	});
+	return `${ts.createPrinter().printNode(ts.EmitHint.Expression, ts.factory.updateObjectLiteralExpression(root, properties), source)}\n`;
+}

package/src/exceptions/migrateConfig.ts

@@ -0,0 +1,64 @@
+import ts from "typescript";
+import type { ExceptionDeclaration } from "./declaration.ts";
+
+function objectOf(expression: ts.Expression): ts.ObjectLiteralExpression | undefined {
+	if (ts.isObjectLiteralExpression(expression)) {
+		return expression;
+	}
+	if (ts.isCallExpression(expression) && expression.arguments[0] !== undefined) {
+		return objectOf(expression.arguments[0]);
+	}
+	return ts.isSatisfiesExpression(expression) || ts.isAsExpression(expression) || ts.isParenthesizedExpression(expression)
+		? objectOf(expression.expression)
+		: undefined;
+}
+
+function nameOf(property: ts.ObjectLiteralElementLike): string | undefined {
+	const name = property.name;
+	if (name === undefined) {
+		return undefined;
+	}
+	if (ts.isComputedPropertyName(name)) {
+		if (ts.isStringLiteral(name.expression) || ts.isNoSubstitutionTemplateLiteral(name.expression) || ts.isNumericLiteral(name.expression)) {
+			return name.expression.text;
+		}
+		throw new Error("Cannot migrate a computed property automatically. Use literal property keys, then run quality exceptions migrate again.");
+	}
+	return ts.isStringLiteral(name) || ts.isIdentifier(name) || ts.isNumericLiteral(name) ? name.text : undefined;
+}
+
+export function migrateConfig(text: string | undefined, file: string, exceptions: readonly ExceptionDeclaration[], hasDeclarations: boolean): string {
+	if (text === undefined) {
+		return `export default { exceptions: ${JSON.stringify(exceptions, null, "\t")} };\n`;
+	}
+	const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+	const exported = source.statements.find(ts.isExportAssignment);
+	const object = exported === undefined ? undefined : objectOf(exported.expression);
+	if (object === undefined || object.properties.some(ts.isSpreadAssignment)) {
+		throw new Error(
+			`Cannot migrate ${file} automatically. Export an object or defineConfig({ ... }) without spreads, then run quality exceptions migrate again.`,
+		);
+	}
+	const properties = object.properties.flatMap((property) => {
+		const name = nameOf(property);
+		if (name === "registry" || name === "exceptions") {
+			return [];
+		}
+		if (name !== "rules" || !hasDeclarations) {
+			return [{ name: name ?? "", text: property.getFullText(source).trim() }];
+		}
+		if (
+			!(ts.isPropertyAssignment(property) && ts.isObjectLiteralExpression(property.initializer))
+			|| property.initializer.properties.some(ts.isSpreadAssignment)
+		) {
+			throw new Error(`Inline the rules object in ${file}, then run quality exceptions migrate again.`);
+		}
+		const rules = property.initializer.properties.filter((rule) => nameOf(rule) !== "suppressions/biome-overrides");
+		return rules.length === 0 ? [] : [{ name: "rules", text: `rules: {\n${rules.map((rule) => rule.getFullText(source).trim()).join(",\n")}\n}` }];
+	});
+	const next = properties.map((property) => property.text);
+	const index = properties.findIndex((property) => property.name > "exceptions");
+	next.splice(index < 0 ? next.length : index, 0, `exceptions: ${JSON.stringify(exceptions, null, "\t")}`);
+	const replacement = `{\n${next.join(",\n")}\n}`;
+	return text.slice(0, object.getStart(source)) + replacement + text.slice(object.end);
+}

package/src/exceptions/registryEntries.ts

@@ -0,0 +1,10 @@
+import type { ExceptionDeclaration } from "./declaration.ts";
+import type { RegistryEntry } from "./registry.ts";
+
+export function registryEntries(declarations: readonly ExceptionDeclaration[]): readonly RegistryEntry[] {
+	return declarations.flatMap(({ files, reason, rules, subject }) =>
+		rules
+			.filter((rule) => !rule.startsWith("biome/"))
+			.flatMap((rule) => files.map((file) => ({ file, reason, rule, ...(subject === undefined ? {} : { subject }) }))),
+	);
+}

package/src/rule.ts

@@ -1,4 +1,5 @@
 import type { Bivariant } from "@shivaedev/types/bivariant.ts";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { describeIssue, type StandardSchemaV1 } from "./standard-schema.ts";
 
 export interface Finding {
@@ -19,6 +20,8 @@ export interface SourceFile {
 }
 
 export interface RuleInputs {
+	readonly configFile?: string;
+	readonly exceptions?: readonly ExceptionDeclaration[];
 	readonly files: readonly string[];
 	readonly readText: (path: string) => Promise<string | undefined>;
 	readonly root: string;

package/src/rules/biome.ts

@@ -43,8 +43,8 @@ async function presetFinding(readText: RuleInputs["readText"]): Promise<readonly
 }
 
 const bridge = defineRule({
-	check: async ({ readText, root }) => {
-		const [preset, report] = await Promise.all([presetFinding(readText), biomeReport(root, ["check"])]);
+	check: async ({ exceptions, readText, root }) => {
+		const [preset, report] = await Promise.all([presetFinding(readText), biomeReport(root, ["check"], exceptions)]);
 		return [...preset, ...report.diagnostics.filter((diagnostic) => FAILING.has(diagnostic.severity)).map(findingOf)];
 	},
 	description:

package/src/rules/suppressions/biome/ConsumerDeclaration.ts

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+import { Declaration } from "./declarations.ts";
+
+const GLOB = /[*!?[\]{}]/u;
+const DIRECTORY = /^\.?[^./\\*!?[\]{}]+$/u;
+const INDIVIDUAL = /^(?:lint|assist)\/(?!domains\/)[a-zA-Z]+\/[a-zA-Z]+$/u;
+
+function namedExclusion(pattern: string): boolean {
+	const segments = pattern.slice(pattern.startsWith("!**/") ? 4 : 1).split("/");
+	return pattern.startsWith("!") && DIRECTORY.test(segments.at(-1) ?? "") && segments.every((segment) => segment === "*" || DIRECTORY.test(segment));
+}
+
+export const ConsumerDeclaration = Declaration.check(
+	Schema.makeFilter(
+		({ includes, rule }) =>
+			rule === "files/includes"
+				? includes.includes("**") && includes.length > 1 && includes.every((pattern) => pattern === "**" || namedExclusion(pattern))
+				: INDIVIDUAL.test(rule) && includes.every((path) => !GLOB.test(path) && /[^/]+\.[^/]+$/u.test(path)),
+		{
+			message:
+				"Declare one lint rule or assist action for explicit files, or files/includes with ** and named directory exclusions. Whole checks, groups and blanket scopes cannot be weakened.",
+		},
+	),
+);

package/src/rules/suppressions/biome-overrides.ts

@@ -1,31 +1,11 @@
 import { Effect, Schema } from "effect";
+import { biomeExceptionHint, missingBiomeFiles } from "#exceptions/biomeFindings.ts";
 import { defineRule, type Finding } from "#rule.ts";
+import { ConsumerDeclaration } from "#rules/suppressions/biome/ConsumerDeclaration.ts";
 import { biomeConfigs, type Chain } from "#rules/suppressions/biome/configs.ts";
-import { Declaration, matches, type Scoped, scoped, scopeText } from "#rules/suppressions/biome/declarations.ts";
+import { matches, type Scoped, scoped, scopeText } from "#rules/suppressions/biome/declarations.ts";
 import { type Weakening, weakeningsOf } from "#rules/suppressions/biome/weakenings.ts";
 
-const GLOB = /[*!?[\]{}]/u;
-const DIRECTORY = /^\.?[^./\\*!?[\]{}]+$/u;
-const INDIVIDUAL = /^(?:lint|assist)\/(?!domains\/)[a-zA-Z]+\/[a-zA-Z]+$/u;
-
-function namedExclusion(pattern: string): boolean {
-	const segments = pattern.slice(pattern.startsWith("!**/") ? 4 : 1).split("/");
-	return pattern.startsWith("!") && DIRECTORY.test(segments.at(-1) ?? "") && segments.every((segment) => segment === "*" || DIRECTORY.test(segment));
-}
-
-const ConsumerDeclaration = Declaration.check(
-	Schema.makeFilter(
-		({ includes, rule }) =>
-			rule === "files/includes"
-				? includes.includes("**") && includes.length > 1 && includes.every((pattern) => pattern === "**" || namedExclusion(pattern))
-				: INDIVIDUAL.test(rule) && includes.every((path) => !GLOB.test(path) && /[^/]+\.[^/]+$/u.test(path)),
-		{
-			message:
-				"Declare one lint rule or assist action for explicit files, or files/includes with ** and named directory exclusions. Whole checks, groups and blanket scopes cannot be weakened.",
-		},
-	),
-);
-
 const BiomeOverridesOptions = Schema.Struct({
 	declared: Schema.Array(ConsumerDeclaration).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
 });
@@ -41,12 +21,12 @@ const shippedBy = ({ base, layers }: Chain): readonly Shipped[] =>
 			: preset.declared.map(({ includes, rule }) => ({ includes: includes.map((glob) => scoped(base, glob)), rule, specifier: preset.specifier })),
 	);
 
-const undeclared = ({ includes, layer, line, rule }: Weakening): Finding =>
+const undeclared = ({ includes, layer, line, rule }: Weakening, configFile: string): Finding =>
 	layer.preset === undefined
 		? {
 				file: layer.path,
 				line,
-				message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and remove the weakening setting.`,
+				message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and remove the weakening setting.${Schema.is(ConsumerDeclaration)({ includes, reason: "Permanent exception.", rule }) ? biomeExceptionHint(includes, rule, configFile) : ""}`,
 				subject: rule,
 			}
 		: {
@@ -85,7 +65,8 @@ export const biomeOverrides = defineRule({
 		const covered = (weakening: Weakening): boolean => [...declared, ...shipped].some((declaration) => matches(declaration, weakening));
 		return [
 			...problems,
-			...weakenings.filter((weakening) => !covered(weakening)).map(undeclared),
+			...(await missingBiomeFiles(inputs)),
+			...weakenings.filter((weakening) => !covered(weakening)).map((weakening) => undeclared(weakening, inputs.configFile ?? "quality.config.ts")),
 			...declared.flatMap(staleOrRepeated(root, weakenings, shipped)),
 		];
 	},