codeguard-testgen 1.0.9 → 1.0.11

package/README.md

@@ -1,23 +1,39 @@
-# CodeGuard Test Generator
+# CodeGuard - AI Code Review & Test Generator
 
-AI-powered unit test generator with AST analysis for TypeScript/JavaScript projects. Automatically generates comprehensive Jest tests using Claude, OpenAI, or Gemini.
+AI-powered code review and unit test generator with AST analysis for TypeScript/JavaScript projects. Automatically reviews code quality and generates comprehensive Jest tests using Claude, OpenAI, or Gemini.
 
-> **⚡ NEW: Auto Mode** - Automatically detect and test changed functions based on git diff! Perfect for CI/CD pipelines.
+> **⚡ NEW: Unified Auto Mode** - Automatically review code quality AND generate tests for staged functions!
 > ```bash
-> testgen auto
+> testgen auto    # Reviews code + generates tests
+> testgen review  # Only code review
+> testgen test    # Only test generation
+> testgen doc     # Generate API documentation
 > ```
 
 ## Features
 
+### Code Review
+- 🔍 **AI Code Review**: Comprehensive analysis of code quality, bugs, performance, and security
+- 👨‍💻 **Senior Developer Perspective**: AI reviews code like an experienced developer
+- 📊 **Structured Reports**: Markdown reviews with severity levels (Critical, High, Medium, Low)
+- 🎯 **Context-Aware**: Uses AST analysis to understand full code context before reviewing
+- 📁 **Review History**: All reviews saved to `reviews/` directory for reference
+
+### Test Generation
 - 🤖 **AI-Powered**: Uses Claude, OpenAI GPT, or Google Gemini to generate intelligent tests
 - 🔍 **AST Analysis**: Deep code analysis using Babel parser for accurate test generation
 - 📦 **Codebase Indexing**: Optional caching for 100x faster analysis on large projects
 - 🎯 **Multiple Modes**: File-wise, folder-wise, function-wise, or auto test generation
-- ⚡ **Auto Mode**: Detects git changes and automatically generates tests for modified functions
 - ✅ **Smart Validation**: Detects incomplete tests, missing assertions, and legitimate failures
 - 🔄 **Iterative Fixing**: Automatically fixes import errors, missing mocks, and test issues
 - 📋 **TypeScript Support**: Full support for TypeScript types, interfaces, and decorators
 
+### Unified Workflow
+- ⚡ **Auto Mode**: Reviews code quality + generates tests for changed functions
+- 🔄 **Git Integration**: Detects changes via git diff (staged and unstaged)
+- 🚀 **CI/CD Ready**: Non-interactive modes perfect for automation
+- 📚 **Documentation Mode**: AI-powered OpenAPI/Swagger documentation generation
+
 ## Installation
 
 ### Global Installation (Recommended)
@@ -51,7 +67,14 @@ Create a `codeguard.json` file in your project root:
   },
   "testDir": "src/tests",
   "extensions": [".ts", ".tsx", ".js", ".jsx"],
