@codefast/cli 0.10.0 → 0.11.0

package/dist/arrange/inspect/output.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { LONG_STRING_TOKEN_THRESHOLD, MAX_REPORT_LINES } from "#/arrange/domain/constants";
+import { logger } from "#/core/logger";
+/**
+ * Presents the human-readable summary of an `arrange inspect` report.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function presentAnalyzeReport(resolvedTargetPath, report) {
+    logger.out(`Path: ${path.resolve(resolvedTargetPath)}`);
+    logger.out(`.ts/.tsx files: ${report.files}`);
+    logger.out(`cn(...) call sites: ${report.cnCallExpressions}`);
+    logger.out(`tv(...) call sites: ${report.tvCallExpressions}`);
+    logger.out(`\nLong cn(...) string literals (≥${LONG_STRING_TOKEN_THRESHOLD} tokens — consider splitting arguments): ${report.longCnStringLiterals.length}`);
+    for (const findingEntry of report.longCnStringLiterals.slice(0, MAX_REPORT_LINES)) {
+        logger.out(`  ${findingEntry.file}:${findingEntry.line}  (${findingEntry.tokenCount} tokens)  ${findingEntry.preview}`);
+    }
+    if (report.longCnStringLiterals.length > MAX_REPORT_LINES) {
+        logger.out(`  … and ${report.longCnStringLiterals.length - MAX_REPORT_LINES} more`);
+    }
+    logger.out(`\nLong tv({...}) string literals in base/variants/… (≥${LONG_STRING_TOKEN_THRESHOLD} tokens): ${report.longTvStringLiterals.length}`);
+    for (const findingEntry of report.longTvStringLiterals.slice(0, MAX_REPORT_LINES)) {
+        logger.out(`  ${findingEntry.file}:${findingEntry.line}  (${findingEntry.tokenCount} tokens)  ${findingEntry.preview}`);
+    }
+    if (report.longTvStringLiterals.length > MAX_REPORT_LINES) {
+        logger.out(`  … and ${report.longTvStringLiterals.length - MAX_REPORT_LINES} more`);
+    }
+    logger.out(`\nJSX className="..." or className={'...'} (static strings, ≥${LONG_STRING_TOKEN_THRESHOLD} tokens): ${report.longJsxClassNameLiterals.length}`);
+    for (const findingEntry of report.longJsxClassNameLiterals.slice(0, MAX_REPORT_LINES)) {
+        logger.out(`  ${findingEntry.file}:${findingEntry.line}  (${findingEntry.tokenCount} tokens)  ${findingEntry.preview}`);
+    }
+    if (report.longJsxClassNameLiterals.length > MAX_REPORT_LINES) {
+        logger.out(`  … and ${report.longJsxClassNameLiterals.length - MAX_REPORT_LINES} more`);
+    }
+    logger.out(`\ncn(...) nested inside tv({...}) (prefer a string or array — preview/apply can rewrite): ${report.cnInsideTvCalls.length}`);
+    for (const findingEntry of report.cnInsideTvCalls.slice(0, MAX_REPORT_LINES)) {
+        logger.out(`  ${findingEntry.file}:${findingEntry.line}  (${findingEntry.argCount} args)  ${findingEntry.preview}`);
+    }
+    if (report.cnInsideTvCalls.length > MAX_REPORT_LINES) {
+        logger.out(`  … and ${report.cnInsideTvCalls.length - MAX_REPORT_LINES} more`);
+    }
+}

package/dist/arrange/{analyze.d.ts → inspect/run.d.ts}

@@ -1,10 +1,10 @@
 import type { AnalyzeReport } from "#/arrange/domain/types";
 import { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
  * Scans a directory's arrange targets and returns the accumulated analyze report.
  *
  * @since 0.3.16-canary.0
  */
-export declare function analyzeDirectory(fs: FilesystemPort, analyzeRootPath: string): Result<AnalyzeReport, AppError>;
+export declare function runArrangeInspect(fs: Filesystem, analyzeRootPath: string): Result<AnalyzeReport, AppError>;

package/dist/arrange/{analyze.js → inspect/run.js}

