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

package/README.md

@@ -1,125 +1,339 @@
-# Command `update-exports`
+# @codefast/cli
 
-## Tổng Quan
+Command line interface tools for CodeFast development, built with explicit architecture principles.
 
-Command `update-exports` là một công cụ tự động hóa việc cập nhật cấu hình `exports` trong file `package.json` của các package trong dự án. Nó phân tích mã nguồn để xác định các module được export và tạo cấu trúc exports phù hợp.
+## Overview
 
-## Cách Sử Dụng
+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.
 
-```shell script
-codefast update-exports [options]
+## Features
+
+- **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
 ```
 
-### Tùy Chọn
-
-| Tùy chọn                  | Mô tả                                            |
-| ------------------------- | ------------------------------------------------ |
-| `-p, --package <package>` | Lọc theo tên package cụ thể                      |
-| `-d, --dry-run`           | Chạy mà không thực hiện thay đổi (chỉ xem trước) |
-| `-v, --verbose`           | Hiển thị đầu ra chi tiết                         |
-| `-c, --config <path>`     | Đường dẫn đến file cấu hình tùy chỉnh            |
-
-## Luồng Hoạt Động
-
-```mermaid
-flowchart TD
-    A[Bắt đầu update-exports] --> B[processAllPackages]
-    B --> C[Tìm kiếm packages với findAllPackages]
-    C --> D[Lấy cấu hình với getConfig]
-    D --> E[Tìm tất cả package.json với glob]
-    E --> F{Đã tìm thấy packages?}
-    F -- Không --> G[Hiển thị cảnh báo]
-    G --> Z[Kết thúc]
-    F -- Có --> H[Xử lý từng package]
-    H --> I[processPackage cho từng package]
-    I --> J[Đọc package.json]
-    J --> K{Match với package filter?}
-    K -- Không --> L[Bỏ qua package]
-    K -- Có --> M[Phân tích imports với analyzeImports]
-    M --> N[Lưu kết quả phân tích]
-    N --> O[Tạo exports mới với generateExports]
-    O --> P{Dry run mode?}
-    P -- Có --> Q[Tạo preview exports]
-    Q --> Z
-    P -- Không --> R[Sao lưu package.json]
-    R --> S[Cập nhật package.json với exports mới]
-    S --> Z
+## Usage
+
+### Available Commands
+
+#### Hello Command
+
+```bash
+codefast hello [options]
+codefast hello --name "Developer"
 ```
 
-1. **Khởi tạo và Tìm Kiếm Package**
+Simple greeting command for testing CLI functionality.
 
-- Command đọc các tùy chọn từ người dùng
-- Tìm kiếm tất cả các file `package.json` trong workspace theo mẫu glob được cấu hình
+**Options:**
 
-2. **Xử Lý Từng Package**
+- `-n, --name <name>`: Name to greet (default: "World")
 
-- Kiểm tra xem package có khớp với filter hay không (nếu có)
-- Đọc cấu hình cụ thể cho package
-- Xác định đường dẫn đến file index
+#### Analyze Command
 
-3. **Phân Tích Imports**
+```bash
+codefast analyze [options]
+codefast analyze --pattern "src/**/*.ts" --config "./tsconfig.json"
+```
 
-- Sử dụng ts-morph để phân tích cú pháp của file index
-- Tìm tất cả các khai báo export
-- Chuẩn hóa đường dẫn (ví dụ: @/ thành ./)
-- Bỏ qua các import từ modules bên ngoài
-- Xử lý đường dẫn export theo cấu hình
+Analyze TypeScript project and generate statistics about classes, functions, and interfaces.
 
-4. **Tạo Exports Mới**
+**Options:**
 
-- Dựa trên imports đã phân tích, tạo cấu trúc exports mới
-- So sánh với exports hiện tại
+- `-p, --pattern <pattern>`: File pattern to analyze (default: "src/**/*.ts")
+- `-c, --config <path>`: Path to tsconfig.json file
 
-5. **Lưu Thay Đổi**
+**Example Output:**
 
-- Nếu ở chế độ dry-run:
-  - Tạo preview của exports mới mà không thực hiện thay đổi
-- Nếu không ở chế độ dry-run:
-  - Tạo bản sao lưu của package.json
-  - Cập nhật package.json với exports mới
+```text
+🔍 Analyzing TypeScript project...
+✅ Found 45 TypeScript files
+⚠️  Loaded 45 source files for analysis
+📊 Project Statistics:
+  Classes: 12
+  Functions: 89
+  Interfaces: 23
+```
 
-6. **Báo Cáo Kết Quả**
+#### Check Component Types Command
 
-- Hiển thị thống kê về số lượng package đã xử lý thành công, bỏ qua, thất bại
+```bash
+codefast check-component-types [options]
+codefast check-component-types --packages-dir "packages"
+```
 
-## Cấu Hình
+Check React component type correspondence across packages in a monorepo.
 
-Command `update-exports` sử dụng file cấu hình để xác định:
+**Options:**
 
-- Mẫu glob để tìm packages
-- Các prefix đường dẫn cần loại bỏ
-- Cấu hình cụ thể cho từng package
+- `-d, --packages-dir <dir>`: Packages directory to analyze (default: "packages")
 
-Bạn có thể chỉ định file cấu hình tùy chỉnh bằng tùy chọn `-c, --config`.
+## Architecture
 
-## Ví Dụ
+This CLI follows **Explicit Architecture** principles, ensuring clear separation of concerns, testability, and maintainability.
 
-Cập nhật exports cho tất cả các package:
+### Directory Structure
 
-```shell script
-codefast update-exports
+```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
 ```
 
