PHPackages                             raffaelecarelle/ai-code-review-bot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. raffaelecarelle/ai-code-review-bot

ActiveLibrary[Utility & Helpers](/categories/utility)

raffaelecarelle/ai-code-review-bot
==================================

Minimal, extensible AI code review tool

1.0.0(7mo ago)301PHPPHP >=8.1CI passing

Since Sep 18Pushed 7mo agoCompare

[ Source](https://github.com/raffaelecarelle/ai-code-review-bot)[ Packagist](https://packagist.org/packages/raffaelecarelle/ai-code-review-bot)[ RSS](/packages/raffaelecarelle-ai-code-review-bot/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (10)Versions (2)Used By (0)

 [![AI Code Review Bot](logo.png)](logo.png)

AI Code Review Bot
==================

[](#ai-code-review-bot)

[![CI](https://github.com/raffaelecarelle/ai-code-review-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/raffaelecarelle/ai-code-review-bot/actions/workflows/ci.yml)

Minimal, extensible AI-assisted code review tool for PHP projects.

- Analyzes unified diffs (from Pull/Merge Requests or files)
- Produces normalized findings (machine-readable JSON or human summary)
- Loads a simple YAML/JSON config with provider/policy settings and an optional coding guidelines file
- Safe defaults: deterministic Mock AI provider; no network calls unless configured

Official documentation: [Docs](https://raffaelecarelle.github.io/ai-code-review-bot/)

---

Table of Contents
-----------------

[](#table-of-contents)

- 1. Objectives and scope
- 2. Architecture and main modules
- 3. Quick start
- 4. Configuration (.aicodereview.yml)
- 5. VCS adapters (GitHub/GitLab)
- 6. Coding guidelines file
- 7. AI providers and token budgeting
- 8. Security & Performance
- 9. Output formats
- 10. Development and QA
- 11. Credits
- 12. License

---

1. Objectives and scope
-----------------------

[](#1-objectives-and-scope)

- Functional
    - Analyze diffs and produce review findings for coding standard violations and simple risk patterns.
    - Dynamic configuration for providers, policy, token budget, rules, and VCS.
    - Post results back to PR/MR via platform adapters when requested.
- Non-functional
    - Safe defaults: no external calls by default (mock provider) and no PR comments unless `--comment`.
    - Modular design to plug real LLM providers and VCS platforms.

2. Architecture and main modules (PHP)
--------------------------------------

[](#2-architecture-and-main-modules-php)

- `bin/aicr`: CLI entry point (Symfony Console) running the review command in single-command mode.
- `src/Command/ReviewCommand.php`: Orchestrates reading config, loading diff (from file or git), running Pipeline, and optional PR/MR commenting. Uses Symfony Process for git.
- `src/Config.php`: Loads YAML/JSON config, merges with defaults, expands `${ENV}` variables, exposes sections (providers, context, policy, vcs, prompts).
- `src/DiffParser.php`: Minimal unified diff parser returning added lines per file with accurate line numbers.
- `src/Pipeline.php`: End-to-end pipeline: parse diff, build AI provider, chunk with token budget, apply policy, and render output.
- `src/Adapters/`: VcsAdapter interface and GithubAdapter/GitlabAdapter/BitbucketAdapter implementations (resolve branches from PR/MR id and post comments).
- `src/Providers/`: AIProvider interface and concrete providers (OpenAI, Gemini, Anthropic, Ollama, Mock).
- `src/Support/`: Core utility classes for enhanced functionality:
    - `ChunkBuilder`: Intelligent diff chunking with semantic analysis and optimization
    - `TokenBudget`: Advanced token management with compression and per-file caps
    - `ResourceManager`: Safe resource handling with automatic cleanup
    - `ApiCache`: Response caching with TTL and size management
    - `InputSanitizer`: Security-focused input validation and sanitization
    - `DiffProcessor`: Enhanced diff processing with filtering capabilities
    - `SemanticChunker`: Context-aware code chunking for better AI analysis
- `src/Config/Constants`: Centralized configuration constants replacing magic numbers and strings.

3. Quick start
--------------

[](#3-quick-start)

- Install dependencies via Composer:

```
composer install
```

- Option A: Analyze an existing diff file
    - Create or use a unified diff, e.g., `examples/sample.diff`.
    - Run:

```
php bin/aicr review --diff-file examples/sample.diff --output summary
php bin/aicr review --diff-file examples/sample.diff --output json
php bin/aicr review --diff-file examples/sample.diff --output summary --provider openai
```

- Option B: Analyze a PR/MR by ID using git
    - Configure `vcs.platform` in `.aicodereview.yml` (github or gitlab) and set required identifiers/tokens.
    - Then run (the command fetches branches, computes diff, and analyzes it):

```
php bin/aicr review --id 123 --output summary
php bin/aicr review --id 123 --output summary --provider gemini
```

- To also post a comment back to the PR/MR, add `--comment`:

```
php bin/aicr review --id 123 --output summary --comment
php bin/aicr review --id 123 --output summary --comment --provider anthropic
```

Notes

- Provide `--config ` to use a non-default config file.
- Use `--provider ` to override the default provider from config (e.g., openai, gemini, anthropic, ollama, mock).
- Without `--diff-file`, `--id` is required and branches are resolved via the configured adapter.

4. Configuration (.aicodereview.yml)
------------------------------------

[](#4-configuration-aicodereviewyml)

Example (see `.aicodereview.yml` in this repo and `examples/config.*.yml`):

```
version: 1
providers:
  # Safe deterministic provider by default
  default: mock
context:
  diff_token_limit: 8000
  overflow_strategy: trim
  per_file_token_cap: 2000
  enable_semantic_chunking: true
  enable_diff_compression: true
policy:
  min_severity_to_comment: info
  max_comments: 50
  redact_secrets: true
  consolidate_similar_findings: true
  max_findings_per_file: 5
  severity_limits:
    error: 10
    warning: 10
    info: 5
guidelines_file: null
vcs:
  # Set one of: github | gitlab | bitbucket
  platform: null
  # GitHub: owner/repo (optional if GH_REPO env or remote origin is GitHub)
  repo: null
  # GitLab: numeric id or full path namespace/repo (optional if GL_PROJECT_ID or remote origin is GitLab)
  project_id: null
  # GitLab: override API base for self-hosted instances (e.g., https://gitlab.example.com/api/v4)
  api_base: null
  # Bitbucket: workspace name (required for Bitbucket)
  workspace: null
  # Bitbucket: repository name (required for Bitbucket)
  repository: null
  # Bitbucket: access token for authentication (required for Bitbucket)
  accessToken: null
  # Bitbucket: API request timeout in seconds (optional, defaults to 30)
  timeout: 30
prompts:
  # Optional: append additional instructions to the base prompts used by the LLM
  # You can use single strings or lists of strings
  system_append: "Prefer concise findings and avoid duplicates."
  user_append:
    - "Prioritize security and performance related issues."
  extra:
    - "If a secret or key is detected, suggest redaction."
excludes:
  # Array of paths to exclude from code review
  # Each element is treated as glob, regex, or relative path from project root
  # Examples:
  - "*.md"           # Exclude all markdown files (glob)
  - "composer.lock"  # Exclude specific files (exact match)
  - "tests/*.php"    # Exclude files in specific directories with patterns (glob)
  - "vendor"         # Exclude entire vendor directory (directory)
  - "node_modules"   # Exclude node_modules directory (directory)
  - "build"          # Exclude build artifacts (directory)
  - "dist"           # Exclude distribution files (directory)
```

Notes

- Env var expansion works in any string value: `${VAR_NAME}`.
- Tokens/ids read from env if not set: `GH_TOKEN`/`GITHUB_TOKEN`, `GL_TOKEN`/`GITLAB_TOKEN`, `GH_REPO`, `GL_PROJECT_ID`.

5. VCS adapters (GitHub/GitLab/Bitbucket)
-----------------------------------------

[](#5-vcs-adapters-githubgitlabbitbucket)

- Configure `vcs.platform` and required parameters as needed.
- The review command supports a single `--id` option (PR number for GitHub, MR IID for GitLab, PR ID for Bitbucket).
- Behavior when `--diff-file` is omitted:
    1. Resolve base/head branches from the ID via platform API.
    2. `git fetch --all`; fetch base/head; compute `git diff base...head`.
    3. Run the analysis pipeline on that diff.
- `--comment` posts the summary back via the adapter.

6. Coding guidelines file
-------------------------

[](#6-coding-guidelines-file)

- You can provide a project coding standard or style guide via `guidelines_file` in `.aicodereview.yml`.
- When set, its content is embedded into the LLM prompts as a base64 string. The prompt explicitly instructs the model to base64-decode the guidelines and follow them strictly during the review.
- No provider-specific file uploads are performed: all supported providers (OpenAI, Gemini, Anthropic, Ollama) receive the same base64-embedded guidelines in the prompt.

7. AI providers and token budgeting
-----------------------------------

[](#7-ai-providers-and-token-budgeting)

- Supported providers in this repository: `openai`, `gemini`, `anthropic`, `ollama`, `mock`.
- Select via `providers.default` and configure each provider section accordingly (see `src/Providers/*` for options).
- Token budgeting is approximate (chars/4). Global and per-file caps are configurable; `overflow_strategy` defaults to `trim`.

### 7.1 Advanced Token Optimization Features

[](#71-advanced-token-optimization-features)

The system includes sophisticated token cost optimization capabilities:

- **Semantic Chunking**: Enable with `enable_semantic_chunking: true` to group related code changes by context (classes, methods, etc.)
- **Diff Compression**: Enable with `enable_diff_compression: true` to intelligently compress diffs while maintaining semantic meaning
- **Trivial Change Filtering**: Automatically filters out whitespace-only changes, TODO comments, and import statements
- **Similar Finding Consolidation**: Set `consolidate_similar_findings: true` to aggregate similar issues across multiple files
- **Per-file Limits**: Control review scope with `max_findings_per_file` to prevent overwhelming output
- **Severity Limits**: Fine-tune output with `severity_limits` to cap the number of findings by severity level

These optimizations can reduce token usage by 30-50% for input and 40-60% for output while maintaining review quality. See `docs/token-cost-optimization.md` for detailed implementation guide.

8. Security & Performance
-----------------------------

[](#8-security--performance)

Introduces significant enhancements focusing on security hardening, performance optimization, and code quality improvements:

### Security Enhancements

[](#security-enhancements)

- **InputSanitizer**: Comprehensive input validation and sanitization for all external data
    - Branch name, repository name, and file path validation
    - API response sanitization to prevent injection attacks
    - URL and commit SHA validation with strict patterns
- **Resource Management**: Safe resource handling with automatic cleanup
    - Temporary file and directory management
    - Resource leak prevention with shutdown handlers
    - Exception-safe cleanup with try-finally patterns

### Performance Optimizations

[](#performance-optimizations)

- **Intelligent Chunking**: Enhanced ChunkBuilder with semantic analysis
    - Batch processing for better memory management
    - Parallel-friendly architecture for large diffs
    - Context-aware chunking for improved AI analysis
- **Advanced Token Management**: Improved TokenBudget with compression
    - Per-file token caps to prevent oversized chunks
    - Diff compression for large files
    - Smart budget allocation and overflow handling
- **API Response Caching**: New ApiCache system for improved performance
    - TTL-based caching with automatic expiration
    - Size-limited cache with LRU eviction
    - Request deduplication and response reuse

### Code Quality Improvements

[](#code-quality-improvements)

- **Constants Centralization**: All magic numbers and strings moved to Constants class
- **Enhanced Error Handling**: Standardized exception handling across all providers
- **Improved Documentation**: Comprehensive PHPDoc comments and inline documentation
- **Security Audit**: Fixed potential security issues identified in code review

### Configuration Enhancements

[](#configuration-enhancements)

New configuration options available:

```
context:
  enable_semantic_chunking: true    # Enable context-aware chunking
  enable_diff_compression: true     # Enable diff compression for large files
  cache_ttl: 3600                  # API response cache TTL in seconds
  max_cache_size: 52428800         # Maximum cache size in bytes (50MB)
```

9. Output formats
-----------------

[](#9-output-formats)

- `json` (default): machine-readable findings array.
- `summary`: human-readable bulleted list. This is also the format used for PR/MR comments.
- `markdown`: structured markdown format with emojis, metadata, and organized findings by severity and file.

9. Development and QA
---------------------

[](#9-development-and-qa)

- Requires PHP and Composer.
- Run unit and E2E tests with PHPUnit:

```
./vendor/bin/phpunit
```

- Coding standards and static analysis:

```
composer analyse
```

- The codebase uses `declare(strict_types=1)` and Symfony components (Console, YAML, Filesystem, Process).

10. Credits
-----------

[](#10-credits)

- Author: Raffaele Carelle
- Contributors: Thanks to everyone who reports issues or submits PRs.

11. License
-----------

[](#11-license)

This project is open-sourced under the MIT License. See the LICENSE file for details.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance62

Regular maintenance activity

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

236d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/470d7f2b64c268ccd0d73d1d19da604f5049ffdc717170df28ac460d34b8a327?d=identicon)[raffaelecarelle](/maintainers/raffaelecarelle)

---

Top Contributors

[![raffaelecarelle](https://avatars.githubusercontent.com/u/15015792?v=4)](https://github.com/raffaelecarelle "raffaelecarelle (95 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/raffaelecarelle-ai-code-review-bot/health.svg)

```
[![Health](https://phpackages.com/badges/raffaelecarelle-ai-code-review-bot/health.svg)](https://phpackages.com/packages/raffaelecarelle-ai-code-review-bot)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19462.3M1.3k](/packages/drupal-core)[silverstripe/framework

The SilverStripe framework

7213.5M2.5k](/packages/silverstripe-framework)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)