@@ -1,4 +1,4 @@
-import { accumulateAnalyzeReportForSourceFile, createEmptyAnalyzeReport } from "#/arrange/domain/analyze-service";
+import { accumulateAnalyzeReportForSourceFile, createEmptyAnalyzeReport, } from "#/arrange/inspect/domain/analyze-service";
 import { scanArrangeTargets } from "#/arrange/scan-target";
 import { parseDomainSourceFile } from "#/arrange/source-parse";
 import { AppError } from "#/core/errors";
@@ -9,7 +9,7 @@ import { err, ok } from "#/core/result";
  *
  * @since 0.3.16-canary.0
  */
-export function analyzeDirectory(fs, analyzeRootPath) {
+export function runArrangeInspect(fs, analyzeRootPath) {
     const report = createEmptyAnalyzeReport();
     try {
         const files = scanArrangeTargets(fs, analyzeRootPath);

package/dist/arrange/{workspace.d.ts → prepare.d.ts}

@@ -1,13 +1,13 @@
 import type { ArrangeTargetWorkspaceAndConfig } from "#/arrange/domain/types";
 import { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
  * Resolves the arrange target, repo root, and loaded config an arrange run needs.
  *
  * @since 0.3.16-canary.0
  */
-export declare function prepareArrangeWorkspace(fs: FilesystemPort, args: {
+export declare function prepareArrangeWorkspace(fs: Filesystem, args: {
     readonly currentWorkingDirectory: string;
     readonly rawTarget: string | undefined;
 }): Promise<Result<ArrangeTargetWorkspaceAndConfig, AppError>>;

package/dist/arrange/{workspace.js → prepare.js}

@@ -1,9 +1,8 @@
 import { resolveArrangeTargetPath } from "#/arrange/resolve-target";
+import { resolveProjectRootResult } from "#/core/cli/resolve-root";
 import { loadCodefastConfig } from "#/core/config";
 import { AppError } from "#/core/errors";
-import { messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
-import { resolveProjectRoot } from "#/core/workspace/resolver";
 /**
  * Resolves the arrange target, repo root, and loaded config an arrange run needs.
  *
@@ -17,13 +16,11 @@ export async function prepareArrangeWorkspace(fs, args) {
     if (!fs.existsSync(resolvedTarget)) {
         return err(new AppError("NOT_FOUND", `Not found: ${resolvedTarget}`));
     }
-    let rootDir;
-    try {
-        rootDir = resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir;
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    const rootOutcome = resolveProjectRootResult(fs, args.currentWorkingDirectory);
+    if (!rootOutcome.ok) {
+        return rootOutcome;
     }
+    const rootDir = rootOutcome.value;
     const loadedOutcome = await loadCodefastConfig(rootDir, fs);
     if (!loadedOutcome.ok) {
         return loadedOutcome;

package/dist/arrange/regroup/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+/**
+ * Machine-readable `arrange` run summary for `--json`, minus the non-serializable preview plans.
+ *
+ * @since 0.11.0
+ */
+export declare function formatArrangeJsonOutput(result: ArrangeRunResult, write: boolean): string;
+/**
+ * Exit `1` when an after-write hook failed, `0` otherwise.
+ *
+ * @since 0.11.0
+ */
+export declare function exitCodeForArrangeResult(result: ArrangeRunResult): number;

package/dist/arrange/regroup/cli-result.js

@@ -0,0 +1,23 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#/core/exit-codes";
+/**
+ * Machine-readable `arrange` run summary for `--json`, minus the non-serializable preview plans.
+ *
+ * @since 0.11.0
+ */
+export function formatArrangeJsonOutput(result, write) {
+    const { previewPlans: _plans, ...serializableResult } = result;
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.hookError === null,
+        write,
+        result: serializableResult,
+    });
+}
+/**
+ * Exit `1` when an after-write hook failed, `0` otherwise.
+ *
+ * @since 0.11.0
+ */
+export function exitCodeForArrangeResult(result) {
+    return result.hookError !== null ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}

package/dist/arrange/regroup/cli-schema.d.ts

@@ -0,0 +1,20 @@
+import * as z from "zod";
+/**
+ * The request payload for a top-level `arrange` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeRunRequest = {
+    rootDir: string;
+    targetPath: string;
+    write: boolean;
+    withClassName?: boolean | undefined;
+    cnImport?: string | undefined;
+    config?: unknown;
+};
+/**
+ * The `zod` schema validating an `arrange` run request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const arrangeRunRequestSchema: z.ZodType<ArrangeRunRequest>;

package/dist/arrange/regroup/cli-schema.js

@@ -0,0 +1,14 @@
+import * as z from "zod";
+/**
+ * The `zod` schema validating an `arrange` run request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export const arrangeRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    write: z.boolean(),
+    withClassName: z.boolean().optional(),
+    cnImport: z.string().optional(),
+    config: z.unknown().optional(),
+});

package/dist/arrange/regroup/output.d.ts

@@ -0,0 +1,14 @@
+import type { GroupFileWorkPlan } from "#/arrange/domain/grouping-service";
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+/**
+ * Presents the totals and follow-up hints for an `arrange` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentArrangeResult(result: ArrangeRunResult, write: boolean): void;
+/**
+ * Presents the per-file preview of a work plan's unwrap and grouping edits.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentGroupFilePreviewFromWork(work: GroupFileWorkPlan): void;

package/dist/arrange/regroup/output.js

@@ -0,0 +1,72 @@
+import { lineOf } from "#/arrange/domain/ast/helpers";
+import { logger } from "#/core/logger";
+/**
+ * Presents the totals and follow-up hints for an `arrange` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function presentArrangeResult(result, write) {
+    logger.out(`\nTotal: ${result.filePaths.length} file(s), ${result.totalFound} site(s) (cn/tv/JSX className) to review.`);
+    if (write) {
+        logger.out(`Applied: ${result.totalChanged} site(s) updated.`);
+    }
+    else {
+        logger.out(`(Re-run without --dry-run to write changes, or "pnpm cli:arrange" / "pnpm exec codefast arrange")`);
+    }
+    const shouldShowCascadeHint = write ? result.totalChanged > 0 : result.totalFound > 0;
+    if (shouldShowCascadeHint) {
+        logger.out("Note: class order may change across concern groups — smoke-test the UI if you rely on cascade order.");
+    }
+    if (result.hookError !== null) {
+        logger.err(result.hookError);
+    }
+}
+/**
+ * Presents the per-file preview of a work plan's unwrap and grouping edits.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function presentGroupFilePreviewFromWork(work) {
+    presentGroupFilePreviewBody({
+        filePath: work.filePath,
+        reportTotal: work.reportTotal,
+        cnInTvNoReplacement: work.cnInTvNoReplacement,
+        cnInTvCalls: work.cnInTvCalls,
+        unwrapReplacementByCall: work.unwrapReplacementByCall,
+        sourceText: work.sourceText,
+        domainSf: work.domainSfForLineNumbers,
+        unwrapEdits: work.unwrapEdits,
+        plannedGroupEdits: work.plannedGroupEdits,
+    });
+}
+function presentGroupFilePreviewBody(args) {
+    const { filePath, reportTotal, cnInTvNoReplacement, cnInTvCalls, unwrapReplacementByCall, sourceText, domainSf, unwrapEdits, plannedGroupEdits, } = args;
+    let header = `\n── ${filePath} (${reportTotal} site(s)`;
+    if (cnInTvNoReplacement > 0) {
+        header += `; plus ${cnInTvNoReplacement} cn() inside tv left unchanged (0 args)`;
+    }
+    header += `) ──`;
+    logger.out(header);
+    for (const call of cnInTvCalls) {
+        const replacement = unwrapReplacementByCall.get(call);
+        if (replacement === undefined) {
+            logger.out(`  Line ${lineOf(domainSf, call)} [tv ⊃ cn]: cn(...) has no arguments — skipped`);
+            continue;
+        }
+        const start = call.pos;
+        const end = call.end;
+        if (sourceText.slice(start, end) === replacement) {
+            continue;
+        }
+        logger.out(`  Line ${lineOf(domainSf, call)} [tv ⊃ cn → string/array]:`);
+        logger.out(`  ${replacement.split("\n").join("\n  ")}`);
+    }
+    if (unwrapEdits.length > 0 && plannedGroupEdits.length > 0) {
+        logger.out("  ([cn] / [tv] / [JSX className] lines below reflect content after unwrap of cn inside tv.)");
+    }
+    for (const plan of plannedGroupEdits) {
+        logger.out(`  Line ${lineOf(plan.lineSf, plan.reportNode)} [${plan.label}]:`);
+        logger.out(`  ${plan.replacement.split("\n").join("\n  ")}`);
+        logger.out(`  // Buckets: ${JSON.stringify(plan.bucketSummary)}`);
+    }
+}

package/dist/arrange/{process-file.d.ts → regroup/process-file.d.ts}

@@ -1,11 +1,11 @@
 import type { ArrangeGroupFileOptions, GroupFileResult } from "#/arrange/domain/types";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 /**
  * Runs the grouping pipeline on one file — preview or write — and returns its per-file result.
  *
  * @since 0.3.16-canary.0
  */
-export declare function processArrangeGroupFile(fs: FilesystemPort, args: {
+export declare function processArrangeGroupFile(fs: Filesystem, args: {
     readonly filePath: string;
     readonly options: ArrangeGroupFileOptions;
 }): GroupFileResult;

package/dist/arrange/{sync.d.ts → regroup/run.d.ts}

@@ -1,11 +1,11 @@
-import type { ArrangeSyncRunRequest } from "#/arrange/cli-schema";
 import type { ArrangeRunResult } from "#/arrange/domain/types";
+import type { ArrangeRunRequest } from "#/arrange/regroup/cli-schema";
 import type { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
  * Runs the grouping pipeline over every target file and returns the aggregated result.
  *
  * @since 0.3.16-canary.0
  */
-export declare function runArrangeSync(fs: FilesystemPort, request: ArrangeSyncRunRequest): Promise<Result<ArrangeRunResult, AppError>>;
+export declare function runArrange(fs: Filesystem, request: ArrangeRunRequest): Promise<Result<ArrangeRunResult, AppError>>;

package/dist/arrange/{sync.js → regroup/run.js}

@@ -1,4 +1,4 @@
-import { processArrangeGroupFile } from "#/arrange/process-file";
+import { processArrangeGroupFile } from "#/arrange/regroup/process-file";
 import { scanArrangeTargets } from "#/arrange/scan-target";
 import { messageFrom } from "#/core/errors";
 import { ok } from "#/core/result";
@@ -19,7 +19,7 @@ async function runOnAfterWriteHook(hook, modifiedFiles) {
  *
  * @since 0.3.16-canary.0
  */
-export async function runArrangeSync(fs, request) {
+export async function runArrange(fs, request) {
     const filePaths = scanArrangeTargets(fs, request.targetPath);
     const modifiedFiles = [];
     const previewPlans = [];

package/dist/arrange/resolve-target.d.ts

@@ -1,10 +1,10 @@
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 /**
  * Resolves the arrange target to a canonical path, defaulting to the nearest package directory.
  *
  * @since 0.3.16-canary.0
  */
-export declare function resolveArrangeTargetPath(fs: FilesystemPort, args: {
+export declare function resolveArrangeTargetPath(fs: Filesystem, args: {
     readonly currentWorkingDirectory: string;
     readonly rawTarget: string | undefined;
 }): string;

package/dist/arrange/scan-target.d.ts

@@ -1,7 +1,7 @@
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 /**
  * Lists the files an arrange run visits — a directory's non-test `.ts`/`.tsx` files, or the single target.
  *
  * @since 0.3.16-canary.0
  */
-export declare function scanArrangeTargets(fs: FilesystemPort, targetPath: string): Array<string>;
+export declare function scanArrangeTargets(fs: Filesystem, targetPath: string): Array<string>;

package/dist/arrange/simplify/cli-result.d.ts

@@ -0,0 +1,7 @@
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+/**
+ * Machine-readable `arrange simplify` summary for `--json`.
+ *
+ * @since 0.11.0
+ */
+export declare function formatArrangeSimplifyJsonOutput(result: ArrangeRunResult, write: boolean): string;

package/dist/arrange/simplify/cli-result.js

@@ -0,0 +1,8 @@
+/**
+ * Machine-readable `arrange simplify` summary for `--json`.
+ *
+ * @since 0.11.0
+ */
+export function formatArrangeSimplifyJsonOutput(result, write) {
+    return JSON.stringify({ schemaVersion: 1, ok: true, write, result });
+}

package/dist/arrange/simplify/cli-schema.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+/**
+ * The request payload for an `arrange simplify` run.
+ *
+ * @since 0.11.0
+ */
+export type ArrangeSimplifyRunRequest = {
+    targetPath: string;
+    write: boolean;
+    foldVariantClassName?: boolean | undefined;
+};
+/**
+ * The `zod` schema validating an `arrange simplify` run request.
+ *
+ * @since 0.11.0
+ */
+export declare const arrangeSimplifyRunRequestSchema: z.ZodType<ArrangeSimplifyRunRequest>;

package/dist/arrange/simplify/cli-schema.js

@@ -0,0 +1,11 @@
+import * as z from "zod";
+/**
+ * The `zod` schema validating an `arrange simplify` run request.
+ *
+ * @since 0.11.0
+ */
+export const arrangeSimplifyRunRequestSchema = z.object({
+    targetPath: z.string().min(1),
+    write: z.boolean(),
+    foldVariantClassName: z.boolean().optional(),
+});

package/dist/arrange/simplify/fold-targets.d.ts

@@ -0,0 +1,13 @@
+/** Collects cn() calls whose override classes can fold into a variant function's `className` option. */
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+import type { PlannedSimplifyEdit } from "#/arrange/domain/ast/simplify-targets";
+import type { FileClassNameProbe } from "#/arrange/simplify/variant-classname-probe";
+/**
+ * Collects `className` fold edits for every foldable `cn(variant({…}), …)` call in a source file.
+ *
+ * @remarks The type server is loaded lazily via `resolveFileProbe` — only once a syntactic candidate
+ * exists — so files with no foldable call never pay for a type query.
+ *
+ * @since 0.11.0
+ */
+export declare function collectClassNameFoldTargets(sourceFile: DomainSourceFile, resolveFileProbe: () => FileClassNameProbe | null): Array<PlannedSimplifyEdit>;

package/dist/arrange/simplify/fold-targets.js

@@ -0,0 +1,139 @@
+/** Collects cn() calls whose override classes can fold into a variant function's `className` option. */
+import { forEachDomainChild, isDomainCallExpression, isDomainIdentifier, isDomainObjectLiteralExpression, isDomainPropertyAccessExpression, isDomainPropertyAssignment, isDomainTailwindClassLiteral, } from "#/arrange/domain/ast/ast-node";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier, propertyAssignmentNameText } from "#/arrange/domain/ast/helpers";
+import { escapeTsStringLiteralContent } from "#/arrange/domain/source-text-formatters";
+/** Groups a run of trailing cn() arguments, coalescing adjacent static literals into one piece. */
+function coalesceTrailingArgs(args, sourceText) {
+    const pieces = [];
+    for (const arg of args) {
+        if (isDomainTailwindClassLiteral(arg)) {
+            const last = pieces.at(-1);
+            if (last?.kind === "static") {
+                last.texts.push(arg.text);
+            }
+            else {
+                pieces.push({ kind: "static", texts: [arg.text] });
+            }
+        }
+        else {
+            pieces.push({ kind: "dynamic", src: sourceText.slice(arg.pos, arg.end) });
+        }
+    }
+    return pieces;
+}
+/** Renders one class piece as either a quoted merged string or the raw source of a dynamic argument. */
+function renderPiece(piece) {
+    return piece.kind === "static" ? `"${escapeTsStringLiteralContent(piece.texts.join(" ").trim())}"` : piece.src;
+}
+/** The source offset of the callee's name — an identifier or the property of a member access. */
+function calleeNameOffset(expression) {
+    if (isDomainIdentifier(expression)) {
+        return expression.pos;
+    }
+    if (isDomainPropertyAccessExpression(expression)) {
+        return expression.name.pos;
+    }
+    return null;
+}
+/** True when the object literal is a plain bag of assignments that does not already set `className`/`class`. */
+function objectAcceptsClassNameFold(objectArg) {
+    for (const property of objectArg.properties) {
+        // A spread or shorthand parses as a non-assignment node — its `className` cannot be reasoned about.
+        if (!isDomainPropertyAssignment(property)) {
+            return false;
+        }
+        const name = propertyAssignmentNameText(property);
+        if (name === "className" || name === "class") {
+            return false;
+        }
+    }
+    return true;
+}
+/** Builds a fold candidate from syntax alone — no type server — or `null` when the shape is not foldable. */
+function buildFoldCandidate(cnCall, sourceText) {
+    const args = cnCall.arguments;
+    const variantCall = args[0];
+    if (args.length < 2 || variantCall === undefined || !isDomainCallExpression(variantCall)) {
+        return null;
+    }
+    const objectArg = variantCall.arguments[0];
+    if (variantCall.arguments.length !== 1 ||
+        objectArg === undefined ||
+        !isDomainObjectLiteralExpression(objectArg) ||
+        !objectAcceptsClassNameFold(objectArg)) {
+        return null;
+    }
+    const calleeOffset = calleeNameOffset(variantCall.expression);
+    if (calleeOffset === null) {
+        return null;
+    }
+    const pieces = coalesceTrailingArgs(args.slice(1), sourceText);
+    if (pieces.length === 0) {
+        return null;
+    }
+    // A dynamic override or more than one piece becomes an array, so the option must accept one; a
+    // single static override stays a scalar string. Types decide whether either shape is legal.
+    const needsArray = pieces.length > 1 || pieces.some((piece) => piece.kind === "dynamic");
+    const rendered = pieces.map(renderPiece);
+    const classNameValue = pieces.length > 1 ? `[${rendered.join(", ")}]` : rendered[0];
+    // Splice `className` in right after the last property (or just inside an empty object), keeping the
+    // object's original text — a trailing comma or line comment would break a re-serialized `{ … }`.
+    const lastProperty = objectArg.properties.at(-1);
+    const insertOffset = lastProperty ? lastProperty.end : objectArg.pos + 1;
+    const insertion = lastProperty ? `, className: ${classNameValue}` : ` className: ${classNameValue} `;
+    const replacement = sourceText.slice(variantCall.pos, insertOffset) + insertion + sourceText.slice(insertOffset, variantCall.end);
+    return {
+        calleeOffset,
+        needsArray,
+        edit: {
+            start: cnCall.pos,
+            end: cnCall.end,
+            replacement,
+            label: "cn-fold-classname",
+        },
+    };
+}
+/**
+ * Collects `className` fold edits for every foldable `cn(variant({…}), …)` call in a source file.
+ *
+ * @remarks The type server is loaded lazily via `resolveFileProbe` — only once a syntactic candidate
+ * exists — so files with no foldable call never pay for a type query.
+ *
+ * @since 0.11.0
+ */
+export function collectClassNameFoldTargets(sourceFile, resolveFileProbe) {
+    const sourceText = sourceFile.text;
+    const knownBindings = buildKnownCnTvBindings(sourceFile);
+    const candidates = [];
+    const visit = (node) => {
+        if (isDomainCallExpression(node) && isCnOrTvIdentifier(node.expression, "cn", knownBindings)) {
+            const candidate = buildFoldCandidate(node, sourceText);
+            if (candidate) {
+                candidates.push(candidate);
+            }
+        }
+        forEachDomainChild(node, visit);
+    };
+    for (const statement of sourceFile.statements) {
+        visit(statement);
+    }
+    if (candidates.length === 0) {
+        return [];
+    }
+    const fileProbe = resolveFileProbe();
+    if (!fileProbe) {
+        return [];
+    }
+    const results = [];
+    for (const candidate of candidates) {
+        const acceptance = fileProbe.classNameAcceptance(candidate.calleeOffset);
+        if (!acceptance) {
+            continue;
+        }
+        if (candidate.needsArray ? !acceptance.acceptsArray : !acceptance.acceptsString) {
+            continue;
+        }
+        results.push(candidate.edit);
+    }
+    return results;
+}

package/dist/arrange/simplify/output.d.ts

@@ -0,0 +1,7 @@
+import type { ArrangeRunResult } from "#/arrange/domain/types";
+/**
+ * Presents the totals for an `arrange simplify` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentSimplifyResult(result: ArrangeRunResult, write: boolean): void;

package/dist/arrange/simplify/output.js

@@ -0,0 +1,15 @@
+import { logger } from "#/core/logger";
+/**
+ * Presents the totals for an `arrange simplify` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function presentSimplifyResult(result, write) {
+    logger.out(`\nTotal: ${result.filePaths.length} file(s), ${result.totalFound} site(s) to simplify.`);
+    if (write) {
+        logger.out(`Applied: ${result.totalChanged} site(s) updated.`);
+    }
+    else {
+        logger.out(`(Run "simplify" to write changes, or "pnpm cli:arrange-simplify" / "pnpm exec codefast arrange simplify")`);
+    }
+}

package/dist/arrange/{simplify-process-file.d.ts → simplify/process-file.d.ts}

@@ -1,11 +1,13 @@
 import type { GroupFileResult } from "#/arrange/domain/types";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { VariantClassNameProbe } from "#/arrange/simplify/variant-classname-probe";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 /**
  * Runs the simplify pass on one file — flattening class expressions and pruning an unused `cn` import.
  *
  * @since 0.3.16-canary.0
  */
-export declare function processArrangeSimplifyFile(fs: FilesystemPort, args: {
+export declare function processArrangeSimplifyFile(fs: Filesystem, args: {
     readonly filePath: string;
     readonly write: boolean;
+    readonly probe?: VariantClassNameProbe | null;
 }): GroupFileResult;

package/dist/arrange/simplify/process-file.js

@@ -0,0 +1,49 @@
+import { collectSimplifyTargets } from "#/arrange/domain/ast/simplify-targets";
+import { dropCnImportIfUnused } from "#/arrange/domain/imports";
+import { collectClassNameFoldTargets } from "#/arrange/simplify/fold-targets";
+import { parseDomainSourceFile } from "#/arrange/source-parse";
+import { applyEditsDescending, dropOverlappingEdits } from "#/core/source-text-edit";
+// A file simplify can act on names `cn`/`tv` (a call or an import to prune) or carries a `class`/`className`;
+// a source with none of these has nothing to flatten or fold, so it never needs parsing.
+const SIMPLIFY_MARKER = /\b(?:cn|tv)\b|className|\bclass\s*[=:]/;
+/**
+ * Runs the simplify pass on one file — flattening class expressions and pruning an unused `cn` import.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function processArrangeSimplifyFile(fs, args) {
+    const { filePath, write, probe } = args;
+    const sourceText = fs.readFileSync(filePath, "utf8");
+    if (!SIMPLIFY_MARKER.test(sourceText)) {
+        return { filePath, totalFound: 0, changed: 0 };
+    }
+    const domainSf = parseDomainSourceFile(filePath, sourceText);
+    // Resolve the file's type-server project at most once, and only if a syntactic fold candidate needs it.
+    let resolvedFileProbe;
+    const resolveFileProbe = () => {
+        resolvedFileProbe ??= probe ? probe.forFile(filePath) : null;
+        return resolvedFileProbe;
+    };
+    // Combine fold and base edits, drop no-ops, then remove overlaps so applyEditsDescending only sees
+    // non-overlapping ranges. Fold edits lead the list, so a fold wins an exact-range tie with a base
+    // edit on the same call and nested calls keep only the outermost edit.
+    const foldEdits = probe ? collectClassNameFoldTargets(domainSf, resolveFileProbe) : [];
+    const baseEdits = collectSimplifyTargets(domainSf);
+    const meaningful = dropOverlappingEdits([...foldEdits, ...baseEdits].filter((edit) => sourceText.slice(edit.start, edit.end) !== edit.replacement));
+    // Apply class-simplification edits first, then prune any cn import that
+    // became (or was already) unused. With no edits the text is unchanged, so the
+    // already-parsed tree is reused rather than parsing every untouched file twice.
+    const textAfterEdits = meaningful.length > 0 ? applyEditsDescending(sourceText, meaningful) : sourceText;
+    const domainSfAfterEdits = meaningful.length > 0 ? parseDomainSourceFile(filePath, textAfterEdits) : domainSf;
+    const textAfterImportDrop = dropCnImportIfUnused(domainSfAfterEdits);
+    const importDropped = textAfterImportDrop !== textAfterEdits;
+    const totalFound = meaningful.length + (importDropped ? 1 : 0);
+    if (totalFound === 0) {
+        return { filePath, totalFound: 0, changed: 0 };
+    }
+    if (!write) {
+        return { filePath, totalFound, changed: 0 };
+    }
+    fs.writeFileSync(filePath, textAfterImportDrop, "utf8");
+    return { filePath, totalFound, changed: totalFound };
+}