@codefast/cli 0.3.12 → 0.3.13-canary.1

package/README.md

@@ -1,100 +1,255 @@
 # @codefast/cli
 
-Two tools bundled in one CLI:
+A focused CLI for two recurring maintenance tasks in monorepos:
 
-| Command       | Purpose                                                                                                                                                                             |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mirror sync` | Regenerate `package.json` `exports` from each package's built `dist/` tree (pnpm workspace packages)                                                                                |
-| `arrange`     | Analyze, dry-run, or apply suggested grouping for long Tailwind class strings inside `cn()` / `tv()` call sites (Tailwind v4–oriented heuristics), or `group` a pasted class string |
+- **`arrange`** — analyze and regroup Tailwind class strings inside `cn()` / `tv()` calls according to a consistent render-pipeline order.
+- **`mirror`** — regenerate `package.json` `exports` fields from built `dist/` trees across a pnpm workspace.
+- **`tag`** (alias: **`annotate`**) — auto-add `@since <version>` to exported TypeScript declarations that are still missing version metadata.
+
+```mermaid
+flowchart LR
+  R[codefast]
+  R --> A[arrange]
+  R --> M[mirror]
+  R --> T[tag]
+
+  A --> A0[analyze]
+  A --> A1[preview]
+  A --> A2[apply]
+  A --> A3[group]
+
+  M --> M0[sync]
+```
 
 ---
 
-## Requirements & Install
+## Requirements
+
+- Node.js `>=22.0.0`
+- pnpm (recommended)
+
+---
 
-**Node.js ≥ 24** is required.
+## Installation
 
 ```bash
-# Global
+# Install globally
 pnpm add -g @codefast/cli
 
