ai-deslop 0.2.0

package/src/shared/type-alias-resolution.ts

@@ -0,0 +1,250 @@
+import type { ESTree } from "@oxlint/plugins";
+
+import { lexicalTypeParameterNames } from "./lexical-type-parameters.ts";
+
+type VisitorKeys = Readonly<Record<string, readonly string[]>>;
+type TypeScope = ESTree.Node;
+
+type TypeBinding = {
+	readonly alias: ESTree.TSTypeAliasDeclaration | null;
+	readonly name: string;
+	readonly scope: TypeScope;
+};
+
+type Substitution = {
+	readonly substitutions: Substitutions;
+	readonly type: ESTree.TSType;
+};
+
+type Substitutions = ReadonlyMap<string, Substitution>;
+
+export type TypeAliasEnvironment = {
+	readonly aliases: readonly ESTree.TSTypeAliasDeclaration[];
+	readonly bindingsByName: ReadonlyMap<string, readonly TypeBinding[]>;
+	readonly visitorKeys: VisitorKeys;
+};
+
+export type ResolvedTypeMatcher = (
+	type: ESTree.TSType,
+	matches: (child: ESTree.TSType) => boolean,
+) => boolean;
+
+const environmentsByProgram = new WeakMap<ESTree.Program, TypeAliasEnvironment>();
+
+function isNode(value: unknown): value is ESTree.Node {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"type" in value &&
+		typeof value.type === "string"
+	);
+}
+
+function enclosingTypeScope(node: ESTree.Node): TypeScope {
+	let current: ESTree.Node | null = node.parent;
+	while (current !== null) {
+		if (
+			current.type === "Program" ||
+			current.type === "BlockStatement" ||
+			current.type === "TSModuleBlock" ||
+			current.type === "StaticBlock" ||
+			current.type === "SwitchStatement"
+		) {
+			return current;
+		}
+		current = current.parent;
+	}
+	return node;
+}
+
+function declaredTypeBinding(node: ESTree.Node): {
+	readonly alias: ESTree.TSTypeAliasDeclaration | null;
+	readonly name: string;
+} | null {
+	if (node.type === "TSTypeAliasDeclaration") {
+		return { alias: node, name: node.id.name };
+	}
+	if (
+		node.type === "TSInterfaceDeclaration" ||
+		node.type === "TSEnumDeclaration" ||
+		node.type === "ClassDeclaration" ||
+		node.type === "ClassExpression"
+	) {
+		return node.id === null ? null : { alias: null, name: node.id.name };
+	}
+	if (
+		node.type === "ImportSpecifier" ||
+		node.type === "ImportDefaultSpecifier" ||
+		node.type === "ImportNamespaceSpecifier"
+	) {
+		return { alias: null, name: node.local.name };
+	}
+	return null;
+}
+
+function collectTypeBindings(
+	node: ESTree.Node,
+	visitorKeys: VisitorKeys,
+	bindingsByName: Map<string, TypeBinding[]>,
+	aliases: ESTree.TSTypeAliasDeclaration[],
+): void {
+	const declared = declaredTypeBinding(node);
+	if (declared !== null) {
+		const bindings = bindingsByName.get(declared.name) ?? [];
+		bindings.push({ ...declared, scope: enclosingTypeScope(node) });
+		bindingsByName.set(declared.name, bindings);
+		if (declared.alias !== null) aliases.push(declared.alias);
+	}
+
+	// SAFETY: Oxlint's visitor keys identify only ESTree child-node properties.
+	const fields = node as unknown as Readonly<Record<string, unknown>>;
+	for (const key of visitorKeys[node.type] ?? []) {
+		const value = fields[key];
+		if (isNode(value)) {
+			collectTypeBindings(value, visitorKeys, bindingsByName, aliases);
+			continue;
+		}
+		if (!Array.isArray(value)) continue;
+		for (const child of value) {
+			if (isNode(child)) {
+				collectTypeBindings(child, visitorKeys, bindingsByName, aliases);
+			}
+		}
+	}
+}
+
+/** Collect every lexical type alias and competing type binding in a program. */
+export function createTypeAliasEnvironment(
+	program: ESTree.Program,
+	visitorKeys: VisitorKeys,
+): TypeAliasEnvironment {
+	const cached = environmentsByProgram.get(program);
+	if (cached !== undefined) return cached;
+	const bindingsByName = new Map<string, TypeBinding[]>();
+	const aliases: ESTree.TSTypeAliasDeclaration[] = [];
+	collectTypeBindings(program, visitorKeys, bindingsByName, aliases);
+	const environment = { aliases, bindingsByName, visitorKeys };
+	environmentsByProgram.set(program, environment);
+	return environment;
+}
+
+function ancestorDistance(ancestor: ESTree.Node, node: ESTree.Node): number | null {
+	let current: ESTree.Node | null = node;
+	let distance = 0;
+	while (current !== null) {
+		if (current === ancestor) return distance;
+		current = current.parent;
+		distance += 1;
+	}
+	return null;
+}
+
+function nearestTypeBindings(
+	name: string,
+	use: ESTree.Node,
+	environment: TypeAliasEnvironment,
+): readonly TypeBinding[] {
+	const candidates = environment.bindingsByName.get(name) ?? [];
+	let nearestDistance = Number.POSITIVE_INFINITY;
+	let nearest: TypeBinding[] = [];
+	for (const candidate of candidates) {
+		const distance = ancestorDistance(candidate.scope, use);
+		if (distance === null || distance > nearestDistance) continue;
+		if (distance === nearestDistance) {
+			nearest.push(candidate);
+			continue;
+		}
+		nearestDistance = distance;
+		nearest = [candidate];
+	}
+	return nearest;
+}
+
+/** Resolve the nearest visible alias with this name, respecting lexical shadowing. */
+export function visibleTypeAlias(
+	name: string,
+	use: ESTree.Node,
+	environment: TypeAliasEnvironment,
+): ESTree.TSTypeAliasDeclaration | null {
+	if (lexicalTypeParameterNames(use, environment.visitorKeys).has(name)) return null;
+	const bindings = nearestTypeBindings(name, use, environment);
+	return bindings.length === 1 ? (bindings[0]?.alias ?? null) : null;
+}
+
+/** Return whether a local declaration shadows a built-in type at this use. */
+export function hasVisibleTypeBinding(
+	name: string,
+	use: ESTree.Node,
+	environment: TypeAliasEnvironment,
+): boolean {
+	return (
+		lexicalTypeParameterNames(use, environment.visitorKeys).has(name) ||
+		nearestTypeBindings(name, use, environment).length > 0
+	);
+}
+
+function typeReferenceName(type: ESTree.TSTypeReference): string | null {
+	return type.typeName.type === "Identifier" ? type.typeName.name : null;
+}
+
+function aliasSubstitutions(
+	alias: ESTree.TSTypeAliasDeclaration,
+	reference: ESTree.TSTypeReference,
+	base: Substitutions,
+): Substitutions | null {
+	const parameters = alias.typeParameters?.params ?? [];
+	const arguments_ = reference.typeArguments?.params ?? [];
+	const next = new Map(base);
+	for (const [index, parameter] of parameters.entries()) {
+		const explicitArgument = arguments_[index];
+		const argument = explicitArgument ?? parameter.default;
+		if (argument === null || argument === undefined) return null;
+		const argumentSubstitutions = explicitArgument === undefined ? next : base;
+		next.set(parameter.name.name, {
+			type: argument,
+			substitutions: new Map(argumentSubstitutions),
+		});
+	}
+	return next;
+}
+
+/** Match a type after resolving visible aliases and substituting their type parameters. */
+export function resolvedTypeMatches(
+	type: ESTree.TSType,
+	environment: TypeAliasEnvironment,
+	matcher: ResolvedTypeMatcher,
+): boolean {
+	const evaluate = (
+		current: ESTree.TSType,
+		substitutions: Substitutions,
+		resolvingAliases: ReadonlySet<ESTree.TSTypeAliasDeclaration>,
+	): boolean => {
+		if (current.type === "TSTypeReference") {
+			const name = typeReferenceName(current);
+			if (name !== null) {
+				const substitution = substitutions.get(name);
+				if (substitution !== undefined && !current.typeArguments?.params.length) {
+					return evaluate(
+						substitution.type,
+						substitution.substitutions,
+						resolvingAliases,
+					);
+				}
+				const alias = visibleTypeAlias(name, current, environment);
+				if (alias !== null && !resolvingAliases.has(alias)) {
+					const nextSubstitutions = aliasSubstitutions(alias, current, substitutions);
+					if (nextSubstitutions !== null) {
+						const nextResolving = new Set(resolvingAliases);
+						nextResolving.add(alias);
+						return evaluate(alias.typeAnnotation, nextSubstitutions, nextResolving);
+					}
+				}
+			}
+		}
+		return matcher(current, (child) =>
+			evaluate(child, substitutions, resolvingAliases),
+		);
+	};
+
+	return evaluate(type, new Map(), new Set());
+}