-  "excludeDirs": ["node_modules", "dist", "build", ".git", "coverage"]
+  "excludeDirs": ["node_modules", "dist", "build", ".git", "coverage"],
+  "validationInterval": 5,
+  "docsDir": "docs",
+  "docFormat": "json",
+  "docTitle": "My API Documentation",
+  "docVersion": "1.0.0",
+  "includeGenericFunctions": true,
+  "repoDoc": false
 }
 ```
 
@@ -65,6 +88,177 @@ Create a `codeguard.json` file in your project root:
 | `testDir` | No | Directory for test files (default: `src/tests`) |
 | `extensions` | No | File extensions to process (default: `.ts`, `.tsx`, `.js`, `.jsx`) |
 | `excludeDirs` | No | Directories to exclude from scanning |
+| `validationInterval` | No | Validation frequency in function-wise mode: `undefined` = no validation, `0` = only at end, `N` = validate every N functions |
+| `docsDir` | No | Directory for generated documentation (default: `docs`) |
+| `docFormat` | No | Documentation format: `json` or `yaml` (default: `json`) |
+| `docTitle` | No | API documentation title (default: from package.json name) |
+| `docVersion` | No | API version (default: from package.json version) |
+| `includeGenericFunctions` | No | Include non-API functions in documentation (default: `true`) |
+| `repoDoc` | No | Document entire repository (`true`) or only staged changes (`false`, default) |
+| `reviewSteps` | No | Array of review steps with custom rulesets (see below) |
+| `reviewExecutionMode` | No | How to execute review steps: `parallel` or `sequential` (default: `parallel`) |
+
+### Configurable Review Steps
+
+Configure custom review steps with rulesets defined in markdown files. Each ruleset is stored in the `codeguard-ruleset/` folder at your project root.
+
+```json
+{
+  "reviewExecutionMode": "parallel",
+  "reviewSteps": [
+    {
+      "id": "code-quality",
+      "name": "Code Quality",
+      "category": "quality",
+      "type": "ai",
+      "enabled": true,
+      "ruleset": "code-quality.md"
+    },
+    {
+      "id": "security",
+      "name": "Security Vulnerabilities",
+      "category": "security",
+      "type": "ai",
+      "enabled": true,
+      "ruleset": "security.md"
+    }
+  ]
+}
+```
+
+**Review Step Options:**
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `id` | Yes | Unique identifier for the step |
+| `name` | Yes | Display name for the review step |
+| `category` | Yes | Category of the review (e.g., `quality`, `security`, `performance`) |
+| `type` | Yes | Type of review (currently only `ai` supported) |
+| `enabled` | Yes | Whether this step is active (`true` or `false`) |
+| `ruleset` | Yes | Filename of markdown ruleset in `codeguard-ruleset/` folder |
+
+**Ruleset Files:**
+
+Rulesets are markdown files stored in `codeguard-ruleset/` at your project root:
+
+```
+your-project/
+├── codeguard.json
+├── codeguard-ruleset/
+│   ├── code-quality.md
+│   ├── security.md
+│   ├── performance.md
+│   └── custom-rules.md
+└── src/
+```
+
+Each ruleset file can contain:
+- Detailed review criteria
+- Specific rules and guidelines
+- Examples and code snippets
+- Severity guidelines
+- OWASP references (for security)
+- Best practices documentation
+
+**Example Ruleset File** (`codeguard-ruleset/code-quality.md`):
+
+```markdown
+# Code Quality Review Ruleset
+
+## Review Criteria
+
+### 1. Naming Conventions
+- Functions: Use clear, descriptive names
+- Variables: Use meaningful names
+- Boolean variables: Prefix with is, has, should
+
+### 2. Code Complexity
+- Functions should be concise (< 50 lines)
+- Cyclomatic complexity should be low (< 10)
+- Avoid deeply nested conditionals
+
+...
+```
+
+**Execution Modes:**
+
+- **`parallel`** (default): All enabled review steps run simultaneously for faster completion
+- **`sequential`**: Steps run one after another in the order defined
+
+**Default Review Steps:**
+
+If you don't specify `reviewSteps` in your config, CodeGuard uses these default steps:
+- ✅ **Code Quality** (`code-quality.md`) - Naming, complexity, readability, best practices
+- ✅ **Potential Bugs** (`potential-bugs.md`) - Logic errors, edge cases, type issues, async problems
+- ✅ **Performance** (`performance.md`) - Algorithm efficiency, unnecessary computations, memory leaks
+- ✅ **Security** (`security.md`) - Input validation, injection risks, OWASP vulnerabilities
+
+**Included Ruleset Files:**
+
+CodeGuard comes with comprehensive default rulesets in `codeguard-ruleset/`:
+- `code-quality.md` - 8 categories including naming, complexity, patterns, error handling
+- `potential-bugs.md` - 8 categories covering logic errors, edge cases, async issues
+- `performance.md` - 8 categories for algorithms, caching, data structures, optimizations
+- `security.md` - OWASP Top 10 coverage with specific checks and references
+
+You can customize these files or create your own rulesets for project-specific requirements.
+
+**Output Format:**
+
+Reviews are organized by step in the final markdown file:
+
+```markdown
+# Code Review
+
+## Summary
+[Overall assessment]
+
+## Files Changed
+[List of files]
+
+## Code Quality
+[Findings from code quality step]
+
+## Security Vulnerabilities
+[Findings from security step]
+
+## Performance Issues
+[Findings from performance step]
+
+## Conclusion
+[Final assessment]
+```
+
+See `codeguard.example.json` for a complete configuration example with additional review steps like Accessibility and Documentation Quality.
+
+### Validation Interval
+
+The `validationInterval` option controls when the full test suite is validated during function-wise test generation:
+
+- **`undefined` (default)**: No periodic validation - fastest, tests each function independently
+- **`0`**: Validate only at the end after all functions are processed
+- **`N` (number)**: Validate every N functions to catch integration issues early
+
+**Example use cases:**
+```json
+{
+  "validationInterval": undefined  // Fast - no validation checkpoints
+}
+```
+
+```json
+{
+  "validationInterval": 5  // Validate after every 5 functions
+}
+```
+
+```json
+{
+  "validationInterval": 0  // Validate only once at the end
+}
+```
+
+**Recommendation**: Use `5` or `10` for large files with many functions to catch integration issues early. Use `undefined` for fastest processing.
 
 ### Getting API Keys
 
@@ -77,7 +271,9 @@ Create a `codeguard.json` file in your project root:
 
 | Command | Description | Use Case |
 |---------|-------------|----------|
-| `testgen auto` | Auto-detect and test changed functions | CI/CD, daily development |
+| `testgen auto` | Review code quality + generate tests | Complete workflow, CI/CD |
+| `testgen review` | Only review code changes | Code review, quality checks |
+| `testgen test` | Only generate tests for changes | Testing workflow |
 | `testgen` | Interactive mode - choose mode manually | Exploratory testing |
 | Mode 1: File-wise | Generate tests for entire file | New files, comprehensive coverage |
 | Mode 2: Folder-wise | Generate tests for all files in folder | Batch processing |
@@ -85,18 +281,94 @@ Create a `codeguard.json` file in your project root:
 
 ## Usage
 
-### Auto Mode (Recommended for CI/CD)
+### Auto Mode - Complete Workflow (Recommended)
 
-Automatically detect and test changed functions based on git diff:
+Automatically review code quality and generate tests for changed functions:
 
 ```bash
 testgen auto
 ```
 
-or
+**What it does:**
+1. **Reviews changed code** for quality, bugs, performance, and security issues
+2. **Generates comprehensive tests** for modified functions
+3. Saves review to `reviews/{filename}.review.md`
+4. Creates or updates test files
+
+**Example output:**
+```
+🔍 Scanning git changes for review...
+📝 Found changes in 1 file(s) to review
+
+🔄 Reviewing: src/services/user.service.ts
+   📦 Changed functions: createUser, updateUser
+   ✅ Review completed
+
+📁 Reviews saved to: reviews/ directory
+
+============================================================
+
+🔍 Scanning git changes for testing...
+📝 Found changes in 1 file(s)
+
+🔄 Processing: src/services/user.service.ts
+   📦 Changed functions: createUser, updateUser
+   ✅ Tests generated successfully
+```
+
+### Review Only Mode
+
+Get AI code review without generating tests:
 
 ```bash