-# Without a global install
-pnpm dlx @codefast/cli -- --help
+# Or run without installing
+pnpm dlx @codefast/cli --help
+```
+
+---
+
+## Quick start
+
+```bash
+# 1. Preview proposed changes — no files written
+codefast arrange preview packages/ui/src/components
+
+# 2. Apply after reviewing the diff
+codefast arrange apply packages/ui/src/components
+
+# 3. Regenerate package exports from built dist/
+codefast mirror sync
+
+# 4. Add @since tags to exported APIs under src/
+codefast tag
 ```
 
 ---
 
 ## `arrange`
 
-### Recommended workflow
+Reads `cn()` and `tv()` call sites, classifies each Tailwind utility, and rewrites the class strings in render-pipeline order (see [Grouping philosophy](#grouping-philosophy--render-pipeline-order) below).
+
+### Workflow
 
-1. **`analyze [target]`** — Prints a report (long strings, nested `cn` in `tv`, related notes). No files changed.
-2. **`preview [target]`** — Same transforms as `apply`, but writes nothing. Inspect stdout before touching the tree.
-3. **`apply [target]`** — Writes edits. Run `preview` first.
+Run the three subcommands in order:
 
-**Default target** (when path is omitted): `packages/ui/src/components` resolved from `process.cwd()`.
+| Step | Command                             | Effect                                |
+| ---- | ----------------------------------- | ------------------------------------- |
+| 1    | `codefast arrange analyze [target]` | Report only — no files changed        |
+| 2    | `codefast arrange preview [target]` | Show exactly what `apply` would write |
+| 3    | `codefast arrange apply [target]`   | Write the changes                     |
 
-### Useful options
+The default `target` when omitted is `packages/ui/src/components`, resolved from `process.cwd()`.
 
-- **`--with-class-name`** — Append `className` as the last argument to the suggested `cn(...)`.
-- **`--cn-import <spec>`** — Override the module specifier when the tool adds a `cn` import.
+### Flags
 
-### `group [tokens...]`
+| Flag                 | Description                                                             |
+| -------------------- | ----------------------------------------------------------------------- |
+| `--with-class-name`  | Append `className` as the last argument when rewriting a `cn(...)` call |
+| `--cn-import <spec>` | Override the module specifier used when adding a missing `cn` import    |
 
-No filesystem involved — paste a class string, get back a suggested `cn(...)` (or a `tv()`-style array with `--tv`) plus a short buckets summary. Use this to tune your mental model before running `analyze` on a large tree.
+### `arrange group` — one-shot string grouping
+
+Groups a single class string without touching the filesystem. Useful for checking how a string would be classified before running `apply`:
+
+```bash
+codefast arrange group "relative flex items-center h-10 w-full rounded-md bg-primary text-white hover:bg-primary/90"
+```
 
 ---
 
-## Grouping philosophy — Render Pipeline Order
+## `mirror sync`
 
-`arrange` does **not** sort alphabetically. It groups utilities in roughly the same order the browser reasons about them:
+Scans built `dist/` trees and regenerates the `exports` field in each `package.json`. Run from anywhere inside the monorepo — the workspace root is discovered automatically via `pnpm-workspace.yaml`.
 
-**Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion → Starting → Behavior → Conditions (State)**
+```bash
+codefast mirror sync              # all packages in the workspace
+codefast mirror sync packages/ui  # a single package path
+codefast mirror sync -v           # verbose output
+```
 
-Bucket breakdown:
+> **Note:** Packages must be built first so `dist/` exists. Run your build step before `mirror sync`.
+
+### Configuration
+
+Create a `codefast.config.js` (or `.mjs`, `.cjs`, `.json`) at the repo root with a `mirror` key:
+
+```js
+// codefast.config.mjs
+export default {
+  mirror: {
+    skipPackages: ["@acme/internal"],
+    pathTransformations: {
+      "@acme/ui": {
+        removePrefix: "./components/",
+      },
+    },
+    customExports: {
+      "@acme/ui": {
+        "./css/*": "./src/styles/*",
+      },
+    },
+    cssExports: {
+      "@acme/ui": {
+        enabled: true,
+        customExports: {
+          "./tokens.css": "./dist/tokens.css",
+        },
+      },
+    },
+  },
+};
+```
 
-| Bucket         | What it covers                                    | Examples                                          |
-| -------------- | ------------------------------------------------- | ------------------------------------------------- |
-| **Existence**  | Display / containment context                     | `hidden`, `block`, `@container`, `group`, `peer`  |
-| **Position**   | Where the box sits                                | `absolute`, `inset-*`, `top-*`, `z-*`             |
-| **Layout**     | How children flow                                 | `flex`, `grid`, `gap-*`, `items-*`                |
-| **Sizing**     | Box dimensions and overflow                       | `w-*`, `h-*`, `aspect-*`, `overflow-*`            |
-| **Spacing**    | Padding and margin only (gaps stay with Layout)   | `p-*`, `m-*`                                      |
-| **Shape**      | Corners and strokes                               | `rounded-*`, `border-*`, `ring-*`                 |
-| **Background** | Surfaces and masks                                | `bg-*`, `from-*`, `via-*`, `to-*`, `mask-*`       |
-| **Shadow**     | Depth                                             | `shadow-*`, `inset-shadow-*`, `text-shadow-*`     |
-| **Typography** | Text appearance                                   | `font-*`, `text-*`, `leading-*`                   |
-| **Composite**  | Layers and transforms — 3D context → 3D → 2D      | `opacity-*`, `rotate-x-*`, `translate-*`          |
-| **Motion**     | Time-based change                                 | `transition-*`, `animate-*`                       |
-| **Starting**   | Tailwind's `starting:` layer, kept next to Motion | `starting:*`                                      |
-| **Behavior**   | Input / scrolling / chrome                        | `cursor-*`, `scroll-*`, `field-sizing-*`, `inert` |
-| **State**      | Everything with a variant stack                   | `hover:`, `md:`, `@md/sidebar:`, `data-[…]:`      |
+Use your real package names from `package.json#name` (for example `@acme/ui`) and adjust entries to match your workspace.
 
