@codefast/cli 0.3.12 → 0.3.13-canary.1

package/dist/lib/arrange/domain/constants.mjs

@@ -0,0 +1,169 @@
+//#region src/lib/arrange/domain/constants.ts
+/** Analyze report: long literal threshold (token count). */
+const LONG_STRING_TOKEN_THRESHOLD = 18;
+/**
+* Minimum token count for a string to be considered a candidate for grouping
+* in the apply/preview pipeline. Intentionally much lower than
+* {@link LONG_STRING_TOKEN_THRESHOLD} (analyze only).
+*/
+const APPLY_MIN_TOKENS = 2;
+/**
+* Minimum tokens a group must have to stand alone before singleton-merging.
+* Set to 2 so single-token groups are not collapsed into unrelated buckets by the merger.
+*/
+const MIN_GROUP_TOKENS = 2;
+/** Dynamic max groups clamp: base bound. */
+const MAX_GROUPS_BASE = 4;
+/** Dynamic max groups clamp: upper cap. */
+const MAX_GROUPS_CAP = 24;
+/**
+* Extra slots so a few state / aria groups do not force `capGroups` to merge
+* unrelated buckets (e.g. `bg-border` + `outline-hidden`).
+*/
+const MAX_GROUPS_HEADROOM = 2;
+/** Maximum findings printed per category in the analyze report. */
+const MAX_REPORT_LINES = 40;
+/** Maximum recursion depth when traversing `tv()` object literals. */
+const MAX_OBJECT_DEPTH = 12;
+/** Maximum depth when peeling conditional / parens / arrays inside `cn(...)` args. */
+const MAX_CLASS_EXPR_DEPTH = 12;
+/**
+* Maximum variant-stripping passes in {@link stripVariants}.
+* Real-world Tailwind stacks rarely exceed 4–5 segments (e.g. `@md/sidebar:group-hover:dark:focus-visible:`);
+* 12 is a conservative safety cap that prevents runaway loops on malformed input.
+*/
+const MAX_STRIP_VARIANT_PASSES = 12;
+/**
+* Passed when optional `knownBindings` is missing — size 0 disables matching
+* for `cn` / `tv` identifier resolution.
+*/
+const EMPTY_CN_TV_BINDINGS = /* @__PURE__ */ new Set();
+/**
+* Bucket sort order — **render pipeline** (lower → earlier in output).
+* Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow
+* → Typography → Composite → Motion → Starting → Behavior → State (variants) → Selector variants.
+*/
+const BUCKET_ORDER = {
+	existence: 0,
+	position: 1,
+	layout: 2,
+	sizing: 3,
+	spacing: 4,
+	shape: 5,
+	background: 6,
+	shadow: 7,
+	typography: 8,
+	composite: 9,
+	motion: 10,
+	starting: 11,
+	behavior: 12,
+	state: 13,
+	selector: 14,
+	other: 15,
+	arbitrary: 16
+};
+/**
+* Compatible bucket **pairs** — two adjacent tokens whose buckets appear in the same
+* `Set` may stay in one `cn()` string chunk. Compatibility is **not transitive**: there is
+* no `{position, sizing}` pair, so `fixed inset-0` and `overflow-auto` become **separate**
+* literals unless **layout** tokens sit between them in sorted order; then
+* `position↔layout` and `layout↔sizing` each justify one hop and the whole “box in flow”
+* (place + tracks + scrollport) stays in one chunk — co-located because they jointly define
+* stacking and scroll behavior for the same surface.
+*/
+const COMPATIBLE_BUCKET_SETS = [
+	new Set(["existence", "position"]),
+	new Set(["existence", "layout"]),
+	new Set(["position", "layout"]),
+	new Set(["layout", "sizing"]),
+	new Set(["shape", "shadow"]),
+	new Set(["background", "shadow"]),
+	new Set(["background", "typography"]),
+	new Set(["layout", "typography"]),
+	new Set(["sizing", "typography"]),
+	new Set(["motion", "behavior"]),
+	new Set(["motion", "starting"]),
+	new Set(["composite", "motion"]),
+	new Set(["sizing", "composite"]),
+	new Set(["sizing", "spacing"])
+];
+/**
+* Responsive / variant prefix — Tailwind v4 aware.
+*
+* v3: sm: md: … — v4: @sm:, @min-[600px]:, @[480px]:, named @md/sidebar:,
+* viewport md/sidebar:, min-[100px]: / max-[100px]:, …
+*/
+const RESPONSIVE_PREFIX = /^(?:@(?:min|max)-\[[^\]]+\]:|@\[[^\]]+\]:|@(?:[a-z0-9]+(?:-[a-z0-9]+)*)(?:\/[a-z][a-z0-9-]*)?:|(?:max-|min-)?(?:sm|md|lg|xl|2xl|3xl)(?:\/[a-z][a-z0-9-]*)?:|(?:max-|min-)\[[^\]]+\]:)/;
+/** State variant stems — hoisted to module scope (not recreated per call). */
+const STATE_PREFIXES = new Set([
+	"hover",
+	"focus",
+	"focus-within",
+	"focus-visible",
+	"active",
+	"visited",
+	"link",
+	"any-link",
+	"disabled",
+	"enabled",
+	"checked",
+	"indeterminate",
+	"required",
+	"optional",
+	"valid",
+	"invalid",
+	"in-range",
+	"out-of-range",
+	"read-only",
+	"read-write",
+	"placeholder-shown",
+	"default",
+	"autofill",
+	"open",
+	"closed",
+	"first",
+	"last",
+	"only",
+	"odd",
+	"even",
+	"first-of-type",
+	"last-of-type",
+	"only-of-type",
+	"first-child",
+	"last-child",
+	"only-child",
+	"empty",
+	"target",
+	"group",
+	"peer",
+	"aria",
+	"data",
+	"dark",
+	"light",
+	"supports",
+	"motion-reduce",
+	"motion-safe",
+	"print",
+	"screen",
+	"ltr",
+	"rtl",
+	"not",
+	"has",
+	"in",
+	"nth",
+	"file",
+	"selection",
+	"marker",
+	"placeholder",
+	"before",
+	"after",
+	"first-line",
+	"first-letter",
+	"backdrop",
+	"details-content",
+	"popover-open"
+]);
+/** Default directory for arrange analyze/preview/apply when no target is passed. */
+const DEFAULT_ARRANGE_TARGET = "packages/ui/src/components";
+//#endregion
+export { APPLY_MIN_TOKENS, BUCKET_ORDER, COMPATIBLE_BUCKET_SETS, DEFAULT_ARRANGE_TARGET, EMPTY_CN_TV_BINDINGS, LONG_STRING_TOKEN_THRESHOLD, MAX_CLASS_EXPR_DEPTH, MAX_GROUPS_BASE, MAX_GROUPS_CAP, MAX_GROUPS_HEADROOM, MAX_OBJECT_DEPTH, MAX_REPORT_LINES, MAX_STRIP_VARIANT_PASSES, MIN_GROUP_TOKENS, RESPONSIVE_PREFIX, STATE_PREFIXES };