-Chạy ở chế độ verbose để xem thông tin chi tiết:
+### Architectural Layers
+
+#### 1. Core/Application Layer
+
+Contains business logic and defines interfaces (ports) for external dependencies.
+
+**Use Cases:**
+
+- `AnalyzeProjectUseCase`: Orchestrates TypeScript project analysis
+- `CheckComponentTypesUseCase`: Handles React component type validation
+- `GreetUserUseCase`: Simple greeting functionality
+
+**Ports (Interfaces):**
+
+- **Analysis Ports**: `TypeScriptAnalysisPort`, `ComponentAnalysisPort`
+- **Service Ports**: `LoggingServicePort`
+- **System Ports**: `FileSystemSystemPort`, `PathSystemPort`, `UrlSystemPort`
+
+#### 2. Infrastructure Layer
+
+Implements the ports using concrete technologies and external libraries.
+
+**Adapters:**
+
+- `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
+
+#### 3. Commands Layer
+
+Handles CLI interface using the Commander.js framework.
+
+- `CommandHandler`: Main command orchestrator with dependency injection
+
+#### 4. Dependency Injection Layer
+
+Manages dependencies using InversifyJS container.
+
+**Modules:**
+
+- `infrastructureModule`: Binds infrastructure adapters
+- `applicationModule`: Binds use cases and application services
+- `commandsModule`: Binds command handlers
+
+### Key Design Principles
+
+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
+
+## Development
+
+### Prerequisites
+
+- Node.js 20.0.0+
+- pnpm 10.13.1+
+
+### Setup
 
-```shell script
-codefast update-exports --verbose
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run in development mode
+pnpm dev
+```
+
+### Available Scripts
+
+```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
+```
+
+### Testing Strategy
+
+The CLI follows a comprehensive testing approach aligned with the explicit architecture:
+
+#### 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
+
+#### Test Structure
+
+```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
+```
+
+#### 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
+
+#### 1. Define the Port (Interface)
+
+```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...
+  }
+}
+```
+
+#### 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 }`;
+  }
+}
 ```
 
-Chỉ xử lý một package cụ thể:
+#### 4. Configure Dependency Injection
+
+```typescript
+// src/di/types.ts
+export const TYPES = {
+  // ... existing types
+  NewFeaturePort: Symbol.for('NewFeaturePort'),
+  NewFeatureUseCase: Symbol.for('NewFeatureUseCase'),
+};
 
-```shell script
-codefast update-exports --package @codefast/ui
+// src/di/modules/infrastructure.module.ts
+infrastructureModule.bind<NewFeaturePort>(TYPES.NewFeaturePort).to(NewFeatureAdapter);
+
+// src/di/modules/application.module.ts
+applicationModule.bind<NewFeatureUseCase>(TYPES.NewFeatureUseCase).to(NewFeatureUseCase);
 ```
 
-Xem trước thay đổi mà không thực sự cập nhật:
+#### 5. Add CLI Command
 
