From 7a80156cc23c530db7be0d322e081afa468ee7ad Mon Sep 17 00:00:00 2001 From: Diego Maroto Date: Sun, 5 Jan 2025 18:02:08 +0100 Subject: [PATCH] Readme --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 107 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 9a86716..cb0f8be 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # AI Pull Request Analysis -A GitHub Action powered by Anthropic's Claude AI that provides intelligent analysis and review of pull requests. +A powerful tool for automated code review powered by Anthropic's Claude AI. Available both as a GitHub Action and as an NPM package for CLI usage. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![NPM Version](https://img.shields.io/npm/v/@diekotto/ai-pull-review-cli.svg)](https://www.npmjs.com/package/@diekotto/ai-pull-review-cli) +[![Node Version](https://img.shields.io/node/v/@diekotto/ai-pull-review-cli.svg)](https://www.npmjs.com/package/@diekotto/ai-pull-review-cli) ## Features @@ -12,16 +14,21 @@ A GitHub Action powered by Anthropic's Claude AI that provides intelligent analy - Documentation assessment - Performance impact analysis - Security best practices verification -- Actionable feedback in PR comments +- Cost estimation and tracking +- Flexible file filtering +- Supports multiple analysis levels +- Available as both GitHub Action and CLI tool -## Getting Started +## Usage Options -### Prerequisites +### 1. GitHub Action + +#### Prerequisites 1. Anthropic API key (obtain from [Anthropic's website](https://anthropic.com)) 2. GitHub repository with pull request workflows enabled -### Installation +#### Installation 1. Create `.github/workflows/pr-analysis.yml`: @@ -41,7 +48,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: AI Pull Request Analysis - uses: diekotto/ai-pull-review@v1 + uses: diekotto/ai-pull-review@v2 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} @@ -52,35 +59,97 @@ jobs: - Create new secret: `ANTHROPIC_API_KEY` - Add your API key as the value +### 2. CLI Usage + +The tool is also available as an NPM package for command-line usage. + +#### Installation + +```bash +# Global installation +npm install -g @diekotto/ai-pull-review-cli + +# Or run directly with npx +npx @diekotto/ai-pull-review-cli +``` + +#### CLI Options + +```bash +Usage: ai-pull-review-cli [options] + +Options: + -V, --version output the version number + -p, --pr Pull request number (required) + -r, --repo Repository (required) + -t, --token GitHub token (default: GITHUB_TOKEN env) + -k, --key Anthropic API key (default: ANTHROPIC_API_KEY env) + -l, --level Analysis level (basic, standard, deep) (default: "basic") + -m, --model Claude model to use (default: "claude-3-5-haiku-20241022") + --file-patterns File patterns to include (comma-separated) + --exclude-patterns File patterns to exclude (default: "**/node_modules/**, **/dist/**, **/build/**, **/bin/**, **/artifacts/**") + --max-files Maximum files to analyze (default: "10") + --max-size Maximum file size in KB (default: "100") + --threshold Comment confidence threshold (default: "0.6") + --write-pull-request Write the analysis to the pull request as a comment + -o, --output Output folder for results (default: "results") + -h, --help display help for command +``` + +#### Example Usage + +```bash +# Using environment variables +export GITHUB_TOKEN=your_github_token +export ANTHROPIC_API_KEY=your_anthropic_key + +# Analyze a specific PR +ai-pull-review-cli -p 123 -r owner/repo -l deep + +# Or with npx +npx ai-pull-review-cli -p 123 -r owner/repo -l deep +``` + ## Configuration -Available options for your workflow file: +### Analysis Levels + +- `basic`: Quick analysis focusing on bugs and style issues +- `standard`: Comprehensive analysis including performance and security +- `deep`: In-depth analysis including architecture, testing, and broader implications + +### Available Models + +The tool supports various Claude models with different capabilities and pricing: + +- `claude-3-5-sonnet-20241022` (Default for accuracy) +- `claude-3-5-haiku-20241022` (Default for speed) +- `claude-3-opus-20240229` (Most capable) + +### GitHub Action Configuration + +Complete configuration options for your workflow file: ```yaml -- uses: diekotto/ai-pull-review@v1 +- uses: diekotto/ai-pull-review@v2 with: # Required anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} # Optional - file_patterns: '**/*.{js,jsx,ts,tsx,py,java,rb,go,rs}' # Default: Files to analyze - exclude_patterns: '**/node_modules/**,**/dist/**' # Default: Files to exclude - max_files: '10' # Default: Maximum files to analyze - comment_threshold: '0.7' # Default: Minimum confidence for comments - analysis_level: 'standard' # Default: basic, standard, or deep - model: 'claude-3-5-haiku-20241022' # Default: Claude model to use + file_patterns: '**/*.js,**/*.jsx,**/*.ts,**/*.tsx,**/*.py,**/*.java,**/*.rb,**/*.go,**/*.rs' # Files to analyze + exclude_patterns: '**/node_modules/**,**/dist/**,**/bin/**' # Files to exclude + max_files: '10' # Maximum files to analyze + max_size: '100' # Maximum file size in KB + comment_threshold: '0.7' # Minimum confidence for comments + analysis_level: 'basic' # basic, standard, or deep + model: 'claude-3-5-haiku-20241022' # Claude model to use ``` -### Analysis Levels - -- `basic`: Quick analysis of bugs and style issues -- `standard`: Comprehensive analysis including performance and security -- `deep`: In-depth analysis including architecture and testing - -### Example Configuration +### Advanced Example -Focused JavaScript analysis with deep inspection: +Configuration focusing on JavaScript analysis with deep inspection: ```yaml name: Deep JS Analysis @@ -102,7 +171,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: AI Pull Request Analysis - uses: diekotto/ai-pull-review@v1 + uses: diekotto/ai-pull-review@v2 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} @@ -111,17 +180,26 @@ jobs: analysis_level: 'deep' max_files: '15' comment_threshold: '0.6' + model: 'claude-3-5-sonnet-20241022' ``` -### Error Handling +## Error Handling and Limitations -The action will: +- Files exceeding size or complexity limits are automatically skipped +- Warnings are logged for problematic files +- Analysis continues with remaining files when encountering issues +- Detailed error reporting in GitHub Actions log +- Cost tracking and estimation for API usage -- Log warnings for problematic files -- Continue analyzing remaining files -- Report errors in the GitHub Actions log -- Skip files exceeding size/complexity limits +## Requirements + +- Node.js >= 22.0.0 +- NPM >= 10.0.0 ## License MIT License - see the [LICENSE](LICENSE) file for details. + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.