codeguard-testgen 1.0.14 → 1.0.16

package/README.md

@@ -1,1157 +1,280 @@
-# CodeGuard - AI Code Review & Test Generator
+# CodeGuard
 
-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.
+**AI-powered code review and unit test generator for TypeScript/JavaScript projects.**
 
-> **⚡ NEW: Unified Auto Mode** - Automatically review code quality AND generate tests for staged functions!
-> ```bash
-> testgen auto    # Reviews code + generates tests
-> testgen review  # Only code review
-> testgen test    # Only test generation
-> testgen doc     # Generate API documentation
-> ```
+CodeGuard combines [Abstract Syntax Tree analysis](#how-it-works) with large language models (Claude, OpenAI, or Gemini) to automatically review code quality and generate comprehensive test suites — either on demand or as part of your CI/CD pipeline.
 
-## 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
+## Documentation
 
-### 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
-- ✅ **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
+| Document | Contents |
+|----------|---------|
+| **This file** | Quick-start, commands, and feature overview |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Complete `codeguard.json` reference |
+| [docs/API.md](docs/API.md) | Exported functions, types, and interfaces |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, module map, data-flow diagrams |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Development setup and contribution guide |
+
+---
 
 ## Installation
 
-### Global Installation (Recommended)
+**Global (recommended):**
 
 ```bash
 npm install -g codeguard-testgen
 ```
 
-### Local Installation
+**Local (project dev dependency):**
 
 ```bash
 npm install --save-dev codeguard-testgen
 ```
 
-## Configuration
-
-Create a `codeguard.json` file in your project root:
-
-```json
-{
-  "aiProvider": "claude",
-  "apiKeys": {
-    "claude": "sk-ant-api03-...",
-    "openai": "sk-...",
-    "gemini": "..."
-  },
-  "models": {
-    "claude": "claude-sonnet-4-20250514",
-    "openai": "gpt-4o-mini",
-    "gemini": "gemini-2.0-flash-exp"
-  },
-  "testEnv": "vitest/jest",
-  "testDir": "src/tests",
-  "excludeDirs": ["node_modules", "dist", "build", ".git", "coverage"],
-  "validationInterval": 5,
-  "reviewExecutionMode": "parallel",
-  "reviewSteps": [
-    {
-      "id": "code-quality",
-      "name": "Code Quality",
-      "category": "quality",
-      "type": "ai",
-      "enabled": true,
-      "ruleset": "code-quality.md"
-    },
-    {
-      "id": "security",
-      "name": "Security",
-      "category": "security",
-      "type": "ai",
-      "enabled": true,
-      "ruleset": "security.md"
-    }
-  ]
-}
-```
-
-### Configuration Options
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `aiProvider` | Yes | AI provider to use: `claude`, `openai`, or `gemini` |
-| `apiKeys` | Yes | API keys for the AI providers |
-| `models` | No | Custom model names (uses defaults if not specified) |
-| `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
+**Requirements:** Node.js ≥ 16, and `@babel/parser` + `@babel/traverse` in the target project:
 
-## 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]
+```bash
+npm install --save-dev @babel/parser @babel/traverse
 ```
 
-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:
+## Quick Start
 
-- **`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
-}
-```
+### 1. Create `codeguard.json` in your project root
 
 ```json
 {
-  "validationInterval": 0  // Validate only once at the end
+  "aiProvider": "claude",
+  "apiKeys": {
+    "claude": "sk-ant-..."
+  },
+  "testEnv": "vitest",
+  "testDir": "src/tests"
 }
 ```
 
-**Recommendation**: Use `5` or `10` for large files with many functions to catch integration issues early. Use `undefined` for fastest processing.
-
-### Getting API Keys
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
 
-- **Claude (Anthropic)**: https://console.anthropic.com/
-- **OpenAI**: https://platform.openai.com/api-keys
-- **Gemini (Google)**: https://makersuite.google.com/app/apikey
-
-
-## Quick Reference
-
-| Command | Description | Use Case |
-|---------|-------------|----------|
-| `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 |
-| Mode 3: Function-wise | Generate tests for specific functions | Incremental testing |
-
-## Usage
-
-### Auto Mode - Complete Workflow (Recommended)
-
-Automatically review code quality and generate tests for changed functions:
+### 2. Stage your changes and run
 
 ```bash
+git add src/services/user.service.ts
 testgen auto
 ```
 
-**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
+CodeGuard will review the changed code and generate tests for modified functions. Results are saved to `reviews/code_review.md` and your `testDir`.
 
