@codefast/cli 0.3.7-canary.0 → 0.3.12

package/dist/lib/arrange/ast/targets.js

@@ -0,0 +1,143 @@
+import ts from "typescript";
+import { APPLY_MIN_TOKENS } from "#lib/arrange/constants";
+import { areCnTailwindPartitionsEquivalent, suggestCnGroups, summarizeGroupBucketLabels, } from "#lib/arrange/grouping";
+import { escapeTsStringLiteralContent, formatArray, formatJsxCnAttributeValue, } from "#lib/arrange/formatters";
+import { tokenizeClassString } from "#lib/arrange/tokenizer";
+import { isUnsafeLiteralForCnStyleApplySplit } from "#lib/arrange/ast/collectors-cn";
+import { jsxClassNameStaticLiteral } from "#lib/arrange/ast/collectors-jsx";
+import { collectGroupableStringNodes, slotClassString } from "#lib/arrange/ast/collectors-tv";
+import { indentOfLineContaining } from "#lib/arrange/ast/utils";
+export function targetReplaceStart(target) {
+    if (target.kind === "cnArg") {
+        return target.item.cnCall
+            ? target.item.cnCall.getStart(target.item.sf)
+            : target.item.node.getStart(target.item.sf);
+    }
+    return target.valueNode.getStart(target.sf);
+}
+export function collectLongJsxClassNameTargets(sf) {
+    const results = [];
+    const visit = (node) => {
+        if (ts.isJsxAttribute(node)) {
+            const parsed = jsxClassNameStaticLiteral(node);
+            if (parsed && tokenizeClassString(parsed.lit.text).length >= APPLY_MIN_TOKENS) {
+                results.push({
+                    kind: "jsxClassName",
+                    sf,
+                    lit: parsed.lit,
+                    valueNode: parsed.valueNode,
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return results;
+}
+export function collectGroupTargets(sf, filePath) {
+    const cnPart = collectGroupableStringNodes(sf).map((item) => ({ kind: "cnArg", item }));
+    if (!filePath.endsWith(".tsx"))
+        return cnPart;
+    return [...cnPart, ...collectLongJsxClassNameTargets(sf)];
+}
+export function formatCnCallReplacement(item, sourceText, withClassName) {
+    const call = item.cnCall;
+    const sf = item.sf;
+    const baseIndent = indentOfLineContaining(sourceText, call.getStart(sf));
+    const argIndent = `${baseIndent}  `;
+    const dynamicArgTexts = [];
+    for (const arg of call.arguments) {
+        const isSimpleStatic = (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) &&
+            !isUnsafeLiteralForCnStyleApplySplit(arg);
+        if (!isSimpleStatic) {
+            dynamicArgTexts.push(sourceText.slice(arg.getStart(sf), arg.getEnd()));
+        }
+    }
+    const pool = slotClassString(item);
+    const groups = pool.trim() ? suggestCnGroups(pool) : [];
+    const allArgs = [];
+    if (groups.length > 1) {
+        for (const group of groups) {
+            allArgs.push(`${argIndent}"${escapeTsStringLiteralContent(group)}"`);
+        }
+    }
+    else if (groups.length === 1) {
+        allArgs.push(`${argIndent}"${escapeTsStringLiteralContent(groups[0])}"`);
+    }
+    for (const dyn of dynamicArgTexts) {
+        allArgs.push(`${argIndent}${dyn}`);
+    }
+    if (withClassName) {
+        allArgs.push(`${argIndent}className`);
+    }
+    // Keep formatter behavior explicit: multiline cn() calls with multiple args use trailing comma.
+    const commaAfterLastArg = allArgs.length > 1;
+    const argLines = allArgs.map((argLine, lineIndex) => lineIndex < allArgs.length - 1 || commaAfterLastArg ? `${argLine},` : `${argLine}`);
+    return `cn(\n${argLines.join("\n")}\n${baseIndent})`;
+}
+export function planGroupEditForTarget(target, textAfterUnwrap, withClassName) {
+    if (target.kind === "jsxClassName") {
+        const groups = suggestCnGroups(target.lit.text);
+        if (groups.length <= 1)
+            return undefined;
+        const start = target.valueNode.getStart(target.sf);
+        const end = target.valueNode.getEnd();
+        const replacement = formatJsxCnAttributeValue(groups, textAfterUnwrap, start);
+        return {
+            start,
+            end,
+            replacement,
+            bucketSummary: summarizeGroupBucketLabels(groups),
+            jsxCn: true,
+            lineSf: target.sf,
+            reportNode: target.lit,
+            label: "JSX className",
+        };
+    }
+    const pool = slotClassString(target.item);
+    const groups = suggestCnGroups(pool);
+    if (groups.length <= 1)
+        return undefined;
+    if (areCnTailwindPartitionsEquivalent(target.item.nodes.map((node) => node.text), groups)) {
+        return undefined;
+    }
+    if (!target.item.cnCall) {
+        const firstNode = target.item.node;
+        const parentArray = target.item.nodes.length > 1 && ts.isArrayLiteralExpression(firstNode.parent)
+            ? firstNode.parent
+            : null;
+        const start = parentArray
+            ? parentArray.getStart(target.item.sf)
+            : firstNode.getStart(target.item.sf);
+        const end = parentArray ? parentArray.getEnd() : firstNode.getEnd();
+        const baseIndent = indentOfLineContaining(textAfterUnwrap, start);
+        const replacement = formatArray(groups)
+            .split("\n")
+            .map((line, lineIndex) => (lineIndex === 0 ? line : `${baseIndent}${line}`))
+            .join("\n");
+        return {
+            start,
+            end,
+            replacement,
+            bucketSummary: summarizeGroupBucketLabels(groups),
+            jsxCn: false,
+            lineSf: target.item.sf,
+            reportNode: firstNode,
+            label: target.item.isTvContext ? "tv" : "cn",
+        };
+    }
+    const call = target.item.cnCall;
+    const start = call.getStart(target.item.sf);
+    const end = call.getEnd();
+    const replacement = formatCnCallReplacement(target.item, textAfterUnwrap, withClassName);
+    return {
+        start,
+        end,
+        replacement,
+        bucketSummary: summarizeGroupBucketLabels(groups),
+        jsxCn: false,
+        lineSf: target.item.sf,
+        reportNode: target.item.node,
+        label: target.item.isTvContext ? "tv" : "cn",
+    };
+}

package/dist/lib/arrange/ast/utils.d.ts

@@ -0,0 +1,36 @@
+import ts from "typescript";
+/** Known module specifiers that export `cn` / `tv`. */
+export declare const KNOWN_CN_TV_MODULES: Set<string>;
+/**
+ * True for typical shadcn-style re-exports: `./utils`, `@/lib/utils`, `…/utils/…`,
+ * or a dedicated `cn.ts` / `cn.tsx` module.
+ */
+export declare function moduleLooksLikeCnTvReexport(mod: string): boolean;
+/**
+ * Build a set of local binding names that are imported from a known cn/tv
+ * module in `sf`.
+ */
+export declare function buildKnownCnTvBindings(sf: ts.SourceFile): Set<string>;
+/**
+ * Returns true when `expr` is an identifier whose name matches `name` AND
+ * that name is listed in `knownBindings` from a recognized import.
+ */
+export declare function isCnOrTvIdentifier(expr: ts.Expression, name: "cn" | "tv", knownBindings?: Set<string>): boolean;
+export declare function propertyAssignmentNameText(prop: ts.PropertyAssignment): string | undefined;
+export declare function lineOf(sf: ts.SourceFile, node: ts.Node): number;
+/**
+ * Returns only the leading whitespace (tabs / spaces) of the line containing
+ * `pos`.
+ */
+export declare function indentOfLineContaining(source: string, pos: number): string;
+export declare function applyEditsDescending(sourceText: string, edits: ReadonlyArray<{
+    start: number;
+    end: number;
+    replacement: string;
+}>): string;
+/**
+ * Replace `cn(...)` nested in `tv({...})` with a plain string (one arg) or a string
+ * array (multiple args). Returns undefined when there are zero arguments.
+ */
+export declare function unwrapCnInsideTvCallReplacement(call: ts.CallExpression, sourceText: string, sf: ts.SourceFile): string | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/arrange/ast/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/lib/arrange/ast/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,aAU9B,CAAC;AAEH;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,CAqBrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,EAAE,CAAC,UAAU,EACnB,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,aAAa,GAAE,GAAG,CAAC,MAAM,CAAwB,GAChD,OAAO,CAOT;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAI1F;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAoB1E;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,GACxE,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,EAAE,CAAC,UAAU,GAChB,MAAM,GAAG,SAAS,CAoBpB"}

package/dist/lib/arrange/ast/utils.js

@@ -0,0 +1,138 @@
+import ts from "typescript";
+import { EMPTY_CN_TV_BINDINGS } from "#lib/arrange/constants";
+/** Known module specifiers that export `cn` / `tv`. */
+export const KNOWN_CN_TV_MODULES = new Set([
+    "@codefast/tailwind-variants",
+    "clsx",
+    "class-variance-authority",
+    // Backward compatibility only: keep detection for existing user code that still imports
+    // from "tailwind-variants"; new code should prefer "@codefast/tailwind-variants".
+    "tailwind-variants",
+    "#lib/utils",
+    "~/lib/utils",
+    "@/lib/utils",
+]);
+/**
+ * True for typical shadcn-style re-exports: `./utils`, `@/lib/utils`, `…/utils/…`,
+ * or a dedicated `cn.ts` / `cn.tsx` module.
+ */
+export function moduleLooksLikeCnTvReexport(mod) {
+    const norm = mod.replace(/\\/g, "/");
+    if (/(?:^|[./])utils(?:\/|$)/.test(norm))
+        return true;
+    if (/\/utils\//.test(norm) || /\/utils$/.test(norm))
+        return true;
+    if (/(?:^|\/)cn\.tsx?$/.test(norm))
+        return true;
+    return false;
+}
+/**
+ * Build a set of local binding names that are imported from a known cn/tv
+ * module in `sf`.
+ */
+export function buildKnownCnTvBindings(sf) {
+    const bindings = new Set();
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt) || !stmt.importClause)
+            continue;
+        if (stmt.importClause.isTypeOnly)
+            continue;
+        const spec = stmt.moduleSpecifier;
+        if (!ts.isStringLiteral(spec))
+            continue;
+        const mod = spec.text;
+        const isKnown = KNOWN_CN_TV_MODULES.has(mod);
+        if (!isKnown && !moduleLooksLikeCnTvReexport(mod))
+            continue;
+        const clause = stmt.importClause;
+        if (clause.name)
+            bindings.add(clause.name.text);
+        if (!clause.namedBindings)
+            continue;
+        if (ts.isNamedImports(clause.namedBindings)) {
+            for (const el of clause.namedBindings.elements)
+                bindings.add(el.name.text);
+            continue;
+        }
+        bindings.add(clause.namedBindings.name.text);
+    }
+    return bindings;
+}
+/**
+ * Returns true when `expr` is an identifier whose name matches `name` AND
+ * that name is listed in `knownBindings` from a recognized import.
+ */
+export function isCnOrTvIdentifier(expr, name, knownBindings = EMPTY_CN_TV_BINDINGS) {
+    if (knownBindings.size === 0)
+        return false;
+    if (ts.isIdentifier(expr) && expr.text === name)
+        return knownBindings.has(expr.text);
+    if (ts.isPropertyAccessExpression(expr) && expr.name.text === name) {
+        return ts.isIdentifier(expr.expression) && knownBindings.has(expr.expression.text);
+    }
+    return false;
+}
+export function propertyAssignmentNameText(prop) {
+    if (ts.isIdentifier(prop.name))
+        return prop.name.text;
+    if (ts.isStringLiteral(prop.name))
+        return prop.name.text;
+    return undefined;
+}
+export function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+/**
+ * Returns only the leading whitespace (tabs / spaces) of the line containing
+ * `pos`.
+ */
+export function indentOfLineContaining(source, pos) {
+    const searchPos = Math.max(0, Math.min(pos, source.length));
+    const prevLineBreak = Math.max(source.lastIndexOf("\n", searchPos - 1), source.lastIndexOf("\r", searchPos - 1));
+    const lineStart = prevLineBreak === -1 ? 0 : prevLineBreak + 1;
+    let lineEnd = source.length;
+    for (let i = lineStart; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "\n" || ch === "\r") {
+            lineEnd = i;
+            break;
+        }
+    }
+    const line = source.slice(lineStart, lineEnd);
+    const indentMatch = /^[\t ]*/.exec(line);
+    return indentMatch?.[0] ?? "";
+}
+export function applyEditsDescending(sourceText, edits) {
+    const sorted = [...edits].sort((editA, editB) => editB.start - editA.start);
+    let out = sourceText;
+    for (const edit of sorted) {
+        out = out.slice(0, edit.start) + edit.replacement + out.slice(edit.end);
+    }
+    return out;
+}
+/**
+ * Replace `cn(...)` nested in `tv({...})` with a plain string (one arg) or a string
+ * array (multiple args). Returns undefined when there are zero arguments.
+ */
+export function unwrapCnInsideTvCallReplacement(call, sourceText, sf) {
+    const args = call.arguments;
+    if (args.length === 0)
+        return undefined;
+    const baseIndent = indentOfLineContaining(sourceText, call.getStart(sf));
+    const innerIndent = `${baseIndent}  `;
+    if (args.length === 1) {
+        const firstArg = args[0];
+        return sourceText.slice(firstArg.getStart(sf), firstArg.getEnd());
+    }
+    const lines = ["["];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const piece = sourceText.slice(arg.getStart(sf), arg.getEnd());
+        // Trailing comma on every element — intentional (Prettier-compatible style;
+        // keeps array diffs clean when arguments are later added or removed).
+        const comma = i < args.length - 1 || args.length > 1 ? "," : "";
+        lines.push(`${innerIndent}${piece}${comma}`);
+    }
+    lines.push(`${baseIndent}]`);
+    return lines.join("\n");
+}

package/dist/lib/arrange/constants.d.ts

@@ -0,0 +1,68 @@
+import type { Bucket } from "#lib/arrange/types";
+/** Analyze report: long literal threshold (token count). */
+export declare 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).
+ */
+export declare 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.
+ */
+export declare const MIN_GROUP_TOKENS = 2;
+/** Dynamic max groups clamp: base bound. */
+export declare const MAX_GROUPS_BASE = 4;
+/** Dynamic max groups clamp: upper cap. */
+export declare 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`).
+ */
+export declare const MAX_GROUPS_HEADROOM = 2;
+/** Maximum findings printed per category in the analyze report. */
+export declare const MAX_REPORT_LINES = 40;
+/** Maximum recursion depth when traversing `tv()` object literals. */
+export declare const MAX_OBJECT_DEPTH = 12;
+/** Maximum depth when peeling conditional / parens / arrays inside `cn(...)` args. */
+export declare 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.
+ */
+export declare const MAX_STRIP_VARIANT_PASSES = 12;
+/**
+ * Passed when optional `knownBindings` is missing — size 0 disables matching
+ * for `cn` / `tv` identifier resolution.
+ */
+export declare const EMPTY_CN_TV_BINDINGS: Set<string>;
+/**
+ * Bucket sort order — **render pipeline** (lower → earlier in output).
+ * Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow
+ * → Typography → Composite → Motion → Starting → Behavior → Conditions (state).
+ */
+export declare const BUCKET_ORDER: Record<Bucket, number>;
+/**
+ * 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.
+ */
+export declare const COMPATIBLE_BUCKET_SETS: ReadonlyArray<ReadonlySet<Bucket>>;
+/**
+ * Responsive / variant prefix — Tailwind v4 aware.
+ *
+ * v3: sm: md: … — v4: @sm:, @min-[600px]:, @[480px]:, named @md/sidebar:,
+ * viewport md/sidebar:, min-[100px]: / max-[100px]:, …
+ */
+export declare const RESPONSIVE_PREFIX: RegExp;
+/** State variant stems — hoisted to module scope (not recreated per call). */
+export declare const STATE_PREFIXES: Set<string>;
+/** Default directory for arrange analyze/preview/apply when no target is passed. */
+export declare const DEFAULT_ARRANGE_TARGET = "packages/ui/src/components";
+//# sourceMappingURL=constants.d.ts.map

package/dist/lib/arrange/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/lib/arrange/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,4DAA4D;AAC5D,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,4CAA4C;AAC5C,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,2CAA2C;AAC3C,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,oBAAoB,aAAoB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiB/C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,WAAW,CAAC,MAAM,CAAC,CA6BrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAC2J,CAAC;AAE1L,8EAA8E;AAC9E,eAAO,MAAM,cAAc,aAmEzB,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,+BAA+B,CAAC"}

package/dist/lib/arrange/constants.js

@@ -0,0 +1,179 @@
+/** Analyze report: long literal threshold (token count). */
+export 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).
+ */
+export 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.
+ */
+export const MIN_GROUP_TOKENS = 2;
+/** Dynamic max groups clamp: base bound. */
+export const MAX_GROUPS_BASE = 4;
+/** Dynamic max groups clamp: upper cap. */
+export 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`).
+ */
+export const MAX_GROUPS_HEADROOM = 2;
+/** Maximum findings printed per category in the analyze report. */
+export const MAX_REPORT_LINES = 40;
+/** Maximum recursion depth when traversing `tv()` object literals. */
+export const MAX_OBJECT_DEPTH = 12;
+/** Maximum depth when peeling conditional / parens / arrays inside `cn(...)` args. */
+export 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.
+ */
+export const MAX_STRIP_VARIANT_PASSES = 12;
+/**
+ * Passed when optional `knownBindings` is missing — size 0 disables matching
+ * for `cn` / `tv` identifier resolution.
+ */
+export const EMPTY_CN_TV_BINDINGS = new Set();
+/**
+ * Bucket sort order — **render pipeline** (lower → earlier in output).
+ * Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow
+ * → Typography → Composite → Motion → Starting → Behavior → Conditions (state).
+ */
+export 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,
+    other: 14,
+    arbitrary: 15,
+};
+/**
+ * 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.
+ */
+export const COMPATIBLE_BUCKET_SETS = [
+    // existence + position: named container / group / peer context edited next to inset & z-index.
+    new Set(["existence", "position"]),
+    // existence + layout: `group/cmd` + `flex …` are one template row (context + grid/flex).
+    new Set(["existence", "layout"]),
+    // position + layout: `fixed inset-0` + `grid` describe the same stacking + track shell.
+    new Set(["position", "layout"]),
+    // layout + sizing: `grid` + `overflow-auto` / min size are one scrollport / track concern.
+    new Set(["layout", "sizing"]),
+    // shape + shadow: radius/border + shadow/outline overlay are one “chrome” literal in UIs.
+    new Set(["shape", "shadow"]),
+    // background + shadow: fill + depth (card surface) without splitting noise across args.
+    new Set(["background", "shadow"]),
+    // background + typography: destructive buttons etc. (`bg-*` + `text-*` on the same control).
+    new Set(["background", "typography"]),
+    // layout + typography: title rows (`flex` + `text-sm`) in one literal when adjacent in sort order.
+    new Set(["layout", "typography"]),
+    // sizing + typography: chart shell (`aspect-video` + `text-xs`) before scoped `[&_…]` state.
+    new Set(["sizing", "typography"]),
+    // motion + behavior: `transition-*` with `pointer-events-*` / `select-*` on the same surface.
+    new Set(["motion", "behavior"]),
+    // motion + starting: `transition` beside `starting:*` for coordinated enter/exit motion.
+    new Set(["motion", "starting"]),
+    // composite + motion: transforms then transitions (`-translate-*` + `transition-*` + `ease-*`).
+    new Set(["composite", "motion"]),
+    // sizing + composite: width/position utilities with transforms in one interaction block.
+    new Set(["sizing", "composite"]),
+    // sizing + spacing: width utilities with padding on the same slot (`w-auto` + `px-3`).
+    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]:, …
+ */
+export 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). */
+export 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. */
+export const DEFAULT_ARRANGE_TARGET = "packages/ui/src/components";