-Some adjacent buckets may be merged into one string literal when declared _compatible_ (e.g. `layout` + `sizing`) — keeps `cn()` readable without flattening unrelated concerns.
+> **Migration:** Path-based keys (for example `packages/ui`) are deprecated for `pathTransformations`, `customExports`, `cssExports`, and `skipPackages`. Migrate to package-name keys.
 
-To change a placement, edit `classifyBareUtility` in `src/lib/arrange/tokenizer.ts` and add a `classifyToken` test in `src/lib/arrange.test.ts`.
+> **Security note:** `.js`, `.mjs`, and `.cjs` config files are loaded via `import()`. Only run `mirror sync` in repositories you trust.
 
 ---
 
-## `mirror sync`
+## Lifecycle hooks (`codefast.config.mjs`)
+
+`codefast` supports lifecycle hooks so teams can plug in their own post-write workflow (formatter, lint-fix, codemods) without hardcoding any formatter inside CLI core.
+
+```javascript
+import { execSync } from "node:child_process";
+
+export default {
+  tag: {
+    onAfterWrite: ({ files }) => {
+      console.log(`Formatting ${files.length} files with Oxc...`);
+      execSync(`npx oxc format ${files.join(" ")}`, { stdio: "inherit" });
+    },
+  },
+  arrange: {
+    onAfterWrite: ({ files }) => {
+      execSync(`npx oxc format ${files.join(" ")}`, { stdio: "inherit" });
+    },
+  },
+};
+```
+
+Hook contract:
+
+- `tag.onAfterWrite?.({ files })` runs after `codefast tag` writes files.
+- `arrange.onAfterWrite?.({ files })` runs after `codefast arrange apply` writes files.
+- Hooks support both sync and async functions (`void | Promise<void>`).
+- Hook errors are logged but do not crash the CLI process.
+
+---
+
+## `tag` / `annotate`
 
-Run from anywhere under the monorepo — the CLI finds the root via `pnpm-workspace.yaml`.
+Scans `.ts` / `.tsx` source files and annotates exported declarations with `@since <current-package-version>`. This keeps API evolution visible and reduces documentation drift in long-lived codebases.
 
 ```bash
-codefast mirror sync              # All workspace packages
-codefast mirror sync packages/ui  # One package only
-codefast mirror sync -v           # Verbose
+codefast tag                  # annotate exports in ./src
+codefast tag packages/ui/src  # annotate a custom target
+codefast annotate --dry-run   # preview only, do not write files
 ```
 
-**Config:** Place `codefast.config.js` (or `.mjs` / `.cjs` / `.json`) at repo root with a `mirror` object (`skipPackages`, `pathTransformations`, `customExports`, …).
+What it updates:
 
-> ⚠️ `.js`/`.mjs`/`.cjs` config files are loaded via `import()` — only run `mirror sync` in repositories you trust.
+- Adds `/** @since <version> */` when an exported declaration has no JSDoc.
+- Injects `@since <version>` into an existing JSDoc block when missing.
+- Leaves declarations unchanged when `@since` is already present.
+
+The `<version>` value is read from the nearest `package.json` found by walking up from the target path.
 
 ---
 
