@codefast/cli 0.9.0 → 0.11.0

package/dist/arrange/domain/types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared types for the arrange pipeline (Tailwind `cn()` / `tv()` tooling).
+ *
+ * **Render Pipeline Order**: Existence → Position → Layout
+ * → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion
+ * → Starting → Behavior → State → Selector.
+ *
+ * `arbitrary` and `other` are non-pipeline tails for `[prop:value]` syntax and unknown utilities.
+ */
+import type { DomainAstNode, DomainCallExpression, DomainSourceFile, DomainTailwindClassLiteral } from "#/arrange/domain/ast/ast-node";
+import type { GroupFileWorkPlan } from "#/arrange/domain/grouping-service";
+import type { CodefastConfig } from "#/core/config/schema";
+/**
+ * The render-pipeline bucket a Tailwind token classifies into.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type Bucket = "existence" | "position" | "layout" | "sizing" | "spacing" | "shape" | "background" | "shadow" | "typography" | "composite" | "motion" | "starting" | "behavior" | "state"
+/**
+ * Selector variants (e.g. `[&…]:`, `*:`, `has-*`) distinct from interactive/data state.
+ */
+ | "selector" | "arbitrary" | "other";
+/**
+ * String or no-substitution template literal used as a Tailwind class blob.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TailwindClassLiteral = DomainTailwindClassLiteral;
+/**
+ * Options controlling which literals a class-expression walk visits.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ForEachStringLiteralInClassExpressionOptions = {
+    /**
+     * When `false`, do not visit literals inside `cond ? "a" : "b"`. Used when
+     * building the cn/tv **apply** pool so mutually exclusive branch classes are
+     * never merged into one static string (while `analyze` still uses the default).
+     */
+    descendIntoConditional?: boolean;
+};
+/**
+ * A static JSX `className` literal paired with the node to replace.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type JsxClassNameStatic = {
+    lit: TailwindClassLiteral;
+    /**
+     * Replace this node: `StringLiteral` or whole `JsxExpression`.
+     */
+    valueNode: DomainAstNode;
+};
+/**
+ * A StringNode represents a single "grouping slot" — the full set of static
+ * string literals that belong to one logical class surface.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type StringNode = {
+    /**
+     * All static string literals belonging to this slot, in source order.
+     */
+    nodes: Array<TailwindClassLiteral>;
+    sf: DomainSourceFile;
+    /**
+     * String slots in `tv({ ... })` that are not `cn(...)` arguments — use `formatArray` when
+     * replacing a whole array, or `formatArrayElementsAsSiblingLines` when replacing one element
+     * inside an existing array.
+     */
+    isTvContext: boolean;
+    /**
+     * When set, the entire cn(...) call is replaced at once.
+     */
+    cnCall?: DomainCallExpression | undefined;
+    /**
+     * First literal in the slot; used for positions and line-number reporting.
+     */
+    get primaryClassLiteral(): TailwindClassLiteral;
+};
+/**
+ * A groupable class surface — a `cn()` argument slot or a static JSX `className`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type GroupTarget = {
+    kind: "cnArg";
+    item: StringNode;
+} | {
+    kind: "jsxClassName";
+    sf: DomainSourceFile;
+    lit: TailwindClassLiteral;
+    valueNode: DomainAstNode;
+};
+/**
+ * A planned text replacement for one grouped class surface.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type PlannedGroupEdit = {
+    start: number;
+    end: number;
+    replacement: string;
+    /**
+     * Per-chunk bucket labels (same as `arrange group` trailing `// Buckets:` line).
+     */
+    bucketSummary: Array<string>;
+    jsxCn: boolean;
+    lineSf: DomainSourceFile;
+    reportNode: DomainAstNode;
+    label: string;
+};
+/**
+ * The accumulated findings of an `arrange analyze` run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type AnalyzeReport = {
+    files: number;
+    cnCallExpressions: number;
+    tvCallExpressions: number;
+    cnInsideTvCalls: Array<{
+        file: string;
+        line: number;
+        argCount: number;
+        preview: string;
+    }>;
+    longCnStringLiterals: Array<{
+        file: string;
+        line: number;
+        tokenCount: number;
+        preview: string;
+    }>;
+    longTvStringLiterals: Array<{
+        file: string;
+        line: number;
+        tokenCount: number;
+        preview: string;
+    }>;
+    longJsxClassNameLiterals: Array<{
+        file: string;
+        line: number;
+        tokenCount: number;
+        preview: string;
+    }>;
+};
+/**
+ * The per-file outcome of a grouping pass.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type GroupFileResult = {
+    filePath: string;
+    /**
+     * Sites worth human review: applied edits plus `cn()` inside `tv` with no args
+     * (skipped). Matches preview totals when `groupEdits` correspond to the same plan.
+     */
+    totalFound: number;
+    /**
+     * Edits actually written in apply mode; always 0 in preview mode.
+     */
+    changed: number;
+    /** Populated only in preview mode (write=false) when edits exist. */
+    workPlan?: GroupFileWorkPlan;
+};
+/**
+ * The options a per-file grouping pass runs with.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeGroupFileOptions = {
+    write: boolean;
+    withClassName: boolean;
+    cnImport?: string | undefined;
+};
+/**
+ * The aggregate outcome of an `arrange` run across files.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeRunResult = {
+    filePaths: Array<string>;
+    modifiedFiles: Array<string>;
+    totalFound: number;
+    totalChanged: number;
+    hookError: string | null;
+    /** Populated in preview mode (write=false); empty in apply mode. */
+    previewPlans: Array<GroupFileWorkPlan>;
+};
+/**
+ * The formatted lines `arrange group` prints for a suggested grouping.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeSuggestGroupsOutput = {
+    readonly primaryLine: string;
+    readonly bucketsCommentLine: string;
+};
+/**
+ * The resolved target, workspace root, and loaded config an arrange run starts from.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeTargetWorkspaceAndConfig = {
+    readonly resolvedTarget: string;
+    readonly rootDir: string;
+    readonly config: CodefastConfig;
+};

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

@@ -0,0 +1,7 @@
+import type { ArrangeSuggestGroupsOutput } from "#/arrange/domain/types";
+/**
+ * Machine-readable `arrange group` suggestion for `--json`.
+ *
+ * @since 0.11.0
+ */
+export declare function formatArrangeGroupJsonOutput(output: ArrangeSuggestGroupsOutput): string;

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