-codeguard auto
+testgen review
+```
+
+**What gets reviewed:**
+- 🎯 **Code Quality**: Naming, complexity, readability, best practices
+- 🐛 **Potential Bugs**: Logic errors, edge cases, type mismatches, async issues
+- ⚡ **Performance**: Inefficient algorithms, memory leaks, unnecessary computations
+- 🔒 **Security**: Input validation, injection risks, authentication issues
+
+**Review output** (`reviews/{filename}.review.md`):
+```markdown
+# Code Review: user.service.ts
+
+## Summary
+Overall code quality is good with some areas for improvement...
+
+## Findings
+
+### 🔴 Critical Issues
+#### [Security] Missing Input Validation
+**Function**: `createUser`
+**Issue**: Email parameter not validated before database insertion...
+**Recommended Fix**: 
+...typescript
+if (!email || !email.includes('@')) {
+  throw new Error('Invalid email');
+}
+...
+
+### 🟡 Medium Priority Issues
+#### [Performance] Inefficient Loop
+...
+
+## ✅ Positive Aspects
+- Well-structured error handling
+- Clear function naming
+
+## 💡 General Recommendations
+1. Add input validation for all public functions
+2. Consider adding JSDoc comments
+```
+
+### Test Generation Only Mode
+
+Generate tests without code review:
+
+```bash
+testgen test
 ```
 
 **How it works:**
@@ -106,7 +378,9 @@ codeguard auto
 4. Automatically generates or updates tests for those functions
 5. No user interaction required - perfect for automation!
 
-**Example workflow:**
+**Example workflows:**
+
+**Complete workflow (review + test):**
 ```bash
 # Make changes to your code
 vim src/services/user.service.ts
@@ -114,10 +388,31 @@ vim src/services/user.service.ts
 # Stage your changes
 git add src/services/user.service.ts
 