-## Developing inside this monorepo
+## Grouping philosophy — Render Pipeline Order
+
+`arrange` does **not** sort classes alphabetically. Instead, it groups utilities in roughly the order the browser applies them — from the box's existence, through its shape and surface, to interactive behavior. This makes class strings easier to scan and reason about at a glance.
+
+**Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion → Starting → Behavior → State → Selector**
+
+| Bucket         | What it covers                                      | Examples                                          |
+| -------------- | --------------------------------------------------- | ------------------------------------------------- |
+| **Existence**  | Display and containment context                     | `hidden`, `block`, `@container`, `group`, `peer`  |
+| **Position**   | Where the box sits                                  | `absolute`, `inset-*`, `top-*`, `z-*`             |
+| **Layout**     | How children flow                                   | `flex`, `grid`, `gap-*`, `items-*`                |
+| **Sizing**     | Box dimensions and overflow                         | `w-*`, `h-*`, `aspect-*`, `overflow-*`            |
+| **Spacing**    | Padding and margin only (gaps stay with Layout)     | `p-*`, `m-*`                                      |
+| **Shape**      | Corners and strokes                                 | `rounded-*`, `border-*`, `ring-*`                 |
+| **Background** | Surfaces and masks                                  | `bg-*`, `from-*`, `via-*`, `to-*`, `mask-*`       |
+| **Shadow**     | Depth                                               | `shadow-*`, `inset-shadow-*`, `text-shadow-*`     |
+| **Typography** | Text appearance                                     | `font-*`, `text-*`, `leading-*`                   |
+| **Composite**  | Layers and transforms (3D context → 3D → 2D)        | `opacity-*`, `rotate-x-*`, `translate-*`          |
+| **Motion**     | Time-based change                                   | `transition-*`, `animate-*`                       |
+| **Starting**   | Tailwind's `starting:` layer — kept next to Motion  | `starting:*`                                      |
+| **Behavior**   | Input, scrolling, and browser chrome                | `cursor-*`, `scroll-*`, `field-sizing-*`, `inert` |
+| **State**      | Interactive and conditional variants (non-selector) | `hover:`, `md:`, `@md/sidebar:`, `data-[…]:`      |
+| **Selector**   | Selector-driven variants                            | `[&…]:`, `*:`, `**:`, `has-*`, `group-[…]:`       |
+
+Adjacent buckets may be merged into one string literal when declared _compatible_ (e.g. `layout` + `sizing`). This keeps `cn()` calls readable without flattening unrelated concerns into a single undifferentiated blob.
+
+To change a placement, edit `classifyBareUtility` in `src/lib/arrange/tokenizer.ts` and add a corresponding `classifyToken` test in `src/lib/arrange.test.ts`.
+
+---
+
+## Troubleshooting
+
+**`codefast: command not found`**
+Install globally with `pnpm add -g @codefast/cli`, or run via `pnpm dlx @codefast/cli <command>`.
+
+**`mirror sync` writes little or no output**
+Packages must be built before syncing. Ensure `dist/` exists by running your build step first, then re-run `codefast mirror sync`.
+
+**Unexpected class reorder after `arrange apply`**
+Run `arrange preview` before applying and smoke-test the UI. Some components rely on cascade-sensitive ordering that `arrange` cannot detect automatically.
+
+---
+
+## Contributing (monorepo setup)
 
 ```bash
+# Build the local CLI (produces dist/bin.js)
+pnpm --filter @codefast/cli build
+
+# Run the local entrypoint
 pnpm exec codefast --help
 ```
 
-Root `package.json` defines optional `cli:*` scripts (e.g. `cli:mirror-sync`, `cli:arrange-analyze`) as thin wrappers around `pnpm exec codefast …`.
+A few naming conventions to keep in mind:
+
+- **`codefast <command>`** refers to CLI commands exposed via the `@codefast/cli` `bin` entry.
+- **Scripts in `packages/cli/package.json`** (`build`, `test`, …) are package-local dev scripts, not CLI commands.
+- The root `package.json` includes optional convenience wrappers such as `cli:mirror-sync` and `cli:arrange-analyze` for common dev workflows.

package/dist/{bin.js → bin.mjs}

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
+import { runCli } from "./program.mjs";
 import process from "node:process";
-import { runCli } from "#program";
+//#region src/bin.ts
 const code = await runCli(process.argv);
 process.exit(code);
+//#endregion
+export {};

package/dist/commands/arrange.mjs