@@ -0,0 +1,12 @@
+/**
+ * Machine-readable `arrange group` suggestion for `--json`.
+ *
+ * @since 0.11.0
+ */
+export function formatArrangeGroupJsonOutput(output) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        primaryLine: output.primaryLine,
+        bucketsCommentLine: output.bucketsCommentLine,
+    });
+}

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

@@ -0,0 +1,17 @@
+import * as z from "zod";
+/**
+ * The request payload for `arrange group`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeSuggestGroupsRequest = {
+    inlineClasses: string;
+    emitTvStyleArray: boolean;
+    trailingClassName: boolean;
+};
+/**
+ * The `zod` schema validating an `arrange group` request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const arrangeSuggestGroupsRequestSchema: z.ZodType<ArrangeSuggestGroupsRequest>;

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

@@ -0,0 +1,13 @@
+import * as z from "zod";
+/**
+ * The `zod` schema validating an `arrange group` request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export const arrangeSuggestGroupsRequestSchema = z.object({
+    inlineClasses: z
+        .string()
+        .min(1, 'Pass a class string. Example: codefast arrange group "flex gap-2 text-sm rounded-md"'),
+    emitTvStyleArray: z.boolean(),
+    trailingClassName: z.boolean(),
+});

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

@@ -0,0 +1,7 @@
+import type { ArrangeSuggestGroupsOutput } from "#/arrange/domain/types";
+/**
+ * Presents the suggested grouping lines for an `arrange group` run.
+ *
+ * @since 0.11.0
+ */
+export declare function presentArrangeGroupResult(output: ArrangeSuggestGroupsOutput): void;

package/dist/arrange/group/output.js