-**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
+## Commands
 
-============================================================
+| Command | Description |
+|---------|-------------|
+| `testgen auto` | Code review **and** test generation for staged changes |
+| `testgen review` | Code review only |
+| `testgen test` | Test generation only |
+| `testgen doc` | API documentation generation *(in development)* |
+| `testgen` | Interactive mode — choose mode and files manually |
 
-🔍 Scanning git changes for testing...
-📝 Found changes in 1 file(s)
+Both `testgen` and `codeguard` are registered as CLI entry points.
 
-🔄 Processing: src/services/user.service.ts
-   📦 Changed functions: createUser, updateUser
-   ✅ Tests generated successfully
-```
+---
 
-### Review Only Mode
+## Features
 
-Get AI code review without generating tests:
+### Code Review (`testgen review`)
 
-```bash
-testgen review
-```
+- Multi-step review pipeline: code quality, potential bugs, performance, security
+- Each step is driven by a customisable markdown **ruleset** file
+- Steps run in parallel by default
+- Output: `reviews/code_review.md` with severity-tagged findings
 
-**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');
-}
-...
+### Test Generation (`testgen test`)
 
-### 🟡 Medium Priority Issues
-#### [Performance] Inefficient Loop
-...
+- Detects changed files and modified exported functions via git diff
+- Uses AST analysis to understand function signatures, types, and dependencies
+- Generates tests with proper mocks, edge cases, and error scenarios
+- Supports Vitest and Jest
+- Iterative AI loop automatically fixes import errors, missing mocks, and type issues
+- Preserves existing tests for unchanged functions
 
-## ✅ Positive Aspects
-- Well-structured error handling
-- Clear function naming
+### Unified Auto Mode (`testgen auto`)
 
-## 💡 General Recommendations
-1. Add input validation for all public functions
-2. Consider adding JSDoc comments
-```
+Runs review and test generation sequentially in one command. Suitable for pre-commit hooks and CI/CD pipelines.
 
-### Test Generation Only Mode
+### Interactive Mode (`testgen`)
 
-Generate tests without code review:
+Guides you through selecting files and functions manually. Supports:
+- **File-wise:** generate tests for all exported functions in a file
+- **Folder-wise:** batch process every file in a directory
+- **Function-wise:** target specific functions with optional periodic validation
 
-```bash
-testgen test
-```
+### Codebase Indexing
 
-**How it works:**
-1. Reads both `git diff --staged` and `git diff` to find all changes
-2. Identifies which files have been modified
-3. Uses AI to detect which exported functions have changes
-4. Automatically generates or updates tests for those functions
-5. No user interaction required - perfect for automation!
+On the first interactive run you will be offered the option to build a codebase index (stored in `.codeguard-cache/index.json`). The index caches AST analysis results, providing roughly **100× speedup** on subsequent runs.
 
-**Example workflows:**
+---
 
-**Complete workflow (review + test):**
-```bash
-# Make changes to your code
-vim src/services/user.service.ts
+## How It Works
 
-# Stage your changes
-git add src/services/user.service.ts
+### Test Generation
 
-# 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
+1. git diff  →  identify changed source files
+2. AI analysis  →  identify which exported functions changed
+3. For each changed function:
+     a. Build prompt: function AST + imports + type definitions
+     b. AI conversation loop (max 30 iterations)
+        AI calls tools: get_function_ast, get_imports_ast, find_file,
+                        upsert_function_tests, run_tests
+     c. Write test file  →  run tests  →  parse failures
+     d. If tests fail: AI fixes and loops again
+4. Report results
 ```
 
-**Test generation only:**
-```bash
-# Generate tests without review
-testgen test
-```
+### Code Review
 
-**Documentation generation:**
-```bash
-# Generate API documentation
-testgen doc
 ```
-
-**Output:**
+1. git diff  →  identify changed source files
+2. Load enabled review steps from codeguard.json
+3. For each step (in parallel or sequential):
+     a. Read ruleset markdown from codeguard-ruleset/
+     b. AI conversation loop with AST tools
+     c. Write findings to temporary markdown file
+4. Merge all step outputs  →  reviews/code_review.md
 ```
-🧪 AI-Powered Unit Test Generator with AST Analysis
-
-🤖 Auto Mode: Detecting changes via git diff
-
-✅ Using OPENAI (gpt-4o-mini) with AST-powered analysis
-
-🔍 Scanning git changes...
 
-📝 Found changes in 2 file(s)
-
-🔄 Processing: src/services/user.service.ts
-   📦 Changed functions: createUser, updateUser
-   ✅ Tests generated successfully
-
-============================================================
-📊 Auto-Generation Summary
-============================================================
-✅ Successfully processed: 1 file(s)
-📝 Functions tested: 2
-============================================================
-```
+### AI Tool System
 