@@ -0,0 +1,107 @@
+import { messageFromCaughtUnknown } from "../lib/infra/caught-unknown-message.mjs";
+import { loadConfig } from "../lib/config/infra/loader.mjs";
+import "../lib/config/index.mjs";
+import { printConfigSchemaWarnings } from "../lib/infra/config-reporter.mjs";
+import { DEFAULT_ARRANGE_TARGET } from "../lib/arrange/domain/constants.mjs";
+import { analyzeDirectory } from "../lib/arrange/application/analyze.mjs";
+import { printAnalyzeReport } from "../lib/arrange/presentation/report.mjs";
+import { suggestCnGroups, summarizeGroupBucketLabels } from "../lib/arrange/domain/grouping.mjs";
+import { formatArray, formatCnCall } from "../lib/arrange/presentation/formatters.mjs";
+import { runArrangeSync } from "../lib/arrange/application/run-target.mjs";
+import { createNodeCliFs, createNodeCliLogger } from "../lib/infra/node-io.mjs";
+import "../lib/arrange/index.mjs";
+import { findRepoRoot } from "../lib/infra/workspace/repo-root.mjs";
+import process from "node:process";
+import path from "node:path";
+import { Option } from "commander";
+//#region src/commands/arrange.ts
+/** Commander attribute `withClassName` (second long flag `--with-class-name`). */
+function createWithClassNameOption() {
+	return new Option("--with-classname, --with-class-name", "Append className as final cn() argument").default(false);
+}
+function defaultTargetPath() {
+	return path.resolve(process.cwd(), DEFAULT_ARRANGE_TARGET);
+}
+function checkTargetExists(resolved, fs, logger) {
+	if (!fs.existsSync(resolved)) {
+		logger.err(`Not found: ${resolved}`);
+		process.exitCode = 1;
+		return false;
+	}
+	return true;
+}
+async function loadArrangeCommandConfig(fs, logger, rootDir) {
+	try {
+		const { config, warnings } = await loadConfig(fs, rootDir);
+		printConfigSchemaWarnings(logger, warnings);
+		return { arrangeConfig: config.arrange ?? {} };
+	} catch (caughtConfigError) {
+		logger.err(messageFromCaughtUnknown(caughtConfigError));
+		process.exitCode = 1;
+		return;
+	}
+}
+function registerArrangeCommand(program) {
+	const arrange = program.command("arrange").description("Analyze and regroup Tailwind classes in cn() / tv() calls (Tailwind v4)");
+	arrange.command("analyze").description("Report long strings, nested cn in tv(), and related findings").argument("[target]", "Directory or file (default: packages/ui/src/components)").action(async (target) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		if (!await loadArrangeCommandConfig(fs, logger, findRepoRoot(fs))) return;
+		printAnalyzeReport(resolved, analyzeDirectory(resolved, fs), logger);
+	});
+	arrange.command("preview").description("Dry-run: print suggested replacements without writing files").argument("[target]", "Directory or file (default: packages/ui/src/components)").addOption(createWithClassNameOption()).option("--cn-import <spec>", "Override module specifier when adding cn import").action(async (target, opts) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		const rootDir = findRepoRoot(fs);
+		const loaded = await loadArrangeCommandConfig(fs, logger, rootDir);
+		if (!loaded) return;
+		process.exitCode = await runArrangeSync({
+			rootDir,
+			config: loaded.arrangeConfig,
+			targetPath: resolved,
+			write: false,
+			withClassName: opts.withClassName,
+			cnImport: opts.cnImport,
+			fs,
+			logger
+		});
+	});
+	arrange.command("apply").description("Apply grouping and cn-in-tv unwrap edits to files").argument("[target]", "Directory or file (default: packages/ui/src/components)").addOption(createWithClassNameOption()).option("--cn-import <spec>", "Override module specifier when adding cn import").action(async (target, opts) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const resolved = target ? path.resolve(target) : defaultTargetPath();
+		if (!checkTargetExists(resolved, fs, logger)) return;
+		const rootDir = findRepoRoot(fs);
+		const loaded = await loadArrangeCommandConfig(fs, logger, rootDir);
+		if (!loaded) return;
+		process.exitCode = await runArrangeSync({
+			rootDir,
+			config: loaded.arrangeConfig,
+			targetPath: resolved,
+			write: true,
+			withClassName: opts.withClassName,
+			cnImport: opts.cnImport,
+			fs,
+			logger
+		});
+	});
+	arrange.command("group").description("Try grouping on a pasted class string (stdout: cn(...) or tv array with --tv)").argument("[tokens...]", "Class tokens (quote a single string if it contains spaces)").option("--tv", "Emit tv()-style array instead of cn() call", false).addOption(createWithClassNameOption()).action((tokens, opts) => {
+		const inlineClasses = tokens.join(" ").trim();
+		if (!inlineClasses) {
+			process.stderr.write("Pass a class string. Example: codefast arrange group \"flex gap-2 text-sm rounded-md\"\n");
+			process.exitCode = 1;
+			return;
+		}
+		const groups = suggestCnGroups(inlineClasses);
+		const result = opts.tv ? formatArray(groups) : formatCnCall(groups, { trailingClassName: !!opts.withClassName });
+		process.stdout.write(`${result}\n`);
+		const bucketSummary = summarizeGroupBucketLabels(groups);
+		process.stdout.write(`\n// Buckets: ${JSON.stringify(bucketSummary)}\n`);
+	});
+}
+//#endregion
+export { registerArrangeCommand };