package/src/tailwind/candidates.ts

@@ -0,0 +1,38 @@
+export interface SpellingChange {
+	original: string;
+	canonical: string;
+}
+
+export function rewriteClassValue(
+	value: string,
+	canonicalOf: ReadonlyMap<string, string>,
+): { fixed: string; changes: Array<SpellingChange> } {
+	const changes: Array<SpellingChange> = [];
+	const fixed = value.replace(/\S+/g, (token) => {
+		const canonical = canonicalOf.get(token);
+		if (canonical !== undefined && canonical !== token) {
+			changes.push({ original: token, canonical });
+			return canonical;
+		}
+		return token;
+	});
+	return { fixed, changes };
+}
+
+export function uniqueTokens(value: string): Array<string> {
+	const tokens = value.match(/\S+/g) ?? [];
+	return [...new Set(tokens)];
+}
+
+export function summarizeChanges(changes: ReadonlyArray<SpellingChange>): {
+	original: string;
+	canonical: string;
+	suffix: string;
+} {
+	const first = changes[0];
+	return {
+		original: first.original,
+		canonical: first.canonical,
+		suffix: changes.length > 1 ? ` (+${changes.length - 1} more in this string)` : "",
+	};
+}

package/src/tailwind/design-system.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSyncFn } from "synckit";
+
+interface LoadJob {
+	type: "load";
+	key: string;
+	cssContent: string;
+	base: string;
+}
+
+interface CanonicalizeJob {
+	type: "canonicalize";
+	key: string;
+	candidates: Array<string>;
+	rem: number;
+}
+
+type WorkerJob = LoadJob | CanonicalizeJob;
+type WorkerResult = { ok: true } | Array<string>;
+type WorkerFunction = (job: WorkerJob) => Promise<WorkerResult>;
+
+const workerPath = fileURLToPath(new URL("./worker.ts", import.meta.url));
+let syncCall: ReturnType<typeof createSyncFn<WorkerFunction>> | null = null;
+const loadedSystems = new Map<string, number>();
+
+function getSyncCall(): ReturnType<typeof createSyncFn<WorkerFunction>> {
+	if (syncCall === null) {
+		syncCall = createSyncFn<WorkerFunction>(workerPath);
+	}
+	return syncCall;
+}
+
+export function resolveCssPath(cssPath: string | undefined, cwd = process.cwd()): string {
+	if (!cssPath) throw new Error("cssPath is required");
+	return path.isAbsolute(cssPath) ? cssPath : path.resolve(cwd, cssPath);
+}
+
+export function ensureDesignSystem(cssFile: string): string {
+	const stat = fs.statSync(cssFile);
+	if (loadedSystems.get(cssFile) === stat.mtimeMs) return cssFile;
+
+	const cssContent = fs.readFileSync(cssFile, "utf8");
+	getSyncCall()({ type: "load", key: cssFile, cssContent, base: path.dirname(cssFile) });
+	loadedSystems.set(cssFile, stat.mtimeMs);
+	return cssFile;
+}
+
+export function canonicalizeTokens(key: string, tokens: Array<string>, rem: number): Map<string, string> {
+	if (tokens.length === 0) return new Map();
+
+	const canonical = getSyncCall()({ type: "canonicalize", key, candidates: tokens, rem });
+	if (!Array.isArray(canonical)) throw new Error("Tailwind canonicalization returned an invalid result");
+
+	const result = new Map<string, string>();
+	for (let i = 0; i < tokens.length; i++) result.set(tokens[i], canonical[i] ?? tokens[i]);
+	return result;
+}