-**Benefits:**
-- 🔍 **Quality Assurance**: Catch issues before they reach production
-- ⚡ **Fast**: Only processes changed files
-- 🎯 **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
+CodeGuard does not allow the AI to read or write files directly. All file access is mediated through typed tools (`read_file`, `analyze_file_ast`, `upsert_function_tests`, `run_tests`, etc.) that the host process executes. This provides auditability and safe error handling. See [docs/API.md — Tool Definitions](docs/API.md#tool-definitions) for the full list.
 
-**What files are processed:**
-- ✅ Source files with supported extensions (`.ts`, `.tsx`, `.js`, `.jsx`)
-- ✅ Files with exported functions
-- ❌ Test files (`.test.`, `.spec.`, `__tests__/`, `/tests/`)
-- ❌ Files in `node_modules`, `dist`, `build`, etc.
-- ❌ Non-source files (configs, markdown, etc.)
+---
 
-### Interactive Mode
+## Configuration Overview
 
-Simply run the command and follow the prompts:
+Key `codeguard.json` fields:
 
-```bash
-testgen
-```
+| Field | Default | Description |
+|-------|---------|-------------|
+| `aiProvider` | — | `"claude"`, `"openai"`, or `"gemini"` (required) |
+| `apiKeys` | — | API keys for the chosen provider (required) |
+| `testEnv` | `"vitest"` | `"vitest"` or `"jest"` |
+| `testDir` | `"src/tests"` | Output directory for generated tests |
+| `reviewExecutionMode` | `"parallel"` | `"parallel"` or `"sequential"` |
+| `reviewSteps` | 4 built-in steps | Array of `ReviewStep` objects |
 
-or
+Full reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)
 
-```bash
-codeguard
-```
+---
 
-You'll be guided through:
-1. Selecting test generation mode (file/folder/function-wise)
-2. Choosing files or functions to test
-3. Optional codebase indexing for faster processing
-
-### Test Generation Modes
-
-#### 1. File-wise Mode
-Generate tests for a single file:
-- Select from a list of source files
-- Generates comprehensive tests for all exported functions
-- Creates test file with proper structure and mocks
-
-#### 2. Folder-wise Mode
-Generate tests for all files in a directory:
-- Select a folder from your project
-- Processes all matching files recursively
-- Batch generates tests with progress tracking
-
-#### 3. Function-wise Mode
-Generate tests for specific functions:
-- Select a file
-- Choose which functions to test
-- Preserves existing tests for other functions
-- Ideal for incremental test development
-
-#### 4. Auto Mode (Unified)
-Review code quality and generate tests automatically:
-- Analyzes git diff (staged and unstaged changes)
-- 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
-# }
-```
+## Output Files
 
-**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" }
-        }
-      }
-    }
-  }
-}
-```
+| Path | Contents |
+|------|---------|
+| `reviews/code_review.md` | Merged review report from all enabled steps |
+| `<testDir>/**/*.test.ts` | Generated/updated test files |
+| `.codeguard-cache/index.json` | Optional codebase index (auto-managed) |
 
-**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
+## CI/CD Integration
 