package/dist/commands/mirror.mjs

@@ -0,0 +1,66 @@
+import { messageFromCaughtUnknown } from "../lib/infra/caught-unknown-message.mjs";
+import { loadConfig } from "../lib/config/infra/loader.mjs";
+import "../lib/config/index.mjs";
+import { printConfigSchemaWarnings } from "../lib/infra/config-reporter.mjs";
+import { createNodeCliFs, createNodeCliLogger } from "../lib/infra/node-io.mjs";
+import { findRepoRoot } from "../lib/infra/workspace/repo-root.mjs";
+import { runMirrorSync } from "../lib/mirror/application/sync.mjs";
+import "../lib/mirror/index.mjs";
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+//#region src/commands/mirror.ts
+function tryRealpath(entryPath) {
+	try {
+		return realpathSync.native(entryPath);
+	} catch {
+		return path.resolve(entryPath);
+	}
+}
+function normalizePath(relPath) {
+	return relPath.split(path.sep).join("/").replace(/\\/g, "/");
+}
+function packageArgToRelative(rootDir, arg) {
+	if (!arg) return;
+	const rootReal = tryRealpath(path.resolve(rootDir));
+	const cwdReal = tryRealpath(process.cwd());
+	const targetReal = tryRealpath(path.isAbsolute(arg) ? path.resolve(arg) : path.resolve(cwdReal, arg));
+	const normalized = normalizePath(path.relative(rootReal, targetReal));
+	if (normalized.startsWith("..") || path.isAbsolute(normalized) || normalized === "" || normalized === ".") throw new Error(`Package path must be a subdirectory under monorepo root: ${rootDir}`);
+	return normalized;
+}
+function registerMirrorCommand(program) {
+	program.command("mirror").description("Keep package manifests aligned with what you ship").command("sync").description("Write package.json exports from dist/ for workspace packages").argument("[package]", "Optional package path relative to repo root (e.g. packages/ui)").option("-v, --verbose", "Print extra diagnostics", false).action(async function(pkg, options) {
+		const globals = this.optsWithGlobals();
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const rootDir = findRepoRoot(fs);
+		let packageFilter;
+		try {
+			packageFilter = packageArgToRelative(rootDir, pkg);
+		} catch (caughtPathError) {
+			this.error(messageFromCaughtUnknown(caughtPathError));
+			return;
+		}
+		let mirrorConfig = {};
+		try {
+			const { config, warnings } = await loadConfig(fs, rootDir);
+			printConfigSchemaWarnings(logger, warnings);
+			mirrorConfig = config.mirror ?? {};
+		} catch (caughtConfigError) {
+			this.error(messageFromCaughtUnknown(caughtConfigError));
+			return;
+		}
+		process.exitCode = await runMirrorSync({
+			rootDir,
+			config: mirrorConfig,
+			verbose: options.verbose,
+			noColor: globals.color === false,
+			packageFilter,
+			fs,
+			logger
+		});
+	});
+}
+//#endregion
+export { packageArgToRelative, registerMirrorCommand };