@@ -0,0 +1,10 @@
+import { logger } from "#/core/logger";
+/**
+ * Presents the suggested grouping lines for an `arrange group` run.
+ *
+ * @since 0.11.0
+ */
+export function presentArrangeGroupResult(output) {
+    logger.out(output.primaryLine);
+    logger.out(output.bucketsCommentLine);
+}

package/dist/arrange/group/suggest.d.ts

@@ -0,0 +1,8 @@
+import type { ArrangeSuggestGroupsOutput } from "#/arrange/domain/types";
+import type { ArrangeSuggestGroupsRequest } from "#/arrange/group/cli-schema";
+/**
+ * Formats the suggested grouping for an inline class string as `arrange group` output lines.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function suggestCnGroupsFromCli(request: ArrangeSuggestGroupsRequest): ArrangeSuggestGroupsOutput;

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

@@ -0,0 +1,7 @@
+import type { AnalyzeReport } from "#/arrange/domain/types";
+/**
+ * Machine-readable `arrange inspect` report for `--json`.
+ *
+ * @since 0.11.0
+ */
+export declare function formatArrangeAnalyzeJsonOutput(analyzeRootPath: string, report: AnalyzeReport): string;

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

@@ -0,0 +1,8 @@
+/**
+ * Machine-readable `arrange inspect` report for `--json`.
+ *
+ * @since 0.11.0
+ */
+export function formatArrangeAnalyzeJsonOutput(analyzeRootPath, report) {
+    return JSON.stringify({ schemaVersion: 1, analyzeRootPath, report });
+}

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

@@ -0,0 +1,15 @@
+import * as z from "zod";
+/**
+ * The request payload for `arrange inspect`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ArrangeAnalyzeDirectoryRequest = {
+    analyzeRootPath: string;
+};
+/**
+ * The `zod` schema validating an `arrange inspect` request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const arrangeAnalyzeDirectoryRequestSchema: z.ZodType<ArrangeAnalyzeDirectoryRequest>;

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

@@ -0,0 +1,9 @@
+import * as z from "zod";
+/**
+ * The `zod` schema validating an `arrange inspect` request.
+ *
+ * @since 0.3.16-canary.0
+ */
+export const arrangeAnalyzeDirectoryRequestSchema = z.object({
+    analyzeRootPath: z.string().min(1, "analyzeRootPath is required"),
+});

package/dist/arrange/inspect/domain/analyze-service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Rich domain: Tailwind/cn/tv analysis rules (counts, long literals, nested cn in tv).
+ * Pure orchestration of domain collectors and invariants — no I/O.
+ */
+import type { DomainSourceFile } from "#/arrange/domain/ast/ast-node";
+import type { AnalyzeReport } from "#/arrange/domain/types";
+/**
+ * Creates a zeroed analyze report ready for accumulation.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function createEmptyAnalyzeReport(): AnalyzeReport;
+/**
+ * Accumulates findings for one parsed source file into `report` (mutates report).
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function accumulateAnalyzeReportForSourceFile(report: AnalyzeReport, domainSf: DomainSourceFile, sourceText: string, filePath: string): void;

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

@@ -0,0 +1,7 @@
+import type { AnalyzeReport } from "#/arrange/domain/types";
+/**
+ * Presents the human-readable summary of an `arrange inspect` report.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentAnalyzeReport(resolvedTargetPath: string, report: AnalyzeReport): void;

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/inspect/run.d.ts

@@ -0,0 +1,10 @@
+import type { AnalyzeReport } from "#/arrange/domain/types";
+import { AppError } from "#/core/errors";
+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 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/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { ArrangeTargetWorkspaceAndConfig } from "#/arrange/domain/types";
+import { AppError } from "#/core/errors";
+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: 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 { findRepoRoot } 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 = findRepoRoot(args.currentWorkingDirectory, fs);
-    }
-    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/regroup/process-file.d.ts

@@ -0,0 +1,11 @@
+import type { ArrangeGroupFileOptions, GroupFileResult } from "#/arrange/domain/types";
+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: Filesystem, args: {
+    readonly filePath: string;
+    readonly options: ArrangeGroupFileOptions;
+}): GroupFileResult;