@codefast/cli 0.3.5 → 0.3.12

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"}

package/dist/lib/arrange/formatters.js

@@ -0,0 +1,57 @@
+import { indentOfLineContaining } from "#lib/arrange/ast/utils";
+export function escapeTsStringLiteralContent(group) {
+    return group.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+/**
+ * Multiline fragment for use *inside* an existing `cn(...)` — replaces one
+ * string argument with several, without producing `cn(cn(...))`.
+ */
+export function formatCnArguments(groups, options) {
+    const indent = options?.indent ?? "  ";
+    const commaAfterLast = options?.commaAfterLastGroup ?? options?.trailingClassName ?? false;
+    const lines = [];
+    for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        const comma = i < groups.length - 1 || commaAfterLast ? "," : "";
+        lines.push(`${indent}"${escapeTsStringLiteralContent(group)}"${comma}`);
+    }
+    if (options?.trailingClassName) {
+        lines.push(`${indent}className,`);
+    }
+    return lines.join("\n");
+}
+export function formatCnCall(groups, options) {
+    const lines = ["cn("];
+    const commaOnEachStringLine = groups.length > 1 || Boolean(options?.trailingClassName);
+    for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        const comma = commaOnEachStringLine ? "," : "";
+        lines.push(`  "${escapeTsStringLiteralContent(group)}"${comma}`);
+    }
+    if (options?.trailingClassName) {
+        lines.push("  className,");
+    }
+    lines.push(")");
+    return lines.join("\n");
+}
+export function formatArray(groups) {
+    const lines = ["["];
+    for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        // Trailing comma on every element when there are multiple entries — matches
+        // Prettier's default array formatting and keeps diffs minimal on insertion.
+        const comma = i < groups.length - 1 || groups.length > 1 ? "," : "";
+        lines.push(`  "${escapeTsStringLiteralContent(group)}"${comma}`);
+    }
+    lines.push("]");
+    return lines.join("\n");
+}
+export function formatJsxCnAttributeValue(groups, source, valueNodeStart) {
+    const baseIndent = indentOfLineContaining(source, valueNodeStart);
+    const argIndent = `${baseIndent}  `;
+    const inner = formatCnArguments(groups, {
+        indent: argIndent,
+        commaAfterLastGroup: groups.length > 1,
+    });
+    return `{cn(\n${inner}\n${baseIndent})}`;
+}

package/dist/lib/arrange/group-file.d.ts

@@ -0,0 +1,4 @@
+import type { CliFs, CliLogger } from "#lib/infra/fs-contract";
+import type { ArrangeGroupFileOptions, GroupFileResult } from "#lib/arrange/types";
+export declare function groupFile(filePath: string, options: ArrangeGroupFileOptions, fs: CliFs, logger: CliLogger): GroupFileResult;
+//# sourceMappingURL=group-file.d.ts.map

package/dist/lib/arrange/group-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-file.d.ts","sourceRoot":"","sources":["../../../src/lib/arrange/group-file.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EAEhB,MAAM,oBAAoB,CAAC;AAiH5B,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,EAChC,EAAE,EAAE,KAAK,EACT,MAAM,EAAE,SAAS,GAChB,eAAe,CA8FjB"}

package/dist/lib/arrange/group-file.js

