@codefast/cli 0.3.7-canary.0 → 0.3.13-canary.0

package/README.md

@@ -1,339 +1,255 @@
 # @codefast/cli
 
-Command line interface tools for CodeFast development, built with explicit architecture principles.
+A focused CLI for two recurring maintenance tasks in monorepos:
 
-## Overview
+- **`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.
 
-The CodeFast CLI is a TypeScript-based command-line tool designed to analyze and validate CodeFast projects. It provides powerful analysis capabilities for TypeScript projects and React component type checking, following explicit architecture guidelines for maintainability, testability, and scalability.
+```mermaid
+flowchart LR
+  R[codefast]
+  R --> A[arrange]
+  R --> M[mirror]
+  R --> T[tag]
 
-## Features
+  A --> A0[analyze]
+  A --> A1[preview]
+  A --> A2[apply]
+  A --> A3[group]
 
-- **TypeScript Project Analysis**: Analyze TypeScript codebases and generate detailed statistics
-- **React Component Type Checking**: Validate React component type correspondence across packages
-- **Explicit Architecture**: Clean, maintainable codebase following DDD and SOLID principles
-- **Dependency Injection**: Fully testable with InversifyJS container
-- **Rich CLI Experience**: Colorful output with chalk and comprehensive help system
-
-## Installation
-
-```bash
-# Install globally
-npm install -g @codefast/cli
-
-# Or use with npx
-npx @codefast/cli --help
+  M --> M0[sync]
 ```
 
-## Usage
+---
 
-### Available Commands
+## Requirements
 
-#### Hello Command
+- Node.js `>=22.0.0`
+- pnpm (recommended)
 
-```bash
-codefast hello [options]
-codefast hello --name "Developer"
-```
-
-Simple greeting command for testing CLI functionality.
-
-**Options:**
+---
 
-- `-n, --name <name>`: Name to greet (default: "World")
-
-#### Analyze Command
+## Installation
 
 ```bash
-codefast analyze [options]
-codefast analyze --pattern "src/**/*.ts" --config "./tsconfig.json"
-```
-
-Analyze TypeScript project and generate statistics about classes, functions, and interfaces.
-
-**Options:**
-
-- `-p, --pattern <pattern>`: File pattern to analyze (default: "src/**/*.ts")
-- `-c, --config <path>`: Path to tsconfig.json file
-
-**Example Output:**
-
-```text
-🔍 Analyzing TypeScript project...
-✅ Found 45 TypeScript files
-⚠️  Loaded 45 source files for analysis
-📊 Project Statistics:
-  Classes: 12
-  Functions: 89
-  Interfaces: 23
-```
-
-#### Check Component Types Command
+# Install globally
+pnpm add -g @codefast/cli
 
-```bash
-codefast check-component-types [options]
-codefast check-component-types --packages-dir "packages"
+# Or run without installing
+pnpm dlx @codefast/cli --help
 ```
 
-Check React component type correspondence across packages in a monorepo.
+---
 
-**Options:**
+## Quick start
 
-- `-d, --packages-dir <dir>`: Packages directory to analyze (default: "packages")
-
-## Architecture
+```bash
+# 1. Preview proposed changes — no files written
+codefast arrange preview packages/ui/src/components
 
-This CLI follows **Explicit Architecture** principles, ensuring clear separation of concerns, testability, and maintainability.
+# 2. Apply after reviewing the diff
+codefast arrange apply packages/ui/src/components
 
-### Directory Structure
+# 3. Regenerate package exports from built dist/
+codefast mirror sync
 
-```text
-src/
-├── core/                           # Core business logic
-│   └── application/               # Application layer
-│       ├── ports/                 # Interface definitions
-│       │   ├── analysis/          # Analysis service interfaces
-│       │   ├── services/          # Service interfaces
-│       │   └── system/            # System service interfaces
-│       └── use-cases/             # Business workflows
-├── infrastructure/                # Technical implementations
-│   └── adapters/                  # Port implementations
-│       ├── analysis/              # Analysis service adapters
-│       ├── services/              # Service adapters
-│       └── system/                # System service adapters
-├── commands/                      # CLI command handling
-├── di/                           # Dependency injection
-│   └── modules/                  # DI module configurations
-└── index.ts                      # CLI entry point
+# 4. Add @since tags to exported APIs under src/
+codefast tag
 ```
 
-### Architectural Layers
-
-#### 1. Core/Application Layer
+---
 
-Contains business logic and defines interfaces (ports) for external dependencies.
+## `arrange`
 
-**Use Cases:**
+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).
 
-- `AnalyzeProjectUseCase`: Orchestrates TypeScript project analysis
-- `CheckComponentTypesUseCase`: Handles React component type validation
-- `GreetUserUseCase`: Simple greeting functionality
+### Workflow
 
-**Ports (Interfaces):**
+Run the three subcommands in order:
 
-- **Analysis Ports**: `TypeScriptAnalysisPort`, `ComponentAnalysisPort`
-- **Service Ports**: `LoggingServicePort`
-- **System Ports**: `FileSystemSystemPort`, `PathSystemPort`, `UrlSystemPort`
+| 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                     |
 
-#### 2. Infrastructure Layer
+The default `target` when omitted is `packages/ui/src/components`, resolved from `process.cwd()`.
 
-Implements the ports using concrete technologies and external libraries.
+### Flags
 
-**Adapters:**
+| 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    |
 
-- `TsMorphTypescriptAnalysisAdapter`: TypeScript analysis using ts-morph
-- `ReactComponentAnalysisAdapter`: React component analysis
-- `ChalkLoggingServiceAdapter`: Colored console logging with chalk
-- `FastGlobFileSystemSystemAdapter`: File system operations with fast-glob
-- `NodePathSystemAdapter`: Path operations using Node.js path module
-- `NodeUrlSystemAdapter`: URL operations using Node.js url module
+### `arrange group` — one-shot string grouping
 
-#### 3. Commands Layer
+Groups a single class string without touching the filesystem. Useful for checking how a string would be classified before running `apply`:
 
-Handles CLI interface using the Commander.js framework.
-
-- `CommandHandler`: Main command orchestrator with dependency injection
-
-#### 4. Dependency Injection Layer
-
-Manages dependencies using InversifyJS container.
+```bash
+codefast arrange group "relative flex items-center h-10 w-full rounded-md bg-primary text-white hover:bg-primary/90"
+```
 
-**Modules:**
+---
 
-- `infrastructureModule`: Binds infrastructure adapters
-- `applicationModule`: Binds use cases and application services
-- `commandsModule`: Binds command handlers
+## `mirror sync`
 
-### Key Design Principles
+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`.
 
