ai-unit-test-generator 1.4.5 → 2.0.1

package/README.md

@@ -1,467 +1,452 @@
-# ai-test-generator
+# ai-unit-test-generator
 
-> AI-powered unit test generator with smart priority scoring
+> AI-powered unit test generator with intelligent priority scoring
 
-[![npm version](https://img.shields.io/npm/v/ai-test-generator.svg)](https://www.npmjs.com/package/ai-test-generator)
+[![npm version](https://img.shields.io/npm/v/ai-unit-test-generator.svg)](https://www.npmjs.com/package/ai-unit-test-generator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🎯 Features
+## 🎯 Key Features
 
-- **Layered Architecture**: Scores based on code layer (Foundation, Business Logic, State Management, UI)
-- **AI-Optimized**: Designed for AI-powered test generation workflows
-- **Batch Test Generation**: Built-in tools for generating tests with AI (ChatGPT, Claude, Cursor Agent, etc.)
-- **Multiple Metrics**: Combines testability, complexity, dependency count, and more
-- **Flexible Configuration**: JSON-based config with presets for different project types
-- **CLI & Programmatic API**: Use as a command-line tool or integrate into your workflow
-- **Rich Reports**: Generates Markdown and CSV reports with detailed scoring
-- **Progress Tracking**: Mark functions as DONE/TODO/SKIP to track testing progress
+- **🏗️ Layered Architecture Scoring**: Intelligent scoring based on code layers (Foundation, Business, State, UI)
+- **🤖 AI-Native Design**: Perfect integration with Cursor Agent, ChatGPT, Claude, and more
+- **📊 Coverage-Aware**: Integrates code coverage data for smart prioritization (incremental & existing code)
+- **🎨 Multi-Dimensional Scoring**: Combines testability, complexity, dependency count, business criticality, error risk
+- **⚡ Batch Generation**: Automated batch test generation with failure retry and progress tracking
+- **📝 Rich Reports**: Generates detailed scoring reports in Markdown and CSV formats
+- **🔄 Status Management**: Automatic progress tracking (TODO/DONE/SKIP)
 
 ## 📦 Installation
 
-### Global Installation (CLI)
+### Global Installation (Recommended)
 
 ```bash
-npm install -g ai-test-generator
+npm install -g ai-unit-test-generator
 ```
 
 ### Project Installation
 
 ```bash
-npm install --save-dev ai-test-generator
+npm install --save-dev ai-unit-test-generator
 ```
 
 ## 🚀 Quick Start
 
-### 1. Initialize Configuration
-
-```bash
-ai-test init
-```
-
-This creates `ut_scoring_config.json` with default settings.
-
-### 2. Scan and Score
+### 1. Scan Code and Generate Priority Report
 
 ```bash
 ai-test scan
 ```
 
-This will:
-1. Scan your codebase for testable targets
-2. Analyze Git history for error signals
-3. Calculate priority scores
-4. Generate reports in `reports/`
+On first run, it automatically generates a config file `ai-test.config.jsonc` with detailed comments.
 
-### 3. View Report
+The scan will:
+1. Analyze code structure and identify testable targets
+2. Auto-run Jest coverage analysis (if installed)
+3. Analyze Git history for error signals
+4. Calculate multi-dimensional priority scores
+5. Generate sorted report (`reports/ut_scores.md`)
 
-```bash
-# View complete report
-cat reports/ut_scores.md
+**Output Example:**
 
-# View P0 targets only
-grep "| P0 |" reports/ut_scores.md
-
-# Export P0 targets to file
-grep "| P0 |" reports/ut_scores.md | awk -F'|' '{print $2}' > p0_targets.txt
+```markdown
+| Status | Score | Priority | Name | Type | Layer | Path | Coverage | CS | BC | CC | ER | Testability | DepCount |
+|--------|-------|----------|------|------|-------|------|----------|----|----|----|----|-------------|----------|
+| TODO | 8.5 | P0 | validatePayment | function | Business Logic | src/services/payment.ts | 0.0% | 10 | 10 | 8 | 7 | 9 | 12 |
+| TODO | 7.8 | P0 | formatCurrency | function | Foundation | src/utils/format.ts | 15.0% | 8 | 6 | 5 | 8 | 10 | 8 |
 ```
 
-### 4. Generate Tests with AI
+### 2. Generate Tests
 
 ```bash
-# Generate prompt for AI
-ai-test gen-prompt -p P0 -n 10 > prompt.txt
-
-# Copy prompt.txt to your AI tool (ChatGPT, Claude, Cursor, etc.)
-# Get the response, save as response.txt
+# Generate tests for 10 functions (default)
+ai-test generate
 
-# Extract test files from AI response
-ai-test extract-tests response.txt
-
-# Run tests
-npm test
-
-# Mark as done
-ai-test mark-done func1 func2 func3
+# Generate tests for 20 functions
+ai-test generate -n 20
 ```
 
-## 📖 CLI Commands
-
-### `ai-test init`
+The command will:
+1. Select the top N highest-priority untested functions from the report
+2. Invoke Cursor Agent to auto-generate tests
+3. Extract and save test files
+4. Run Jest to validate tests
+5. Auto-update report status to DONE
+6. Generate failure hints for next iteration if tests fail
 
-Initialize UT scoring configuration.
+### 3. Track Progress
 
 ```bash
-ai-test init [options]
+# View report
+cat reports/ut_scores.md
 
-Options:
-  -p, --preset <type>   Use preset config (default)
-  -o, --output <path>   Output config file path (default: ut_scoring_config.json)
+# View P0 priority tasks
+grep "| P0 |" reports/ut_scores.md
+
+# View pending tasks
+grep "| TODO |" reports/ut_scores.md
 ```
 
+## 📖 CLI Commands
+
 ### `ai-test scan`
 
-Scan code and generate UT priority scoring report.
+Scan code and generate priority report
 
 ```bash
 ai-test scan [options]
 
 Options:
-  -c, --config <path>   Config file path (default: ut_scoring_config.json)
+  -c, --config <path>   Config file path (default: ai-test.config.jsonc)
   -o, --output <dir>    Output directory (default: reports)
-  --skip-git            Skip Git signals generation
+  --skip-git            Skip Git history analysis
 ```
 
 **Output Files:**
-- `reports/targets.json` - List of all scanned targets
+- `reports/targets.json` - List of scanned targets
 - `reports/git_signals.json` - Git analysis data
-- `reports/ut_scores.md` - Priority scoring report (Markdown, sorted by score)
-- `reports/ut_scores.csv` - Priority scoring report (CSV)
+- `reports/ut_scores.md` - Markdown format report (sorted by score)
+- `reports/ut_scores.csv` - CSV format report
 
-### `ai-test gen-prompt`
+### `ai-test generate`
 
-Generate AI prompt for batch test generation.
+Generate unit tests (using Cursor Agent)
 
 ```bash
-ai-test gen-prompt [options] > prompt.txt
+ai-test generate [options]
 
 Options:
-  -p, --priority <level>     Filter by priority (P0, P1, P2, P3)
-  -l, --layer <name>         Filter by layer (Foundation, Business, State, UI)
-  -n, --limit <count>        Limit number of targets
-      --skip <count>         Skip first N targets (for pagination)
-      --min-score <score>    Minimum score threshold
-      --report <path>        Report file path (default: reports/ut_scores.md)
-      --framework <name>     Project framework (default: React + TypeScript)
-      --hints <text>         Inject failure hints text into prompt
-      --hints-file <path>    Inject failure hints from file (e.g., reports/hints.txt)
-      --only-paths <csv>     Restrict to specific source paths (comma-separated)
+  -n, --count <number>  Number of functions to generate tests for (default: 10)
 ```
 
-**Example:**
-```bash
-# Generate prompt for 10 P0 functions
-ai-test gen-prompt -p P0 -n 10 > prompt.txt
-
-# Generate prompt for Foundation layer with high scores
-ai-test gen-prompt -l Foundation --min-score 7.5 -n 5 > prompt.txt
-
-# Generate next batch (skip first 10)
-ai-test gen-prompt -p P0 --skip 10 -n 10 > prompt.txt
-```
-
-### `ai-test extract-tests`
-
-Extract test files from AI response.
-
-```bash
-ai-test extract-tests <response-file> [options]
-
-Options:
-  --overwrite    Overwrite existing test files
-  --dry-run      Show what would be created without actually creating files
-```
-
-**Example:**
-```bash
-# Extract tests from AI response
-ai-test extract-tests response.txt
-
-# Dry-run to see what would be created
-ai-test extract-tests response.txt --dry-run
-
-# Overwrite existing tests
-ai-test extract-tests response.txt --overwrite
-```
-
-### `ai-test mark-done`
-
-Mark functions as done in the scoring report.
-
-```bash
-ai-test mark-done <function-names...> [options]
-
-Options:
-  --report <path>       Report file path (default: reports/ut_scores.md)
-  --status <status>     Mark status: DONE or SKIP (default: DONE)
-  --dry-run             Show what would be changed without actually changing
-```
-
-**Example:**
-```bash
-# Mark functions as done
-ai-test mark-done disableDragBack getMediumScale
-
-# Mark as skipped
-ai-test mark-done complexFunction --status SKIP
-
-# Dry-run
-ai-test mark-done func1 func2 --dry-run
-```
+The command automatically:
+- Selects highest-priority untested functions
+- Generates AI prompt and invokes Cursor Agent
+- Extracts and saves test files
+- Runs tests for validation
+- Updates report status
 
 ## ⚙️ Configuration
 
-### Basic Configuration
+On first run of `ai-test scan`, a config file `ai-test.config.jsonc` is auto-generated with detailed comments.
 
-```json
+### Core Configuration
+
+```jsonc
 {
-  "scoringMode": "layered",
+  "scoringMode": "layered",  // Scoring mode: layered or legacy
+  
+  // Coverage configuration
+  "coverage": {
+    "runBeforeScan": true,  // Auto-run Jest coverage before scan
+    "command": "npx jest --coverage --silent",
+    "summaryPath": "coverage/coverage-summary.json"
+  },
+  
+  // Coverage scoring mapping
+  "coverageScoring": {
+    "naScore": 5,  // Default score when coverage data is unavailable
+    "mapping": [
+      { "lte": 0, "score": 10 },    // 0% coverage → highest priority
+      { "lte": 40, "score": 8 },    // 1-40% → high priority
+      { "lte": 70, "score": 6 },    // 41-70% → medium priority
+      { "lte": 90, "score": 3 },    // 71-90% → low priority
+      { "lte": 100, "score": 1 }    // 91-100% → lowest priority
+    ]
+  },
+  
+  // Layer configuration
   "layers": {
     "foundation": {
-      "name": "Foundation (基础工具层)",
-      "patterns": ["utils/**", "helpers/**", "constants/**"],
+      "name": "Foundation (Utils & Helpers)",
+      "patterns": ["**/utils/**", "**/helpers/**", "**/constants/**"],
       "weights": {
-        "testability": 0.50,
-        "dependencyCount": 0.30,
-        "complexity": 0.20
+        "testability": 0.30,      // Testability weight
+        "dependencyCount": 0.25,  // Dependency count weight
+        "complexity": 0.15,       // Complexity weight
+        "BC": 0.10,              // Business criticality weight
+        "ER": 0.10,              // Error risk weight
+        "coverage": 0.10          // Coverage weight
       },
       "thresholds": {
-        "P0": 7.5,
-        "P1": 6.0,
-        "P2": 4.0
+        "P0": 8.0,  // Score ≥8.0 = P0 (must test)
+        "P1": 6.5,  // Score 6.5-7.9 = P1 (high priority)
+        "P2": 5.0   // Score 5.0-6.4 = P2 (medium priority), <5.0 = P3
       }
     }
+    // ... other layer configurations
   }
 }
 ```
 
-### Presets
-
-- **default**: Balanced scoring for general projects
-- **react**: Optimized for React applications
-- **node**: Optimized for Node.js projects
-
 ## 📊 Priority Levels
 
 | Priority | Score Range | Description | Action |
 |----------|-------------|-------------|--------|
-| **P0** | ≥7.5 | Must test | Generate immediately with AI |
-| **P1** | 6.0-7.4 | High priority | Batch generate |
-| **P2** | 4.0-5.9 | Medium priority | Generate with careful review |
-| **P3** | <4.0 | Low priority | Optional coverage |
+| **P0** | ≥8.0 | Must test | Generate immediately |
+| **P1** | 6.5-7.9 | High priority | Batch generate |
+| **P2** | 5.0-6.4 | Medium priority | Generate with review |
+| **P3** | <5.0 | Low priority | Optional coverage |
 
-## 🏗️ Architecture
+## 🏗️ Layered Architecture
 
-### Layered Scoring System
+### 1. Foundation Layer
+- **Characteristics**: Utility functions, helpers, constants
+- **Weights**: High testability weight (30%)
+- **Threshold**: P0 ≥ 8.0
 
-1. **Foundation Layer**: Utils, helpers, constants
-   - High testability weight (50%)
-   - Focus on pure functions
-   
-2. **Business Logic Layer**: Services, APIs, data processing
-   - Balanced metrics
-   - Critical for correctness
+### 2. Business Logic Layer
+- **Characteristics**: Services, APIs, data processing
+- **Weights**: Balanced multi-dimensional scoring
+- **Threshold**: P0 ≥ 7.5
 
-3. **State Management Layer**: Stores, contexts, reducers
-   - Error risk weight emphasized
-   
-4. **UI Components Layer**: React components, views
-   - Complexity and error risk balanced
+### 3. State Management Layer
+- **Characteristics**: State stores, contexts, reducers
+- **Weights**: Emphasizes error risk
+- **Threshold**: P0 ≥ 7.0
 
-## 🔧 Programmatic Usage
+### 4. UI Components Layer
+- **Characteristics**: React components, views
+- **Weights**: Balanced complexity and error risk
+- **Threshold**: P0 ≥ 6.5
 
-If you need to integrate into your Node.js workflow:
+## 📈 Scoring Metrics Explained
 
-```javascript
-import { exec } from 'child_process'
-import { promisify } from 'util'
+### Coverage Score (CS)
 
-const execAsync = promisify(exec)
+**New Feature**: Integrates code coverage data for both incremental and existing code scenarios.
 
-// Run scoring workflow
-const { stdout } = await execAsync('ai-test scan')
-console.log(stdout)
-```
+- **Score Mapping**:
+  - 0% → 10 points (highest priority, needs testing urgently)
+  - 1-40% → 8 points (high priority)
+  - 41-70% → 6 points (medium priority)
+  - 71-90% → 3 points (low priority)
+  - 91-100% → 1 point (well covered)
+  - N/A → 5 points (no data available)
 
-**Recommended**: Use the CLI directly for simplicity.
+- **Weight**: Configured per layer (typically 10-20%)
 
-## 🤖 AI Integration
+### Testability
 
-This tool is designed for AI-powered test generation workflows:
+- **Pure Functions**: 10/10 (no side effects, easy to test)
+- **Simple Mocks**: 8-9/10 (dependencies easy to mock)
+- **Complex Dependencies**: 4-6/10 (requires complex test setup)
 
-1. **Run scoring** to get prioritized target list
-   ```bash
-   ai-test scan
-   ```
+### Dependency Count
 
-2. **Extract P0 targets**
-   ```bash
-   grep "| P0 |" reports/ut_scores.md | awk -F'|' '{print $2}' > p0_targets.txt
-   ```
+Based on reference count:
+- **≥10 modules referencing**: 10/10 (core module)
+- **5-9 modules**: 10/10
+- **3-4 modules**: 9/10
+- **1-2 modules**: 7/10
+- **No references**: 5/10
 
-3. **Batch Automation with Cursor Agent**
-  ```bash
-  # One batch
-  ai-test run-batch -p P0 -n 10 --skip 0
+### Complexity
 
-  # Run all batches until TODO=0
-  ai-test run-all -p P0 -n 10
-  ```
+- **Cyclomatic Complexity**: 11-15 → 10/10 (medium complexity, worth testing)
+- **Cognitive Complexity**: Analyzed via ESLint
+- **Nesting Depth**: Adjusts complexity score
 
-4. **Failure Feedback Loop**
-  - After each batch, we parse Jest JSON report and write hints into `reports/hints.txt`
-  - Next batch will inject hints via `--hints-file reports/hints.txt`
+### Business Criticality (BC)
 
-### ✅ Quality Assurance (Default Enhanced Mode)
+Based on Git history:
+- Modification frequency
+- Number of contributors
+- Commit message keywords (fix, bug, hotfix)
 
-To balance quality and speed, ai-test-generator enables a light assurance layer by default (inspired by Meta's TestGen-LLM deployment at scale).
+### Error Risk (ER)
 
-- Stability reruns (P0 only):
-  - `run-batch` reruns Jest once for P0 targets to reduce flakiness (runInBand)
-- Coverage-aware prioritization:
-  - `score-ut.mjs` supports coverageBoost to prioritize low-coverage files
-- Failure hints loop:
-  - `jest-failure-analyzer.mjs` produces actionable hints (import path, type errors, timers, selectors)
-  - Hints are injected to the next prompt automatically
+Based on:
+- Error handling code
+- Try-catch blocks
+- Number of conditional branches
 
-Notes:
-- Defaults are conservative (P0 strong, others light) to avoid runtime explosion.
-- You can further tune coverageBoost and thresholds in `ut_scoring_config.json`.
+## 🤖 AI Integration
 
-## 📈 Metrics Explained
+### Using Cursor Agent (Recommended)
 
-### Coverage-aware Scoring (New)
+```bash
+# Auto-generate tests (built-in Cursor Agent integration)
+ai-test generate -n 10
+```
 
-We incorporate code coverage into prioritization, balancing both incremental (new code) and stock (existing code) scenarios.
+### Using Other AI Tools (ChatGPT, Claude)
 
-- Coverage Score (CS) mapping:
-  - 0% → 10 (highest)
-  - 1-40% → 8
-  - 41-70% → 6
-  - 71-90% → 3
-  - 91-100% → 1 (lowest)
-  - N/A → 5 (no data)
-- Default weights (legacy mode): `coverage: 0.20`
-- Layered weights: each layer includes a `coverage` weight (see default config)
-- Optional `coverageBoost` provides a small additive boost for low-coverage files to break ties.
+```bash
+# 1. Generate AI prompt
+ai-test scan
+grep "| TODO |" reports/ut_scores.md | head -10
 
-Coverage is parsed from `coverage/coverage-summary.json` if present. You can run coverage before `scan` to leverage coverage-aware prioritization.
+# 2. Manually copy function info to AI tool
+# 3. Save AI response to a file
+# 4. Run tests for validation
+npm test
+```
 
-Configuration snippet:
+## 🎬 Complete Workflow Example
 
-```json
-{
-  "coverageScoring": {
-    "naScore": 5,
-    "mapping": [
-      { "lte": 0, "score": 10 },
-      { "lte": 40, "score": 8 },
-      { "lte": 70, "score": 6 },
-      { "lte": 90, "score": 3 },
-      { "lte": 100, "score": 1 }
-    ]
-  },
-  "coverageBoost": { "enable": true, "threshold": 60, "scale": 0.5, "maxBoost": 0.5 }
-}
-```
+```bash
+# 1. Install Jest (if not already installed)
+npm i -D jest@29 ts-jest@29 @types/jest@29 jest-environment-jsdom@29
 
-### Testability (50% weight in Foundation layer)
-- Pure functions: 10/10
-- Simple mocks: 8-9/10
-- Complex dependencies: 4-6/10
+# 2. Scan code
+ai-test scan
+# ✅ Auto-generates config file
+# ✅ Auto-runs coverage analysis
+# ✅ Generates priority report
 
-### Dependency Count (30% weight in Foundation layer)
-- ≥10 modules depend on it: 10/10
-- 5-9 modules: 10/10
-- 3-4 modules: 9/10
-- 1-2 modules: 7/10
-- Not referenced: 5/10
+# 3. View report
+cat reports/ut_scores.md
 
-### Complexity (20% weight in Foundation layer)
-- Cyclomatic complexity: 11-15: 10/10
-- Cognitive complexity from ESLint
-- Adjustments for nesting depth, branch count
+# 4. Generate tests (10 functions)
+ai-test generate
 
-## 🛠️ Development
+# 5. View results
+npm test
 
-### Project Structure
+# 6. Continue with next batch
+ai-test generate -n 10
 
-```
-ut-priority-scorer/
-├── bin/
-│   └── ut-score.js           # CLI entry point
-├── lib/
-│   ├── index.js              # Main exports
-│   ├── gen-targets.mjs           # Target generation
-│   ├── gen-git-signals.mjs       # Git analysis
-│   ├── score-ut.mjs              # Scoring engine (supports coverage boost)
-│   ├── gen-test-prompt.mjs       # Build batch prompt (JSON manifest + code blocks)
-│   ├── extract-tests.mjs         # Extract tests (manifest-first, fallback headings)
-│   ├── ai-generate.mjs           # Call cursor-agent chat
-│   ├── jest-runner.mjs           # Run Jest and collect reports/coverage
-│   ├── jest-failure-analyzer.mjs # Parse Jest JSON and produce hints
-│   ├── run-batch.mjs             # Orchestrate one batch
-│   └── run-all.mjs               # Loop through all batches
-├── templates/
-│   ├── default.config.json   # Default preset
-│   ├── react.config.json     # React preset
-│   └── node.config.json      # Node.js preset
-└── docs/
-    ├── workflow.md           # Detailed workflow
-    └── architecture.md       # Architecture design
+# 7. Repeat until all high-priority tests are complete
 ```
 
-## 📝 Examples
+## 🛠️ Advanced Usage
 
-### Example: Scoring a React Project
+### Jest Environment Requirements
 
-```bash
-# Initialize with default config
-ai-test init
+First-time users need to install Jest:
 
-# Customize config if needed
-vim ut_scoring_config.json
+```bash
+npm i -D jest@29 ts-jest@29 @types/jest@29 jest-environment-jsdom@29
+```
 
-# Run scoring
-ai-test scan
+Then add type support in `tsconfig.json`:
 
-# View P0 targets
-grep "| P0 |" reports/ut_scores.md
+```json
+{
+  "compilerOptions": {
+    "typeRoots": ["node_modules/@types"]
+  }
+}
 ```
 
-### Example: npm Scripts Integration
+### Custom Coverage Command
 
-Add to your `package.json`:
+Modify `ai-test.config.jsonc`:
 
-```json
+```jsonc
 {
-  "scripts": {
-    "test:priority": "ai-test scan",
-    "test:p0": "grep '| P0 |' reports/ut_scores.md"
+  "coverage": {
+    "runBeforeScan": true,
+    "command": "npm run test:coverage"  // Custom command
   }
 }
 ```
 
-## 🤝 Contributing
+### Skip Git Analysis
 
-Contributions are welcome! Please read our contributing guidelines.
+If project has no Git history or Git signals are not needed:
 
-## 📄 License
+```bash
+ai-test scan --skip-git
+```
 
-MIT © YuhengZhou
+## 📚 Inspiration
 
-## 🔗 Links
+This project draws inspiration from research and practices:
 
-- [GitHub Repository](https://github.com/temptrip/ai-test-generator)
-- [npm Package](https://www.npmjs.com/package/ai-test-generator)
-- [Issue Tracker](https://github.com/temptrip/ai-test-generator/issues)
+- **Meta TestGen-LLM**: Quality assurance filters and at-scale practices  
+  [Automated Unit Test Improvement using Large Language Models at Meta](https://arxiv.org/abs/2402.09171)
 
-## 📚 Inspiration & Prior Art
+- **ByteDance Midscene.js**: Natural language interface and stability practices  
+  https://github.com/web-infra-dev/midscene
 
-We learned from and adapted ideas in the community:
+- **Airbnb**: Large-scale LLM-assisted migration and batching  
+  https://medium.com/airbnb-engineering/accelerating-large-scale-test-migration-with-llms-9565c208023b
 
-- Meta TestGen-LLM — assurance filters and at-scale practices: [Automated Unit Test Improvement using Large Language Models at Meta](https://arxiv.org/abs/2402.09171)
-- ByteDance Midscene.js (NL to UI Test) — natural language interface and stability practices: `https://github.com/web-infra-dev/midscene`
-- Airbnb — large-scale LLM-aided migration and batching: `https://medium.com/airbnb-engineering/accelerating-large-scale-test-migration-with-llms-9565c208023b`
-- TestART (paper) — iterative generation and template repairs: `https://arxiv.org/abs/2408.03095`
+- **TestART**: Iterative generation and template repair  
+  https://arxiv.org/abs/2408.03095
 
-In ai-test-generator, these ideas shape:
-- Strict output protocol (JSON manifest + per-file code blocks)
+These ideas are reflected in `ai-unit-test-generator` as:
+- Strict output protocol (JSON manifest + code blocks)
 - Failure feedback loop (Jest JSON → actionable hints → next prompt)
 - Batch processing with progress tracking (TODO/DONE/SKIP)
-- Optional coverage-aware prioritization
+- Coverage-aware prioritization
+
+## 🔧 Project Structure
+
+```
+ai-unit-test-generator/
+├── bin/
+│   └── cli.js                    # CLI entry point
+├── lib/
+│   ├── core/                     # 核心分析层（无 AI 依赖）
+│   │   ├── scanner.mjs          # AST 扫描 + 元数据提取
+│   │   ├── git-analyzer.mjs     # Git 历史分析
+│   │   ├── scorer.mjs           # 评分引擎 + AI 增强
+│   │   └── index.mjs            # 模块导出
+│   ├── ai/                       # AI 交互层
+│   │   ├── sampler.mjs          # 智能代码采样
+│   │   ├── context-builder.mjs  # 项目上下文构建
+│   │   ├── analyzer-prompt.mjs  # AI 分析 Prompt
+│   │   ├── validator.mjs        # 响应验证
+│   │   ├── reviewer.mjs         # 交互式审核 UI
+│   │   ├── config-writer.mjs    # 安全配置写入
+│   │   ├── prompt-builder.mjs   # 测试生成 Prompt
+│   │   ├── client.mjs           # Cursor Agent 调用
+│   │   ├── extractor.mjs        # 测试提取
+│   │   └── index.mjs            # 模块导出
+│   ├── testing/                  # 测试执行层
+│   │   ├── runner.mjs           # Jest 运行器
+│   │   ├── analyzer.mjs         # 失败分析
+│   │   ├── coverage-runner.mjs  # 覆盖率分析
+│   │   └── index.mjs            # 模块导出
+│   ├── workflows/                # 工作流编排层
+│   │   ├── init.mjs             # 初始化工作流
+│   │   ├── analyze.mjs          # AI 分析工作流
+│   │   ├── scan.mjs             # 扫描工作流
+│   │   ├── generate.mjs         # 生成工作流
+│   │   ├── batch.mjs            # 批处理
+│   │   ├── all.mjs              # 全自动
+│   │   └── index.mjs            # 模块导出
+│   ├── utils/                    # 工具层
+│   │   ├── config-manager.mjs   # 配置管理
+│   │   ├── scan-manager.mjs     # 扫描管理
+│   │   ├── marker.mjs           # 状态标记
+│   │   └── index.mjs            # 模块导出
+│   └── index.mjs                 # 根导出
+└── templates/
+    └── default.config.jsonc      # 默认配置模板
+```
+
+### Architecture Principles
+
+- **Layered Design**: Clear separation between core analysis, AI interaction, testing, and workflows
+- **Zero AI Dependency in Core**: `lib/core/` can be used without AI features
+- **Modular Exports**: Each layer has `index.mjs` for clean API
+- **Programmatic API**: All workflows can be imported and used programmatically
+
+## 🤝 Contributing
+
+Contributions are welcome! Please submit issues or pull requests.
+
+## 📄 License
+
+MIT © YuhengZhou
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/ai-unit-test-generator)
+- [Technical Documentation](./tech_doc.md)
+- [Changelog](./CHANGELOG.md)
 
 ## 💬 Support
 
-- GitHub Issues: [Report bugs](https://github.com/temptrip/ut-priority-scorer/issues)
-- Documentation: [Read the docs](https://github.com/temptrip/ut-priority-scorer/tree/main/docs)
+Need help? Get support through:
+
+- Read [Technical Documentation](./tech_doc.md)
+- Check [Changelog](./CHANGELOG.md)
+- Submit [GitHub Issues](https://github.com/temptrip/ai-unit-test-generator/issues)
+
+---
 
+**Tip**: For first-time users, it's recommended to test on a small project first to familiarize yourself with the workflow before applying to larger projects.