package/src/tailwind/rule.ts

@@ -0,0 +1,126 @@
+import { defineRule } from "@oxlint/plugins";
+import type { ESTree } from "@oxlint/plugins";
+import { rewriteClassValue, summarizeChanges, uniqueTokens } from "./candidates.ts";
+import { canonicalizeTokens, ensureDesignSystem, resolveCssPath } from "./design-system.ts";
+
+export const PLUGIN_NAME = "deslop";
+export const RULE_ID = "canonical-class-names";
+
+const DEFAULT_ATTRIBUTES = ["class", "className"];
+const DEFAULT_CALLEE_FUNCTIONS = ["cn", "clsx", "cva", "twMerge", "tw", "classNames", "cx"];
+const DEFAULT_ROOT_FONT_SIZE = 16;
+
+interface RuleOptions {
+	cssPath: string;
+	rootFontSize?: number;
+	attributes?: Array<string>;
+	calleeFunctions?: Array<string>;
+}
+
+const OPTIONS_SCHEMA = {
+	type: "object",
+	properties: {
+		cssPath: { type: "string", description: "Path to the Tailwind v4 entry CSS." },
+		rootFontSize: { type: "number", description: "Root font size in px used for rem normalization." },
+		attributes: { type: "array", items: { type: "string" }, description: "JSX class-list attributes." },
+		calleeFunctions: { type: "array", items: { type: "string" }, description: "Class-list helper functions." },
+	},
+	required: ["cssPath"],
+	additionalProperties: false,
+} as const;
+
+type StringNode = ESTree.StringLiteral | ESTree.TemplateLiteral;
+
+export const canonicalClassNames = defineRule({
+	meta: {
+		type: "suggestion",
+		docs: { description: "Enforce canonical Tailwind CSS class spellings." },
+		fixable: "code",
+		messages: {
+			nonCanonical: "Tailwind class '{{original}}' can be written as '{{canonical}}'.{{suffix}}",
+			cssNotFound: "Could not load Tailwind CSS entry file: {{path}}",
+		},
+		schema: [OPTIONS_SCHEMA],
+	},
+	createOnce(context) {
+		let attributes = new Set(DEFAULT_ATTRIBUTES);
+		let callees = new Set(DEFAULT_CALLEE_FUNCTIONS);
+		let rem = DEFAULT_ROOT_FONT_SIZE;
+		let cssFile = "";
+		let designKey: string | false | null = null;
+
+		function initFile() {
+			const options = (context.options?.[0] ?? {}) as Partial<RuleOptions>;
+			attributes = new Set(options.attributes ?? DEFAULT_ATTRIBUTES);
+			callees = new Set(options.calleeFunctions ?? DEFAULT_CALLEE_FUNCTIONS);
+			rem = options.rootFontSize ?? DEFAULT_ROOT_FONT_SIZE;
+			try {
+				cssFile = resolveCssPath(options.cssPath);
+			} catch {
+				cssFile = options.cssPath ?? "";
+			}
+			designKey = null;
+		}
+
+		function getDesignKey(): string | null {
+			if (designKey === null) {
+				try { designKey = ensureDesignSystem(cssFile); } catch { designKey = false; }
+			}
+			return designKey === false ? null : designKey;
+		}
+
+		function checkStringNode(node: StringNode, value: string) {
+			const tokens = uniqueTokens(value);
+			if (tokens.length === 0) return;
+			const key = getDesignKey();
+			if (key === null) {
+				context.report({ node, messageId: "cssNotFound", data: { path: cssFile } });
+				return;
+			}
+			let canonicalOf: Map<string, string>;
+			try { canonicalOf = canonicalizeTokens(key, tokens, rem); } catch { return; }
+			const { fixed, changes } = rewriteClassValue(value, canonicalOf);
+			if (changes.length === 0) return;
+			const summary = summarizeChanges(changes);
+			context.report({
+				node,
+				messageId: "nonCanonical",
+				data: summary,
+				fix(fixer) {
+					const first = context.sourceCode.getText(node)[0];
+					const quote = first === "'" || first === '"' || first === "`" ? first : '"';
+					return fixer.replaceText(node, `${quote}${fixed}${quote}`);
+				},
+			});
+		}
+
+		function checkExpression(node: ESTree.Expression | ESTree.JSXEmptyExpression) {
+			if (node.type === "Literal" && typeof node.value === "string") checkStringNode(node, node.value);
+			else if (node.type === "TemplateLiteral" && node.expressions.length === 0 && node.quasis.length === 1) {
+				checkStringNode(node, node.quasis[0].value.raw);
+			}
+		}
+
+		return {
+			before() {
+				initFile();
+				const text = context.sourceCode.text;
+				for (const name of attributes) if (name !== "" && text.includes(name)) return;
+				for (const name of callees) if (name !== "" && text.includes(name)) return;
+				return false;
+			},
+			JSXAttribute(node) {
+				if (node.name.type !== "JSXIdentifier" || !attributes.has(node.name.name) || !node.value) return;
+				if (node.value.type === "Literal" && typeof node.value.value === "string") checkStringNode(node.value, node.value.value);
+				else if (node.value.type === "JSXExpressionContainer") checkExpression(node.value.expression);
+			},
+			CallExpression(node) {
+				let name: string | null = null;
+				if (node.callee.type === "Identifier") name = node.callee.name;
+				else if (node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.property.type === "Identifier") name = node.callee.property.name;
+				if (name === null || !callees.has(name)) return;
+				for (const arg of node.arguments) if (arg.type === "Literal" || arg.type === "TemplateLiteral") checkExpression(arg);
+			},
+		};
+	},
+});

package/src/tailwind/worker.ts

@@ -0,0 +1,38 @@
+import { __unstable__loadDesignSystem } from "@tailwindcss/node";
+import { runAsWorker } from "synckit";
+
+interface LoadJob {
+	type: "load";
+	key: string;
+	cssContent: string;
+	base: string;
+}
+
+interface CanonicalizeJob {
+	type: "canonicalize";
+	key: string;
+	candidates: Array<string>;
+	rem: number;
+}
+
+type WorkerJob = LoadJob | CanonicalizeJob;
+
+interface DesignSystem {
+	canonicalizeCandidates(candidates: Array<string>, options: { rem: number }): Array<string>;
+}
+
+const designSystems = new Map<string, DesignSystem>();
+
+runAsWorker(async (job: WorkerJob) => {
+	if (job.type === "load") {
+		designSystems.set(
+			job.key,
+			await __unstable__loadDesignSystem(job.cssContent, { base: job.base }) as DesignSystem,
+		);
+		return { ok: true };
+	}
+
+	const designSystem = designSystems.get(job.key);
+	if (!designSystem) throw new Error(`Tailwind design system not loaded for "${job.key}"`);
+	return designSystem.canonicalizeCandidates(job.candidates, { rem: job.rem });
+});