package/dist/lib/arrange/domain/errors.mjs

@@ -0,0 +1,19 @@
+//#region src/lib/arrange/domain/errors.ts
+/**
+* Structured errors for the arrange CLI library (throw from lib; handle exit in commands).
+*/
+const ArrangeErrorCode = {
+	TARGET_NOT_FOUND: "TARGET_NOT_FOUND",
+	INVALID_INPUT: "INVALID_INPUT",
+	INTERNAL: "INTERNAL"
+};
+var ArrangeError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "ArrangeError";
+		this.code = code;
+	}
+};
+//#endregion
+export { ArrangeError, ArrangeErrorCode };

package/dist/lib/arrange/domain/grouping.mjs

@@ -0,0 +1,235 @@
+import { BUCKET_ORDER } from "./constants.mjs";
+import { bucketsCompatible, bucketsMergeCompatible, classifyToken, compositeSecondaryOrder, selectorKey, stateKey, stripVariants, tokenizeClassString } from "./tokenizer.mjs";
+//#region src/lib/arrange/domain/grouping.ts
+function isVariantKeyedBucket(bucket) {
+	return bucket === "selector" || bucket === "state" || bucket === "starting";
+}
+function variantGroupKey(bucket, classToken) {
+	return bucket === "selector" ? selectorKey(classToken) : stateKey(classToken);
+}
+/**
+* True when `staticLiteralTexts` carries the **same partition** of Tailwind tokens as
+* `suggestedGroups` from {@link suggestCnGroups}, ignoring order of arguments and
+* order of tokens within each chunk.
+*/
+function areCnTailwindPartitionsEquivalent(staticLiteralTexts, suggestedGroups) {
+	const partitionSignatures = (chunks) => chunks.map((chunk) => {
+		const classTokens = tokenizeClassString(chunk);
+		return classTokens.length === 0 ? "" : [...classTokens].sort().join(" ");
+	}).filter((s) => s.length > 0).sort((a, b) => a.localeCompare(b));
+	const staticPartitionSigs = partitionSignatures(staticLiteralTexts);
+	const suggestedPartitionSigs = partitionSignatures(suggestedGroups);
+	if (staticPartitionSigs.length !== suggestedPartitionSigs.length) return false;
+	for (let i = 0; i < staticPartitionSigs.length; i++) if (staticPartitionSigs[i] !== suggestedPartitionSigs[i]) return false;
+	return true;
+}
+/** Dominant bucket of a whitespace-delimited class group (for merge heuristics). */
+function dominantBucketOfGroup(groupStr) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const classToken of tokenizeClassString(groupStr)) {
+		const tokenBucket = classifyToken(classToken);
+		counts.set(tokenBucket, (counts.get(tokenBucket) ?? 0) + 1);
+	}
+	let best = "other";
+	let bestN = 0;
+	for (const [bucket, count] of counts) {
+		if (count > bestN) {
+			best = bucket;
+			bestN = count;
+			continue;
+		}
+		if (count === bestN && BUCKET_ORDER[bucket] < BUCKET_ORDER[best]) best = bucket;
+	}
+	return best;
+}
+/** Dynamic cap: more tokens → allow more groups, within [BASE, CAP]. */
+function dynamicMaxGroups(tokenCount) {
+	const byTokens = Math.ceil(tokenCount / 2) + 2;
+	return Math.max(4, Math.min(24, byTokens));
+}
+/**
+* Merge singleton groups (< MIN_GROUP_TOKENS tokens) into their nearest
+* neighbour. Prefers merging toward a bucket-compatible neighbor.
+*
+* Loop termination: each iteration either splices one element (shrinking the
+* array, guaranteeing progress) or finds no singleton that can merge and exits
+* via `changed = false`. Two mutually-incompatible singletons both hit
+* `continue` and `changed` stays false, so the loop exits without spinning.
+*/
+function mergeSingletons(groups) {
+	if (groups.length <= 1) return groups;
+	const result = [...groups];
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (let i = 0; i < result.length; i++) if (tokenizeClassString(result[i]).length < 2) {
+			if (result.length === 1) break;
+			const myBucket = dominantBucketOfGroup(result[i]);
+			const prevCompat = i > 0 && bucketsMergeCompatible(myBucket, dominantBucketOfGroup(result[i - 1]));
+			const nextCompat = i < result.length - 1 && bucketsMergeCompatible(myBucket, dominantBucketOfGroup(result[i + 1]));
+			let mergeDir;
+			if (nextCompat && !prevCompat) mergeDir = "forward";
+			else if (prevCompat && !nextCompat) mergeDir = "backward";
+			else if (prevCompat && nextCompat) mergeDir = i < result.length - 1 ? "forward" : "backward";
+			else continue;
+			if (mergeDir === "forward") result[i + 1] = result[i] + " " + result[i + 1];
+			else result[i - 1] = result[i - 1] + " " + result[i];
+			result.splice(i, 1);
+			changed = true;
+			break;
+		}
+	}
+	return result;
+}
+/** Tie-break when two merge candidates are both {@link bucketsMergeCompatible} (same bucket or COMPATIBLE_BUCKET_SETS). */
+function capMergePenalty(leftBucket, rightBucket) {
+	if (leftBucket === rightBucket) return 0;
+	if (bucketsCompatible(leftBucket, rightBucket)) return 0;
+	return 500;
+}
+/**
+* Merge adjacent groups until total count ≤ maxGroups.
+* Only merges pairs allowed by {@link bucketsMergeCompatible} — never glues incompatible
+* buckets (which previously defaulted to penalty 0 and merged layout+state when over cap).
+*
+* Complexity: O(n²) in the number of groups — each merge pass scans all remaining adjacent
+* pairs. In practice `n` is bounded by {@link MAX_GROUPS_CAP} (24) and typical class strings
+* are well below that, so this is not a concern for the current usage pattern. If this ever
+* runs in a high-throughput batch mode, consider a priority-queue approach.
+*/
+function capGroups(groups, maxGroups) {
+	const result = [...groups];
+	const lengths = result.map((groupStr) => tokenizeClassString(groupStr).length);
+	while (result.length > maxGroups) {
+		const mergePairCandidates = [];
+		for (let i = 0; i < result.length - 1; i++) {
+			const dominantLeft = dominantBucketOfGroup(result[i]);
+			const dominantRight = dominantBucketOfGroup(result[i + 1]);
+			if (!bucketsMergeCompatible(dominantLeft, dominantRight)) continue;
+			mergePairCandidates.push({
+				i,
+				size: lengths[i] + lengths[i + 1],
+				penalty: capMergePenalty(dominantLeft, dominantRight)
+			});
+		}
+		if (mergePairCandidates.length === 0) break;
+		let best = mergePairCandidates[0];
+		for (const candidate of mergePairCandidates) if (candidate.penalty < best.penalty || candidate.penalty === best.penalty && candidate.size < best.size) best = candidate;
+		const bestIdx = best.i;
+		result[bestIdx] = result[bestIdx] + " " + result[bestIdx + 1];
+		lengths[bestIdx] = lengths[bestIdx] + lengths[bestIdx + 1];
+		result.splice(bestIdx + 1, 1);
+		lengths.splice(bestIdx + 1, 1);
+	}
+	return result;
+}
+/**
+* If a chunk is **only** bare `ease-*` timing (Motion), buffer it and prepend to the **first**
+* **later** chunk that is predominantly `state` **and** contains some `animate-*` utility —
+* skipping intermediate `state` chunks (`sm:…`, `group-data-[…]:…`, etc.) that sit between
+* `ease-ui` and `data-open:animate-*`. If no such chunk exists, the ease chunk is left as-is.
+*/
+function mergeEaseTimingIntoFollowingAnimatedState(groups) {
+	const result = [...groups];
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (let i = 0; i < result.length; i++) {
+			if (!chunkIsOnlyEaseTimingMotion(result[i])) continue;
+			const easeStr = result[i];
+			let target = -1;
+			for (let j = i + 1; j < result.length; j++) {
+				if (dominantBucketOfGroup(result[j]) !== "state") continue;
+				if (!tokenizeClassString(result[j]).some((classToken) => /^animate/.test(stripVariants(classToken)))) continue;
+				target = j;
+				break;
+			}
+			if (target === -1) continue;
+			result[target] = `${easeStr} ${result[target]}`.trim();
+			result.splice(i, 1);
+			changed = true;
+			break;
+		}
+	}
+	return result;
+}
+function chunkIsOnlyEaseTimingMotion(groupStr) {
+	const classTokens = tokenizeClassString(groupStr);
+	if (classTokens.length === 0) return false;
+	return classTokens.every((classToken) => classifyToken(classToken) === "motion" && /^ease-/.test(stripVariants(classToken)));
+}
+function suggestCnGroups(classString) {
+	const tokens = tokenizeClassString(classString);
+	if (tokens.length === 0) return [];
+	const classified = tokens.map((classToken, index) => ({
+		classToken,
+		bucket: classifyToken(classToken),
+		index
+	}));
+	classified.sort((left, right) => {
+		const bucketOrderDiff = BUCKET_ORDER[left.bucket] - BUCKET_ORDER[right.bucket];
+		if (bucketOrderDiff !== 0) return bucketOrderDiff;
+		if (left.bucket === "composite" && right.bucket === "composite") {
+			const compositeOrderDiff = compositeSecondaryOrder(stripVariants(left.classToken)) - compositeSecondaryOrder(stripVariants(right.classToken));
+			if (compositeOrderDiff !== 0) return compositeOrderDiff;
+		}
+		return left.index - right.index;
+	});
+	const rawGroups = [];
+	/** Bucket of the last token already placed in the current run (pairwise compat with `COMPATIBLE_BUCKET_SETS`). */
+	let lastBucketInRun = null;
+	let currentStateKey = null;
+	let currentTokens = [];
+	const flush = () => {
+		if (currentTokens.length > 0) {
+			rawGroups.push(currentTokens.join(" "));
+			currentTokens = [];
+		}
+		lastBucketInRun = null;
+		currentStateKey = null;
+	};
+	for (const { classToken, bucket: tokenBucket } of classified) {
+		if (lastBucketInRun === null) {
+			lastBucketInRun = tokenBucket;
+			currentStateKey = isVariantKeyedBucket(tokenBucket) ? variantGroupKey(tokenBucket, classToken) : null;
+			currentTokens.push(classToken);
+			continue;
+		}
+		if (isVariantKeyedBucket(tokenBucket)) {
+			const key = variantGroupKey(tokenBucket, classToken);
+			if (currentStateKey !== null && key !== currentStateKey) {
+				flush();
+				lastBucketInRun = tokenBucket;
+				currentStateKey = key;
+				currentTokens.push(classToken);
+				continue;
+			}
+		}
+		if (!bucketsCompatible(tokenBucket, lastBucketInRun)) {
+			flush();
+			lastBucketInRun = tokenBucket;
+			currentStateKey = isVariantKeyedBucket(tokenBucket) ? variantGroupKey(tokenBucket, classToken) : null;
+			currentTokens.push(classToken);
+			continue;
+		}
+		if (isVariantKeyedBucket(tokenBucket)) currentStateKey = variantGroupKey(tokenBucket, classToken);
+		else if (currentStateKey !== null) currentStateKey = null;
+		lastBucketInRun = tokenBucket;
+		currentTokens.push(classToken);
+	}
+	flush();
+	const withEaseMerged = mergeEaseTimingIntoFollowingAnimatedState(mergeSingletons(rawGroups));
+	return capGroups(withEaseMerged, Math.max(dynamicMaxGroups(tokens.length), withEaseMerged.length));
+}
+/**
+* One label per suggested group: a single bucket name, or `mixed:a+b` when that chunk
+* spans multiple Tailwind buckets (matches `codefast arrange group` stdout).
+*/
+function summarizeGroupBucketLabels(groups) {
+	return groups.map((g) => {
+		const uniq = new Set(tokenizeClassString(g).map(classifyToken));
+		return uniq.size === 1 ? [...uniq][0] : `mixed:${[...uniq].sort().join("+")}`;
+	});
+}
+//#endregion
+export { areCnTailwindPartitionsEquivalent, capGroups, mergeEaseTimingIntoFollowingAnimatedState, mergeSingletons, suggestCnGroups, summarizeGroupBucketLabels };