-# Auto-generate tests for changed functions
+# Review code quality and generate tests
 testgen auto
 ```
 
+**Review only:**
+```bash
+# Get code review for staged changes
+testgen review
+
+# Check the review
+cat reviews/user.service.review.md
+```
+
+**Test generation only:**
+```bash
+# Generate tests without review
+testgen test
+```
+
+**Documentation generation:**
+```bash
+# Generate API documentation
+testgen doc
+```
+
 **Output:**
 ```
 🧪 AI-Powered Unit Test Generator with AST Analysis
@@ -143,10 +438,12 @@ testgen auto
 ```
 
 **Benefits:**
+- 🔍 **Quality Assurance**: Catch issues before they reach production
 - ⚡ **Fast**: Only processes changed files
-- 🎯 **Targeted**: Generates tests only for modified functions
+- 🎯 **Targeted**: Reviews and tests only modified functions
 - 🔄 **CI/CD Ready**: Non-interactive, perfect for automation
 - 🛡️ **Safe**: Preserves existing tests for unchanged functions
+- 📊 **Trackable**: All reviews saved for historical reference
 
 **What files are processed:**
 - ✅ Source files with supported extensions (`.ts`, `.tsx`, `.js`, `.jsx`)
@@ -195,16 +492,174 @@ Generate tests for specific functions:
 - Preserves existing tests for other functions
 - Ideal for incremental test development
 
-#### 4. Auto Mode
-Automatically detect and test changed functions:
+#### 4. Auto Mode (Unified)
+Review code quality and generate tests automatically:
 - Analyzes git diff (staged and unstaged changes)
-- AI identifies which functions were modified
-- Generates tests only for changed exported functions
+- AI reviews code for quality, bugs, performance, security
+- Generates comprehensive review markdown files
+- Creates tests for changed exported functions
 - Non-interactive - perfect for CI/CD pipelines
 - Use: `testgen auto`
 
+#### 5. Review Mode
+AI-powered code review only:
+- Comprehensive analysis by senior-level AI reviewer
+- Reviews code quality, potential bugs, performance issues, security vulnerabilities
+- Uses AST tools to understand full context
+- Generates structured markdown reports
+- Use: `testgen review`
+
+#### 6. Test Mode
+Test generation only:
+- Generates tests for changed functions
+- Skips code review process
+- Faster when you only need tests
+- Use: `testgen test`
+
+#### 7. Documentation Mode
+AI-powered API documentation generation:
+- **Default**: Documents only staged/changed functions (like review/test modes)
+- **Full Repo**: Set `"repoDoc": true` to document entire codebase
+- Analyzes codebase using AST tools
+- Auto-detects API endpoints (Express, NestJS, Fastify, Koa)
+- Generates comprehensive OpenAPI 3.0 specification
+- Documents both API routes and generic functions
+- Smart merge with existing documentation
+- Supports JSON and YAML formats
+- Use: `testgen doc`
+
+**Two modes:**
+
+**1. Changed Files Only (Default)** - `"repoDoc": false` or omitted
+- Works like `testgen review` and `testgen test`
+- Only documents staged/changed functions
+- Fast and targeted
+- Perfect for incremental updates
+- Requires git repository
+
+**2. Full Repository** - `"repoDoc": true`
+- Documents entire codebase
+- Comprehensive documentation generation
+- Useful for initial documentation or major updates
+- No git requirement
+
+**What it documents:**
+- ✅ **API Endpoints**: All REST API routes with methods, paths, parameters
+- ✅ **Request/Response Schemas**: Inferred from TypeScript types
+- ✅ **Authentication**: Detects and documents auth requirements
+- ✅ **Error Responses**: Documents error cases and status codes
+- ✅ **Generic Functions**: Optional documentation for utility functions
+- ✅ **Usage Examples**: AI-generated examples for each endpoint
+
+**Supported Frameworks:**
+- **Express**: `app.get()`, `router.post()`, route methods
+- **NestJS**: `@Controller()`, `@Get()`, `@Post()`, decorators
+- **Fastify**: `fastify.route()`, route configurations
+- **Koa**: `router.get()`, middleware patterns
+
+**Example usage:**
+```bash
+# Document only changed/staged functions (default)
+testgen doc
+
+# Output:
+# 📚 Documentation Mode: Generating API documentation
+#
+# 🔍 Scanning git changes for documentation...
+#
+# 📝 Found changes in 2 file(s)
+#
+# 🤖 Generating OpenAPI specification...
+#
+# ✅ Documentation generated successfully
+#
+# ============================================================
+# 📊 Documentation Summary
+# ============================================================
+# ✅ API Endpoints documented: 5
+# ✅ Generic functions documented: 8
+# 📁 Output: docs/openapi.json
+# ============================================================
+
+# For full repository documentation, set in codeguard.json:
+# {
+#   "repoDoc": true
+# }
+```
+
+**Generated OpenAPI spec:**
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "My API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Get all users",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/User" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "email": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+**Smart merging:**
+When existing documentation is found, CodeGuard intelligently merges:
+- ✅ Preserves manually edited descriptions and summaries
+- ✅ Updates schemas with latest types from code
+- ✅ Adds new endpoints without removing manual changes
+- ✅ Maintains custom examples and documentation
+- ✅ Tracks generation metadata and timestamps
+
 ## How It Works
 
+### Code Review Process
+1. **Git Diff Analysis**: Detects changed files and functions
+2. **AST Analysis**: Deep parse of code structure using Babel
+3. **Context Understanding**: AI uses tools to analyze:
+   - Function implementations
+   - Dependencies and imports
+   - Type definitions
+   - Related code context
+4. **Multi-Aspect Review**: Analyzes for:
+   - Code quality and best practices
+   - Potential bugs and edge cases
+   - Performance bottlenecks
+   - Security vulnerabilities
+5. **Structured Report**: Generates markdown with:
+   - Severity-based findings
+   - Code snippets and fixes
+   - Positive observations
+   - Actionable recommendations
+
+### Test Generation Process
 1. **AST Analysis**: Parses your code using Babel to understand structure
 2. **Dependency Resolution**: Analyzes imports and calculates correct paths
 3. **AI Generation**: Uses AI to generate comprehensive test cases
@@ -217,6 +672,24 @@ Automatically detect and test changed functions:
    - Type mismatches
 7. **Failure Detection**: Distinguishes between test bugs and source code bugs
 
+### Documentation Generation Process
+1. **File Scanning**: Recursively scans all source files in the project
+2. **AST Analysis**: Parses each file using Babel to understand structure
+3. **Endpoint Detection**: AI identifies API routes across different frameworks:
+   - Express: `app.METHOD()`, `router.METHOD()`
+   - NestJS: `@Controller()`, `@Get()`, `@Post()`, etc.
+   - Fastify: `fastify.route()`, route configurations
+   - Koa: `router.METHOD()`, middleware chains
+4. **Schema Inference**: Extracts TypeScript types for request/response schemas
+5. **AI Enhancement**: AI generates:
+   - Meaningful descriptions for each endpoint
+   - Parameter documentation
+   - Response examples
+   - Error scenarios
+6. **OpenAPI Generation**: Builds complete OpenAPI 3.0 specification
+7. **Smart Merge**: Intelligently merges with existing documentation
+8. **File Output**: Writes to `docs/openapi.json` or `.yaml`
+
 ## Generated Test Features
 
 The AI generates tests with:
@@ -236,21 +709,19 @@ The AI generates tests with:
 
 ### CI/CD Integration
 
-Auto mode is designed for continuous integration workflows:
+CodeGuard modes are designed for continuous integration workflows:
 
-**GitHub Actions Example:**
+**GitHub Actions - Complete Workflow (Review + Tests):**
 
 ```yaml