@@ -0,0 +1,115 @@
+import ts from "typescript";
+import { applyEditsDescending, buildKnownCnTvBindings, lineOf, unwrapCnInsideTvCallReplacement, } from "#lib/arrange/ast/utils";
+import { listAllCnCallsInsideTvInSourceFile } from "#lib/arrange/ast/collectors-tv";
+import { collectGroupTargets, planGroupEditForTarget, targetReplaceStart, } from "#lib/arrange/ast/targets";
+import { ensureCnImport } from "#lib/arrange/imports";
+function printGroupFilePreview(logger, args) {
+    const { out } = logger;
+    const { filePath, reportTotal, cnInTvNoReplacement, cnInTvCalls, unwrapReplacementByCall, sourceText, sf, unwrapEdits, plannedGroupEdits, } = args;
+    let header = `\n── ${filePath} (${reportTotal} site(s)`;
+    if (cnInTvNoReplacement > 0) {
+        header += `; plus ${cnInTvNoReplacement} cn() inside tv left unchanged (0 args)`;
+    }
+    header += `) ──`;
+    out(header);
+    for (const call of cnInTvCalls) {
+        const replacement = unwrapReplacementByCall.get(call);
+        if (replacement === undefined) {
+            out(`  Line ${lineOf(sf, call)} [tv ⊃ cn]: cn(...) has no arguments — skipped`);
+            continue;
+        }
+        const start = call.getStart(sf);
+        const end = call.getEnd();
+        if (sourceText.slice(start, end) === replacement)
+            continue;
+        out(`  Line ${lineOf(sf, call)} [tv ⊃ cn → string/array]:`);
+        out(`  ${replacement.split("\n").join("\n  ")}`);
+    }
+    if (unwrapEdits.length > 0 && plannedGroupEdits.length > 0) {
+        out("  ([cn] / [tv] / [JSX className] lines below reflect content after unwrap of cn inside tv.)");
+    }
+    for (const plan of plannedGroupEdits) {
+        out(`  Line ${lineOf(plan.lineSf, plan.reportNode)} [${plan.label}]:`);
+        out(`  ${plan.replacement.split("\n").join("\n  ")}`);
+        out(`  // Buckets: ${JSON.stringify(plan.bucketSummary)}`);
+    }
+}
+function applyGroupFileWrites(filePath, options, fs, logger, unwrapEdits, textAfterUnwrap, plannedGroupEdits, cnInTvNoReplacement) {
+    const groupEdits = plannedGroupEdits.map((p) => ({
+        start: p.start,
+        end: p.end,
+        replacement: p.replacement,
+        jsxCn: p.jsxCn,
+    }));
+    const touchedJsxCn = groupEdits.some((e) => e.jsxCn);
+    let newText = groupEdits.length > 0 ? applyEditsDescending(textAfterUnwrap, groupEdits) : textAfterUnwrap;
+    const changed = unwrapEdits.length + groupEdits.length;
+    if (changed > 0) {
+        if (touchedJsxCn) {
+            newText = ensureCnImport(newText, filePath, options.cnImport);
+        }
+        fs.writeFileSync(filePath, newText, "utf8");
+    }
+    return { filePath, totalFound: changed + cnInTvNoReplacement, changed };
+}
+export function groupFile(filePath, options, fs, logger) {
+    const sourceText = fs.readFileSync(filePath, "utf8");
+    const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const knownBindings = buildKnownCnTvBindings(sf);
+    const cnInTvCalls = listAllCnCallsInsideTvInSourceFile(sf, knownBindings);
+    const unwrapPlans = cnInTvCalls
+        .map((call) => {
+        const replacement = unwrapCnInsideTvCallReplacement(call, sourceText, sf);
+        if (replacement === undefined)
+            return undefined;
+        return { start: call.getStart(sf), end: call.getEnd(), replacement, call };
+    })
+        .filter((e) => e !== undefined);
+    const unwrapReplacementByCall = new Map(unwrapPlans.map((p) => [p.call, p.replacement]));
+    const unwrapEdits = unwrapPlans.filter((e) => sourceText.slice(e.start, e.end) !== e.replacement);
+    const textAfterUnwrap = unwrapEdits.length > 0 ? applyEditsDescending(sourceText, unwrapEdits) : sourceText;
+    // The first parse (`sf`) intentionally targets the original source text to discover unwrap edits.
+    // After `applyEditsDescending` runs, node offsets from that AST no longer match the updated text.
+    // Re-parse `textAfterUnwrap` so group-target traversal uses valid positions; reusing the first AST
+    // would produce incorrect start/end offsets for subsequent grouping edits.
+    const sfGrouped = ts.createSourceFile(filePath, textAfterUnwrap, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const groupTargets = collectGroupTargets(sfGrouped, filePath);
+    const cnInTvNoReplacement = cnInTvCalls.length - unwrapPlans.length;
+    const sortedTargets = [...groupTargets].sort((a, b) => targetReplaceStart(b) - targetReplaceStart(a));
+    const plannedGroupEdits = [];
+    for (const t of sortedTargets) {
+        const plan = planGroupEditForTarget(t, textAfterUnwrap, options.withClassName);
+        if (plan === undefined)
+            continue;
+        if (textAfterUnwrap.slice(plan.start, plan.end) === plan.replacement)
+            continue;
+        plannedGroupEdits.push(plan);
+    }
+    const editSitesCount = unwrapEdits.length + plannedGroupEdits.length;
+    const reportTotal = editSitesCount + cnInTvNoReplacement;
+    if (cnInTvCalls.length === 0 && groupTargets.length === 0) {
+        return { filePath, totalFound: 0, changed: 0 };
+    }
+    if (!options.write) {
+        if (editSitesCount === 0 && cnInTvNoReplacement === 0) {
+            return { filePath, totalFound: 0, changed: 0 };
+        }
+        printGroupFilePreview(logger, {
+            filePath,
+            reportTotal,
+            cnInTvNoReplacement,
+            cnInTvCalls,
+            unwrapReplacementByCall,
+            sourceText,
+            sf,
+            unwrapEdits,
+            plannedGroupEdits,
+        });
+        return {
+            filePath,
+            totalFound: reportTotal,
+            changed: 0,
+        };
+    }
+    return applyGroupFileWrites(filePath, options, fs, logger, unwrapEdits, textAfterUnwrap, plannedGroupEdits, cnInTvNoReplacement);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export declare function areCnTailwindPartitionsEquivalent(staticLiteralTexts: string[], suggestedGroups: string[]): boolean;
+/**
+ * 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.
+ */
+export declare function mergeSingletons(groups: string[]): string[];
+/**
+ * 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.
+ */
+export declare function capGroups(groups: string[], maxGroups: number): string[];
+/**
+ * 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.
+ */
+export declare function mergeEaseTimingIntoFollowingAnimatedState(groups: string[]): string[];
+export declare function suggestCnGroups(classString: string): string[];
+/**
+ * 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).
+ */
+export declare function summarizeGroupBucketLabels(groups: string[]): string[];
+//# sourceMappingURL=grouping.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.d.ts","sourceRoot":"","sources":["../../../src/lib/arrange/grouping.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,kBAAkB,EAAE,MAAM,EAAE,EAC5B,eAAe,EAAE,MAAM,EAAE,GACxB,OAAO,CAiBT;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAyC1D;AASD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAmCvE;AAED;;;;;GAKG;AACH,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAwBpF;AAQD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA8E7D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKrE"}