package/dist/lib/arrange/domain/imports.mjs

@@ -0,0 +1,54 @@
+import ts from "typescript";
+//#region src/lib/arrange/domain/imports.ts
+function sourceFileImportsCn(sf) {
+	for (const statement of sf.statements) {
+		if (!ts.isImportDeclaration(statement) || !statement.importClause) continue;
+		const clause = statement.importClause;
+		if (clause.name?.text === "cn") return true;
+		if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+			for (const importedBinding of clause.namedBindings.elements) if (importedBinding.name.text === "cn") return true;
+		}
+	}
+	return false;
+}
+/**
+* Resolve the module specifier used when injecting a `cn` import into a file.
+*/
+function cnModuleSpecifierForFile(filePath, override) {
+	if (override) return override;
+	return "@codefast/tailwind-variants";
+}
+function findImportDeclarationFromModule(sf, moduleSpecifier) {
+	for (const statement of sf.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		const spec = statement.moduleSpecifier;
+		if (ts.isStringLiteral(spec) && spec.text === moduleSpecifier) return statement;
+	}
+}
+function ensureCnImport(sourceText, filePath, cnImportOverride) {
+	const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+	if (sourceFileImportsCn(sf)) return sourceText;
+	const moduleSpecifier = cnModuleSpecifierForFile(filePath, cnImportOverride);
+	const decl = findImportDeclarationFromModule(sf, moduleSpecifier);
+	if (decl?.importClause && !decl.importClause.isTypeOnly && decl.importClause.namedBindings && ts.isNamedImports(decl.importClause.namedBindings)) {
+		const elements = decl.importClause.namedBindings.elements;
+		if (elements.length > 0) {
+			const pos = elements[0].getStart(sf);
+			return `${sourceText.slice(0, pos)}cn, ${sourceText.slice(pos)}`;
+		}
+	}
+	const importLine = `import { cn } from "${moduleSpecifier}";`;
+	let firstImport = -1;
+	for (const statement of sf.statements) if (ts.isImportDeclaration(statement)) {
+		firstImport = statement.getStart(sf);
+		break;
+	}
+	const useClient = /^["']use client["'];?\s*\r?\n/.exec(sourceText);
+	let insertAt;
+	if (useClient) insertAt = useClient[0].length;
+	else if (firstImport !== -1) insertAt = firstImport;
+	else insertAt = 0;
+	return `${sourceText.slice(0, insertAt)}${importLine}\n${sourceText.slice(insertAt)}`;
+}
+//#endregion
+export { cnModuleSpecifierForFile, ensureCnImport };