-name: Auto Generate Tests
+name: AI Code Review & Test Generation
 
 on:
-  push:
-    branches: [ main, develop ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, develop ]
 
 jobs:
-  generate-tests:
+  review-and-test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -268,33 +739,98 @@ jobs:
       - name: Install CodeGuard
         run: npm install -g codeguard-testgen
       
-      - name: Generate tests for changed functions
+      - name: Review code and generate tests
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
         run: testgen auto
       
-      - name: Commit generated tests
+      - name: Upload review reports
+        uses: actions/upload-artifact@v3
+        with:
+          name: code-reviews
+          path: reviews/
+      
+      - name: Commit generated tests and reviews
         run: |
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
-          git add src/tests/
-          git commit -m "🤖 Auto-generate tests for changed functions" || echo "No changes"
+          git add src/tests/ reviews/
+          git commit -m "🤖 AI code review + tests for changed functions" || echo "No changes"
           git push
 ```
 
+**GitHub Actions - Review Only:**
+
+```yaml
+name: AI Code Review
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  code-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install CodeGuard
+        run: npm install -g codeguard-testgen
+      
+      - name: AI Code Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: testgen review
+      
+      - name: Comment PR with review
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const reviews = fs.readdirSync('reviews/');
+            for (const review of reviews) {
+              const content = fs.readFileSync(`reviews/${review}`, 'utf8');
+              github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: `## AI Code Review: ${review}\n\n${content}`
+              });
+            }
+```
+
 **GitLab CI Example:**
 
 ```yaml