-```shell script
-codefast update-exports --dry-run
+```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);
+});
 ```
 
-## Lưu Ý
+## Dependencies
+
+### Core Dependencies
+
+- **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
+
+### Development Dependencies
+
+- **@rslib/core**: Modern build tool for libraries
+- **TypeScript**: Type checking and compilation
+- **Jest**: Testing framework
+- **ESLint**: Code linting
+- **Prettier**: Code formatting
+
+## 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
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Related
 
-- Command sẽ tạo bản sao lưu của các file package.json trước khi thực hiện thay đổi
-- Các exports được tạo dựa trên việc phân tích mã nguồn, đảm bảo tính nhất quán
-- Sử dụng tùy chọn `--dry-run` để kiểm tra các thay đổi trước khi áp dụng
+- [CodeFast UI Components](../ui/README.md)

package/dist/cjs/index.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+let __rslib_import_meta_url__="undefined"==typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_exports__={};function main(){console.log("Hello, world!")}for(var __webpack_i__ in main(),__webpack_exports__)exports[__webpack_i__]=__webpack_exports__[__webpack_i__];Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/cjs/src/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":""}

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+console.log("Hello, world!");

package/dist/esm/src/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@codefast/cli",
-  "version": "0.3.5-canary.0",
-  "description": "CodeFast CLI - A development toolkit for CodeFast.",
+  "version": "0.3.7-canary.0",
+  "description": "Command line interface tools for CodeFast development",
+  "keywords": [
+    "cli",
+    "command-line",
+    "tools",
+    "typescript",
+    "monorepo",
+    "development"
+  ],
+  "homepage": "https://github.com/codefastlabs/codefast/tree/main/packages/cli#readme",
   "bugs": {
     "url": "https://github.com/codefastlabs/codefast/issues"
   },
@@ -12,9 +21,25 @@
   },
   "license": "MIT",
   "author": "Vuong Phan <mr.thevuong@gmail.com>",
+  "sideEffects": false,
   "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "default": "./dist/esm/index.js",
+        "types": "./dist/esm/index.d.ts"
+      },
+      "require": {
+        "default": "./dist/cjs/index.cjs",
+        "types": "./dist/cjs/index.d.cts"
+      }
+    }
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
   "bin": {
-    "codefast": "dist/index.js"
+    "codefast": "./dist/esm/index.js"
   },
   "files": [
     "dist",
@@ -23,36 +48,41 @@
     "LICENSE"
   ],
   "dependencies": {
-    "chalk": "^5.4.1",
+    "chalk": "^5.3.0",
     "commander": "^14.0.0",
-    "glob": "^11.0.3",
-    "inversify": "^7.5.2",
-    "lodash-es": "^4.17.21",
+    "fast-glob": "^3.3.2",
+    "inversify": "^7.6.1",
     "reflect-metadata": "^0.2.2",
     "ts-morph": "^26.0.0",
-    "zod": "4.0.0-beta.20250414T061543"
+    "zod": "^4.0.10"
   },
   "devDependencies": {
-    "@rslib/core": "^0.9.2",
-    "@types/commander": "^2.12.5",
-    "@types/lodash-es": "^4.17.12",
-    "@types/node": "^24.0.1",
-    "eslint": "^9.29.0",
+    "@rslib/core": "^0.11.0",
+    "@swc/core": "^1.13.2",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.1.0",
+    "eslint": "^9.32.0",
+    "jest": "^30.0.5",
+    "jiti": "^2.5.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3",
-    "@codefast/eslint-config": "0.3.5-canary.0",
-    "@codefast/typescript-config": "0.3.5-canary.0"
+    "@codefast/eslint-config": "0.3.7-canary.0",
+    "@codefast/typescript-config": "0.3.7-canary.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "preferUnplugged": true,
   "scripts": {
     "build": "rslib build",
-    "check-types": "tsc --noEmit",
-    "clean": "rimraf dist",
-    "dev": "cross-env NODE_ENV=development rslib build --watch",
-    "lint": "eslint --cache --max-warnings 0",
-    "lint:inspect": "npx @eslint/config-inspector@latest"
+    "clean": "rm -rf dist",
+    "dev": "rslib build --watch",
+    "lint": "TIMING=1 eslint --max-warnings 0 .",
+    "lint:fix": "TIMING=1 eslint --max-warnings 0 --fix .",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:coverage:ci": "jest --coverage --ci",
+    "test:watch": "jest --watch",
+    "type-check": "tsc --noEmit"
   }
 }