-### 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
-4. **Validation**: Checks for completeness, assertions, and coverage
-5. **Execution**: Runs tests with Jest to verify correctness
-6. **Iterative Fixing**: Automatically fixes common issues like:
-   - Import path errors
-   - Missing mocks
-   - Database initialization errors
-   - 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:
-
-- ✅ Proper imports and type definitions
-- ✅ Jest mocks for dependencies
-- ✅ Multiple test cases per function:
-  - Happy path scenarios
-  - Edge cases (null, undefined, empty arrays)
-  - Error conditions
-  - Async behavior testing
-- ✅ Clear, descriptive test names
-- ✅ Complete implementations (no placeholder comments)
-- ✅ Real assertions with expect() statements
-
-## Advanced Features
-
-### CI/CD Integration
-
-CodeGuard modes are designed for continuous integration workflows:
-
-**GitHub Actions - Complete Workflow (Review + Tests):**
+### GitHub Actions — auto mode
 
 ```yaml
-name: AI Code Review & Test Generation
+name: AI Code Review & Tests
 
 on:
   pull_request:
-    branches: [ main, develop ]
+    branches: [main]
 
 jobs:
-  review-and-test:
+  codeguard:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
         with:
-          fetch-depth: 0  # Fetch full history for git diff
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v3
         with:
           node-version: '18'
-      
-      - name: Install dependencies
-        run: npm install
-      
-      - name: Install CodeGuard
-        run: npm install -g codeguard-testgen
-      
-      - name: Review code and generate tests
-        env:
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        run: testgen auto
-      
-      - 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/ 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
+      - run: npm install
+      - run: npm install -g codeguard-testgen
 
-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
+      - name: Review and generate tests
         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:**
+        run: testgen auto
 
-```yaml
-review-and-test:
-  stage: quality
-  script:
-    - npm install -g codeguard-testgen
-    - 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
+      - uses: actions/upload-artifact@v3
+        with:
+          name: code-review
+          path: reviews/
 ```
 
-**Pre-commit Hook:**
+### Pre-commit hook
 
 ```bash
 #!/bin/bash
 # .git/hooks/pre-commit
-
-# Review code and generate tests for staged changes
 testgen auto
-
-# 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
-
-On first run, you'll be prompted to enable codebase indexing:
-
-```
-Enable codebase indexing? (y/n)
-```
-
-Benefits:
-- 100x+ faster analysis on subsequent runs
-- Instant dependency lookups
-- Cached AST parsing
-- Automatic update detection
-
-The index is stored in `.codeguard-cache/` and automatically updates when files change.
-
-### Legitimate Failure Detection
-
-The tool distinguishes between:
-
-**Fixable Test Issues** (automatically fixed):
-- Wrong import paths
-- Missing mocks
-- Incorrect assertions
-- TypeScript errors
-
-**Legitimate Source Code Bugs** (reported, not fixed):
-- Function returns wrong type
-- Missing null checks
-- Logic errors
-- Unhandled edge cases
-
-When legitimate bugs are found, they're reported with details for you to fix in the source code.
-
-## Examples
-
-### Example 1: Complete Workflow (Auto Mode)
-
-**Step 1: Make changes to a function**
-```typescript
-// src/services/user.service.ts
-export const createUser = async (name: string, email: string) => {
-  // Added email validation
-  if (!email.includes('@')) {
-    throw new Error('Invalid email');
-  }
-  
-  return await db.users.create({ name, email });
-};
-
-export const deleteUser = async (id: string) => {
-  return await db.users.delete(id);
-};
-```
-
-**Step 2: Stage changes and run auto mode**
-```bash
-git add src/services/user.service.ts
-testgen auto
-```
-
-**Output:**
-```
-🔍 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
-   📦 Changed functions: createUser
-   ✅ Tests generated successfully
-```
-
-**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
+## Supported AI Providers
 
-#### [Code Quality] Weak Email Validation
-**Function**: `createUser`
-**Issue**: Email validation only checks for '@' symbol, not comprehensive
+| Provider | Config value | Default model |
+|----------|-------------|---------------|
+| Anthropic Claude | `"claude"` | `claude-sonnet-4-5-20250929` |
+| OpenAI | `"openai"` | `gpt-5-mini` |
+| Google Gemini | `"gemini"` | `gemini-2.0-flash-lite` |
 