package/dist/commands/tag.mjs

@@ -0,0 +1,58 @@
+import { messageFromCaughtUnknown } from "../lib/infra/caught-unknown-message.mjs";
+import { loadConfig } from "../lib/config/infra/loader.mjs";
+import "../lib/config/index.mjs";
+import { printConfigSchemaWarnings } from "../lib/infra/config-reporter.mjs";
+import { createNodeCliFs, createNodeCliLogger } from "../lib/infra/node-io.mjs";
+import { findRepoRoot } from "../lib/infra/workspace/repo-root.mjs";
+import { runTagSync } from "../lib/tag/application/engine.mjs";
+import { createTagProgressListener, formatSummary, formatTargetTable, formatWarningsAndErrors } from "../lib/tag/presentation/tag-presenter.mjs";
+import "../lib/tag/index.mjs";
+import process from "node:process";
+import path from "node:path";
+//#region src/commands/tag.ts
+function resolveTagRootDir(fs, logger) {
+	try {
+		return findRepoRoot(fs);
+	} catch (caughtRepoRootError) {
+		logger.out(`[tag] workspace root auto-detection failed (${messageFromCaughtUnknown(caughtRepoRootError)}), using cwd=${process.cwd()}`);
+		return process.cwd();
+	}
+}
+function registerTagCommand(program) {
+	program.command("tag").alias("annotate").description("Add @since <version> JSDoc tags to exported declarations").argument("[target]", "Directory or file to annotate (default: auto-discover workspace packages)").option("--dry-run", "Show summary without writing files", false).action(async (target, options) => {
+		const fs = createNodeCliFs();
+		const logger = createNodeCliLogger();
+		const rootDir = resolveTagRootDir(fs, logger);
+		let tagConfig = {};
+		try {
+			const { config, warnings } = await loadConfig(fs, rootDir);
+			printConfigSchemaWarnings(logger, warnings);
+			tagConfig = config.tag ?? {};
+		} catch (caughtConfigError) {
+			logger.err(messageFromCaughtUnknown(caughtConfigError));
+			process.exitCode = 1;
+			return;
+		}
+		const tagResult = await runTagSync({
+			rootDir,
+			config: tagConfig,
+			skipPackages: tagConfig.skipPackages,
+			targetPath: target ? path.resolve(target) : void 0,
+			write: !options.dryRun,
+			fs,
+			listener: createTagProgressListener((line) => logger.out(line))
+		});
+		logger.out(formatTargetTable(tagResult.selectedTargets, rootDir));
+		if (tagResult.selectedTargets.length === 0) {
+			logger.err("No packages found in workspace. Check your pnpm-workspace.yaml or provide an explicit target path.");
+			process.exitCode = 1;
+			return;
+		}
+		const warningsAndErrorsSection = formatWarningsAndErrors(tagResult);
+		if (warningsAndErrorsSection) logger.err(warningsAndErrorsSection);
+		logger.out(formatSummary(tagResult));
+		process.exitCode = tagResult.targetResults.some((targetResult) => targetResult.runError !== null) || tagResult.hookError ? 1 : 0;
+	});
+}
+//#endregion
+export { registerTagCommand };

package/dist/lib/arrange/application/analyze.mjs