-generate-tests:
-  stage: test
+review-and-test:
+  stage: quality
   script:
     - npm install -g codeguard-testgen
-    - testgen auto
+    - testgen auto  # Review + tests
   artifacts:
     paths:
+      - reviews/
       - src/tests/
   only:
     - merge_requests
+
+review-only:
+  stage: quality
+  script:
+    - npm install -g codeguard-testgen
+    - testgen review
+  artifacts:
+    reports:
+      codequality: reviews/
+  only:
+    - merge_requests
 ```
 
 **Pre-commit Hook:**
@@ -303,11 +839,24 @@ generate-tests:
 #!/bin/bash
 # .git/hooks/pre-commit
 
-# Generate tests for staged changes
+# Review code and generate tests for staged changes
 testgen auto
 
-# Add generated tests to commit
-git add src/tests/
+# Add generated tests and reviews to commit
+git add src/tests/ reviews/
+```
+
+**Pre-push Hook (Review Only):**
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+
+# Quick code review before pushing
+testgen review
+
+# Show review summary
+echo "📊 Code Review Complete - Check reviews/ directory"
 ```
 
 ### Codebase Indexing
@@ -346,7 +895,7 @@ When legitimate bugs are found, they're reported with details for you to fix in
 
 ## Examples
 
-### Example 1: Auto Mode Workflow
+### Example 1: Complete Workflow (Auto Mode)
 
 **Step 1: Make changes to a function**
 ```typescript
@@ -373,7 +922,16 @@ testgen auto
 
 **Output:**
 ```
-🔍 Scanning git changes...
+🔍 Scanning git changes for review...
+📝 Found changes in 1 file(s)
+
+🔄 Reviewing: src/services/user.service.ts
+   📦 Changed functions: createUser
+   ✅ Review completed
+
+============================================================
+
+🔍 Scanning git changes for testing...
 📝 Found changes in 1 file(s)
 
 🔄 Processing: src/services/user.service.ts
@@ -381,7 +939,26 @@ testgen auto
    ✅ Tests generated successfully
 ```
 
-**Result:** Only `createUser` gets new tests, `deleteUser` tests remain unchanged!
+**Results:** 
+- `reviews/user.service.review.md` created with code quality analysis
+- Only `createUser` gets new tests, `deleteUser` tests remain unchanged!
+
+**Review excerpt:**
+```markdown
+### 🟡 Medium Priority Issues
+
+#### [Code Quality] Weak Email Validation
+**Function**: `createUser`
+**Issue**: Email validation only checks for '@' symbol, not comprehensive
+
+**Recommended Fix**:
+```typescript
+const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+if (!emailRegex.test(email)) {
+  throw new Error('Invalid email format');
+}
+```
+```
 
 ### Example 2: Testing a User Service
 
@@ -425,10 +1002,10 @@ describe('UserService', () => {
 
 ## Troubleshooting
 
-### Auto Mode Issues
+### Command Mode Issues
 
 #### "Not a git repository"
-Auto mode requires git to detect changes. Initialize git in your project:
+The `auto`, `test`, and `review` commands require git to detect changes. Initialize git in your project:
 ```bash
 git init
 ```
@@ -445,6 +1022,14 @@ git status
 git diff
 ```
 
+#### Review/Test mode not working
+Make sure you're using the correct command:
+```bash
+testgen auto    # Review + tests
+testgen review  # Only review
+testgen test    # Only tests
+```
+
 #### "No exported functions changed"
 Possible causes:
 1. **AI model misconfigured**: Check your `codeguard.json` has a valid model name:
@@ -534,6 +1119,8 @@ your-project/
 │   └── tests/              # Generated tests
 │       └── services/
 │           └── user.service.test.ts
+├── reviews/                # AI code reviews
+│   └── user.service.review.md
 └── .codeguard-cache/       # Optional index cache
 ```