-1. **Dependency Inversion**: All dependencies flow inward toward the core business logic
-2. **Interface Segregation**: Small, focused interfaces for each concern
-3. **Single Responsibility**: Each class has one reason to change
-4. **Testability**: All dependencies are injected and can be mocked
-5. **Explicit Dependencies**: No hidden dependencies or global 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
+```
 
-## Development
+> **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",
+        },
+      },
+    },
+  },
+};
+```
 
-### Prerequisites
+Use your real package names from `package.json#name` (for example `@acme/ui`) and adjust entries to match your workspace.
 
-- Node.js 20.0.0+
-- pnpm 10.13.1+
+> **Migration:** Path-based keys (for example `packages/ui`) are deprecated for `pathTransformations`, `customExports`, `cssExports`, and `skipPackages`. Migrate to package-name keys.
 
-### Setup
+> **Security note:** `.js`, `.mjs`, and `.cjs` config files are loaded via `import()`. Only run `mirror sync` in repositories you trust.
 
-```bash
-# Install dependencies
-pnpm install
+---
 
-# Build the package
-pnpm build
+## Lifecycle hooks (`codefast.config.mjs`)
 
-# Run in development mode
-pnpm dev
-```
+`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.
 
-### Available Scripts
+```javascript
+import { execSync } from "node:child_process";
 
-```bash
-# Development
-pnpm dev                    # Build and watch for changes
-pnpm build                  # Build for production
-pnpm clean                  # Clean build artifacts
-
-# Code Quality
-pnpm lint                   # Run ESLint
-pnpm lint:fix              # Fix ESLint issues
-pnpm type-check            # TypeScript type checking
-pnpm format                # Format code with Prettier
-pnpm format:check          # Check code formatting
-
-# Testing
-pnpm test                  # Run tests
-pnpm test:watch           # Run tests in watch mode
-pnpm test:coverage        # Run tests with coverage
-pnpm test:coverage:ci     # Run tests with CI coverage
+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" });
+    },
+  },
+};
 ```
 
-### Testing Strategy
+Hook contract:
 
-The CLI follows a comprehensive testing approach aligned with the explicit architecture:
+- `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.
 
-#### Unit Testing
+---
 
-- **Domain/Application Layer**: Test use cases with mocked ports
-- **Infrastructure Layer**: Test adapters with real or mocked external dependencies
-- **Commands Layer**: Test command handlers with mocked use cases
+## `tag` / `annotate`
 
-#### Test Structure
+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.
 
-```text
-src/
-├── core/application/use-cases/
-│   ├── analyze-project.use-case.ts
-│   └── analyze-project.use-case.test.ts
-├── infrastructure/adapters/
-│   ├── ts-morph.typescript.analysis.adapter.ts
-│   └── ts-morph.typescript.analysis.adapter.test.ts
-└── commands/
-    ├── command-handler.ts
-    └── command-handler.test.ts
+```bash
+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
 ```
 
-#### Testing Best Practices
-
-- Mock at the port boundaries (interfaces)
-- Use dependency injection for test isolation
-- Test business logic independently of technical details
-- Maintain high coverage for critical paths
-
-### Adding New Features
+What it updates:
 