@@ -0,0 +1,92 @@
+import "../domain/constants.mjs";
+import { tokenizeClassString } from "../domain/tokenizer.mjs";
+import { forEachStringLiteralInClassExpression } from "../domain/ast/collectors-cn.mjs";
+import { jsxClassNameStaticLiteral } from "../domain/ast/collectors-jsx.mjs";
+import { buildKnownCnTvBindings, isCnOrTvIdentifier, lineOf } from "../domain/ast/ast-helpers.mjs";
+import { collectCnCallsInsideTv, traverseTvObject } from "../domain/ast/collectors-tv.mjs";
+import { walkTsxFiles } from "../infra/walk.mjs";
+import ts from "typescript";
+//#region src/lib/arrange/application/analyze.ts
+function analyzeCnCall(sf, call, report) {
+	for (const arg of call.arguments) forEachStringLiteralInClassExpression(arg, (lit) => {
+		const text = lit.text;
+		const tokenCount = tokenizeClassString(text).length;
+		if (tokenCount >= 18) report.longCnStringLiterals.push({
+			file: sf.fileName,
+			line: lineOf(sf, lit),
+			tokenCount,
+			preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+		});
+	});
+}
+function visitCallExpressionForArrangeAnalyze(callExpression, sf, sourceText, knownBindings, report) {
+	if (isCnOrTvIdentifier(callExpression.expression, "cn", knownBindings)) {
+		report.cnCallExpressions++;
+		analyzeCnCall(sf, callExpression, report);
+		return;
+	}
+	if (!isCnOrTvIdentifier(callExpression.expression, "tv", knownBindings)) return;
+	report.tvCallExpressions++;
+	const arg0 = callExpression.arguments[0];
+	if (!arg0 || !ts.isObjectLiteralExpression(arg0)) return;
+	for (const nestedCn of collectCnCallsInsideTv(sf, arg0, knownBindings, 0)) {
+		const src = sourceText.slice(nestedCn.getStart(sf), nestedCn.getEnd());
+		const preview = src.length > 72 ? `${src.slice(0, 72)}…` : src;
+		report.cnInsideTvCalls.push({
+			file: sf.fileName,
+			line: lineOf(sf, nestedCn),
+			argCount: nestedCn.arguments.length,
+			preview
+		});
+	}
+	traverseTvObject(sf, arg0, (classLiteral) => {
+		const text = classLiteral.text;
+		const tokenCount = tokenizeClassString(text).length;
+		if (tokenCount >= 18) report.longTvStringLiterals.push({
+			file: sf.fileName,
+			line: lineOf(sf, classLiteral),
+			tokenCount,
+			preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+		});
+	}, 0, knownBindings);
+}
+function visitJsxAttributeForArrangeAnalyze(jsxClassAttribute, sf, filePath, report) {
+	if (!filePath.endsWith(".tsx")) return;
+	const parsed = jsxClassNameStaticLiteral(jsxClassAttribute);
+	if (!parsed) return;
+	const text = parsed.lit.text;
+	const tokenCount = tokenizeClassString(text).length;
+	if (tokenCount >= 18) report.longJsxClassNameLiterals.push({
+		file: sf.fileName,
+		line: lineOf(sf, parsed.lit),
+		tokenCount,
+		preview: text.length > 72 ? `${text.slice(0, 72)}…` : text
+	});
+}
+function analyzeDirectory(analyzeRootPath, fs) {
+	const report = {
+		files: 0,
+		cnCallExpressions: 0,
+		tvCallExpressions: 0,
+		cnInsideTvCalls: [],
+		longCnStringLiterals: [],
+		longTvStringLiterals: [],
+		longJsxClassNameLiterals: []
+	};
+	const files = fs.statSync(analyzeRootPath).isDirectory() ? walkTsxFiles(analyzeRootPath, fs) : [analyzeRootPath];
+	for (const filePath of files) {
+		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);
+		report.files++;
+		const knownBindings = buildKnownCnTvBindings(sf);
+		const visitTypeScriptSubtree = (tsNode) => {
+			if (ts.isCallExpression(tsNode)) visitCallExpressionForArrangeAnalyze(tsNode, sf, sourceText, knownBindings, report);
+			if (ts.isJsxAttribute(tsNode)) visitJsxAttributeForArrangeAnalyze(tsNode, sf, filePath, report);
+			ts.forEachChild(tsNode, visitTypeScriptSubtree);
+		};
+		visitTypeScriptSubtree(sf);
+	}
+	return report;
+}
+//#endregion
+export { analyzeDirectory };