-**Recommended Fix**:
-```typescript
-const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-if (!emailRegex.test(email)) {
-  throw new Error('Invalid email format');
-}
-```
-```
+All providers share the same retry logic: exponential backoff with jitter, retrying on 429/5xx responses.
 
-### Example 2: Testing a User Service
-
-```typescript
-// src/services/user.service.ts
-export class UserService {
-  async getUser(id: string): Promise<User> {
-    return await this.db.findUser(id);
-  }
-}
-```
-
-Generated test:
-
-```typescript
-// src/tests/services/user.service.test.ts
-import { UserService } from '../../services/user.service';
-
-jest.mock('../../database');
-
-describe('UserService', () => {
-  describe('getUser', () => {
-    test('should return user when id exists', async () => {
-      const mockUser = { id: '123', name: 'John' };
-      const service = new UserService();
-      service.db.findUser = jest.fn().mockResolvedValue(mockUser);
-      
-      const result = await service.getUser('123');
-      
-      expect(result).toEqual(mockUser);
-      expect(service.db.findUser).toHaveBeenCalledWith('123');
-    });
-    
-    test('should handle null id', async () => {
-      const service = new UserService();
-      await expect(service.getUser(null)).rejects.toThrow();
-    });
-  });
-});
-```
+---
 
 ## Troubleshooting
 
-### Command Mode Issues
-
-#### "Not a git repository"
-The `auto`, `test`, and `review` commands require git to detect changes. Initialize git in your project:
-```bash
-git init
-```
-
-#### "No changes detected in source files"
-This means:
-- No staged or unstaged changes exist
-- Only test files were modified (test files are excluded)
-- Changes are in non-source files
-
-Check your changes:
-```bash
-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:
-   ```json
-   {
-     "models": {
-       "openai": "gpt-4o-mini"  // ✅ Correct
-       // NOT "gpt-5-mini" ❌
-     }
-   }
-   ```
-2. **Only internal functions changed**: Auto mode only generates tests for exported functions
-3. **File has no exported functions**: Make sure functions are exported:
-   ```typescript
-   export const myFunction = () => { }  // ✅ Will be tested
-   const internalFunc = () => { }       // ❌ Will be skipped
-   ```
-
-#### Debugging Auto Mode
-Enable detailed logging by checking the console output:
-```bash
-testgen auto
-```
-
-Look for:
-- `📦 Found X exported function(s): ...` - Shows detected functions
-- `🤖 AI response: ...` - Shows what AI detected
-- `📊 AST Analysis result: ...` - Shows file parsing results
-
-### "Configuration Error: codeguard.json not found"
-
-Create a `codeguard.json` file in your project root. See Configuration section above.
-
-### "API key not configured"
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `codeguard.json not found` | Missing config file | Create it in the project root |
+| `API key not configured` | Missing key | Add to `codeguard.json` or set env var |
+| `Not a git repository` | `auto`/`test`/`review` require git | Run `git init` |
+| `No changes detected` | No staged/unstaged source changes | Check `git status` and `git diff` |
+| `No exported functions changed` | Only internal functions modified | Ensure the changed function is exported |
+| `Missing required packages` | Babel not installed | `npm install --save-dev @babel/parser @babel/traverse` |
 
-Ensure your `codeguard.json` has the correct API key for your selected provider:
+More troubleshooting: [docs/CONFIGURATION.md#troubleshooting](docs/CONFIGURATION.md#troubleshooting)
 
-```json
-{
-  "aiProvider": "claude",
-  "apiKeys": {
-    "claude": "sk-ant-..."
-  }
-}
-```
-
-### Tests fail with import errors
-
-The tool automatically detects and fixes import path errors. If issues persist:
-1. Check that all dependencies are installed
-2. Verify your project structure matches expected paths
-3. Ensure TypeScript is configured correctly
-
-### "Missing required packages"
-
-Install Babel dependencies:
-
-```bash
-npm install --save-dev @babel/parser @babel/traverse
-```
-
-## Programmatic Usage
-
-You can also use CodeGuard as a library:
-
-```typescript
-import { generateTests, analyzeFileAST } from 'codeguard-testgen';
-
-// Generate tests for a file
-await generateTests('src/services/user.service.ts');
-
-// Analyze a file's AST
-const analysis = analyzeFileAST('src/utils/helpers.ts');
-console.log(analysis.functions);
-```
-
-## Project Structure
-
-After installation, your project will have:
-
-```
-your-project/
-├── codeguard.json          # Configuration file
-├── src/
-│   ├── services/
-│   │   └── user.service.ts
-│   └── tests/              # Generated tests
-│       └── services/
-│           └── user.service.test.ts
-├── reviews/                # AI code reviews
-│   └── user.service.review.md
-└── .codeguard-cache/       # Optional index cache
-```
+---
 
 ## Requirements
 
 - Node.js >= 16.0.0
-- Jest (for running generated tests)
-- TypeScript (for TypeScript projects)
+- Git (for `auto`, `review`, `test` commands)
+- `@babel/parser` and `@babel/traverse` in the target project
+- Vitest or Jest (for running generated tests)
+
+---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).
 
-## Contributing
+## Author
+
+[Ekansh Gahlot](https://github.com/Ekansh-Gahlot)
 
-Contributions welcome! Please open an issue or submit a pull request.
+## Contributing
 
-## Support
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
 
-For issues, questions, or feature requests, please open an issue on GitHub.
+## Issues
 
+[github.com/Ekansh-Gahlot/codeguard-testgen/issues](https://github.com/Ekansh-Gahlot/codeguard-testgen/issues)