-#### 1. Define the Port (Interface)
+- 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.
 
-```typescript
-// src/core/application/ports/new-feature.port.ts
-export interface NewFeaturePort {
-  performAction(input: string): Promise<string>;
-}
-```
-
-#### 2. Create the Use Case
-
-```typescript
-// src/core/application/use-cases/new-feature.use-case.ts
-@injectable()
-export class NewFeatureUseCase {
-  constructor(
-    @inject(TYPES.NewFeaturePort)
-    private readonly newFeatureService: NewFeaturePort,
-  ) {}
-
-  async execute(input: string): Promise<void> {
-    const result = await this.newFeatureService.performAction(input);
-    // Handle result...
-  }
-}
-```
+The `<version>` value is read from the nearest `package.json` found by walking up from the target path.
 
-#### 3. Implement the Adapter
-
-```typescript
-// src/infrastructure/adapters/new-feature.adapter.ts
-@injectable()
-export class NewFeatureAdapter implements NewFeaturePort {
-  async performAction(input: string): Promise<string> {
-    // Implementation using external library
-    return `Processed: ${ input }`;
-  }
-}
-```
+---
 
-#### 4. Configure Dependency Injection
+## Grouping philosophy — Render Pipeline Order
 
-```typescript
-// src/di/types.ts
-export const TYPES = {
-  // ... existing types
-  NewFeaturePort: Symbol.for('NewFeaturePort'),
-  NewFeatureUseCase: Symbol.for('NewFeatureUseCase'),
-};
+`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.
 
-// src/di/modules/infrastructure.module.ts
-infrastructureModule.bind<NewFeaturePort>(TYPES.NewFeaturePort).to(NewFeatureAdapter);
+**Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow → Typography → Composite → Motion → Starting → Behavior → State → Selector**
 
-// src/di/modules/application.module.ts
-applicationModule.bind<NewFeatureUseCase>(TYPES.NewFeatureUseCase).to(NewFeatureUseCase);
-```
+| 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-[…]:`       |
 
-#### 5. Add CLI Command
+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.
 
-```typescript
-// src/commands/command-handler.ts
-this.program.command('new-feature').description('Description of new feature').action(async (options) => {
-  await this.newFeatureUseCase.execute(options.input);
-});
-```
+To change a placement, edit `classifyBareUtility` in `src/lib/arrange/tokenizer.ts` and add a corresponding `classifyToken` test in `src/lib/arrange.test.ts`.
 
-## Dependencies
+---
 
-### Core Dependencies
+## Troubleshooting
 
-- **chalk**: Terminal styling and colors
-- **commander**: CLI framework and argument parsing
-- **fast-glob**: Fast file globbing for file system operations
-- **inversify**: Dependency injection container
-- **reflect-metadata**: Metadata reflection for decorators
-- **ts-morph**: TypeScript compiler API wrapper
-- **zod**: Schema validation and type safety
+**`codefast: command not found`**
+Install globally with `pnpm add -g @codefast/cli`, or run via `pnpm dlx @codefast/cli <command>`.
 
-### Development Dependencies
+**`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`.
 
-- **@rslib/core**: Modern build tool for libraries
-- **TypeScript**: Type checking and compilation
-- **Jest**: Testing framework
-- **ESLint**: Code linting
-- **Prettier**: Code formatting
+**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
+---
 
-1. Follow the explicit architecture guidelines
-2. Write tests for new features
-3. Ensure all quality checks pass (`pnpm lint`, `pnpm type-check`, `pnpm test`)
-4. Update documentation for new commands or features
+## Contributing (monorepo setup)
 
-## License
+```bash
+# Build the local CLI (produces dist/bin.js)
+pnpm --filter @codefast/cli build
 
-MIT License - see LICENSE file for details.
+# Run the local entrypoint
+pnpm exec codefast --help
+```
 
-## Related
+A few naming conventions to keep in mind:
 
-- [CodeFast UI Components](../ui/README.md)
+- **`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/analyze-DvtJ3j9m.mjs

@@ -0,0 +1,92 @@
+import "./constants-AtPhF-Ct.mjs";
+import { d as tokenizeClassString } from "./tokenizer-CeZx73Zu.mjs";
+import { r as forEachStringLiteralInClassExpression } from "./collectors-cn-BS8TTQ8O.mjs";
+import { t as jsxClassNameStaticLiteral } from "./collectors-jsx-D9tL2ZPM.mjs";
+import { a as isCnOrTvIdentifier, o as lineOf, r as buildKnownCnTvBindings } from "./ast-helpers-MDRYuIAk.mjs";
+import { c as traverseTvObject, t as collectCnCallsInsideTv } from "./collectors-tv-D2PXZaRt.mjs";
+import { n as walkTsxFiles } from "./walk-DjgQn66n.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 as t };