package/dist/lib/arrange/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Structured errors for the arrange CLI library (throw from lib; handle exit in commands).
+ */
+export declare const ArrangeErrorCode: {
+    readonly TARGET_NOT_FOUND: "TARGET_NOT_FOUND";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly INTERNAL: "INTERNAL";
+};
+export type ArrangeErrorCode = (typeof ArrangeErrorCode)[keyof typeof ArrangeErrorCode];
+export declare class ArrangeError extends Error {
+    readonly code: ArrangeErrorCode;
+    constructor(code: ArrangeErrorCode, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/arrange/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/arrange/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,gBAAgB;aAC3B,gBAAgB,EAAE,kBAAkB;aACpC,aAAa,EAAE,eAAe;aAC9B,QAAQ,EAAE,UAAU;CACZ,CAAC;AAGX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAExF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAEhC,YAAY,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAI1E;CACF"}

package/dist/lib/arrange/errors.js

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

package/dist/lib/arrange/formatters.d.ts

@@ -0,0 +1,16 @@
+export declare function escapeTsStringLiteralContent(group: string): string;
+/**
+ * Multiline fragment for use *inside* an existing `cn(...)` — replaces one
+ * string argument with several, without producing `cn(cn(...))`.
+ */
+export declare function formatCnArguments(groups: string[], options?: {
+    indent?: string;
+    commaAfterLastGroup?: boolean;
+    trailingClassName?: boolean;
+}): string;
+export declare function formatCnCall(groups: string[], options?: {
+    trailingClassName?: boolean;
+}): string;
+export declare function formatArray(groups: string[]): string;
+export declare function formatJsxCnAttributeValue(groups: string[], source: string, valueNodeStart: number): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/lib/arrange/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../../src/lib/arrange/formatters.ts"],"names":[],"mappings":"AAEA,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GACA,MAAM,CAaR;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAahG;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,MAAM,CAQR"}