Metadata-Version: 2.4
Name: apex-ray
Version: 0.1.12
Summary: Local CLI-first AI code review for git diffs with analyzer-backed context.
Project-URL: Homepage, https://dobrotacreator.github.io/apex-ray/
Project-URL: Documentation, https://dobrotacreator.github.io/apex-ray/
Project-URL: Repository, https://github.com/dobrotacreator/apex-ray
Project-URL: Issues, https://github.com/dobrotacreator/apex-ray/issues
Project-URL: Changelog, https://github.com/dobrotacreator/apex-ray/blob/main/CHANGELOG.md
Author: Apex Ray contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,code-analysis,code-review,git-diff,go,javascript,llm,local-first,python,static-analysis,typescript
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Go
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.14
Requires-Dist: pydantic>=2.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.26.2
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/apex-ray-logo-animated.svg" alt="Apex Ray logo animation" width="240">
</p>

# Apex Ray

[![CI](https://github.com/dobrotacreator/apex-ray/actions/workflows/ci.yml/badge.svg)](https://github.com/dobrotacreator/apex-ray/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0ea5e9.svg)](https://dobrotacreator.github.io/apex-ray/)
[![PyPI](https://img.shields.io/pypi/v/apex-ray.svg)](https://pypi.org/project/apex-ray/)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://github.com/dobrotacreator/apex-ray/blob/main/pyproject.toml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Local CLI-first AI code review for git diffs with analyzer-backed context.

Full documentation: [dobrotacreator.github.io/apex-ray](https://dobrotacreator.github.io/apex-ray/)

Apex Ray reads a git diff, builds compact context packs around changed code,
runs optional specialist LLM review through local CLIs or direct APIs,
verifies findings, and writes Markdown, JSON, HTML, and SARIF reports. It can
run locally or in GitHub Actions without depending on a hosted PR-review
product.

> Apex Ray is pre-1.0. Report schemas and configuration can change while the project is prepared for production use.

## Install

One-off run without a persistent install:

```bash
uvx apex-ray --help
uvx apex-ray doctor
```

User-level CLI install:

```bash
uv tool install apex-ray
apex-ray --version
apex-ray doctor
```

`pipx install apex-ray` is also supported if you use pipx for isolated Python CLI tools.

## Quick Start

In a project you want to review:

```bash
apex-ray init
apex-ray doctor
git status --short
```

Inspect and commit the setup files before using the first worktree review for application changes.

If Apex Ray later warns that generated agent instructions are outdated, refresh only those managed artifacts with:

```bash
apex-ray init --refresh-agent-artifacts --dry-run
apex-ray init --refresh-agent-artifacts
```

Run a deterministic no-LLM review:

```bash
apex-ray review --worktree --no-llm --output .apex-ray/reports/review.md --json .apex-ray/reports/review.json
```

Run the configured LLM review:

```bash
apex-ray review --worktree --llm --output .apex-ray/reports/review.md --json .apex-ray/reports/review.json --html .apex-ray/reports/review.html
```

Review a branch against the configured base:

```bash
apex-ray review --base main --llm
```

Continue only unreviewed packs from a partial report:

```bash
apex-ray review --continue-from .apex-ray/reports/review.json --residual-priority p0 --llm
apex-ray review --continue-from .apex-ray/reports/review.json --only-pack '<pack-id>' --llm
```

Run the same gate that `apex-ray init` wires into pre-push:

```bash
apex-ray gate pre-push
```

The gate reviews `review.base...HEAD`, writes `.apex-ray/reports/pre-push.md` and `.apex-ray/reports/pre-push.json`, prints an agent-friendly blocking summary, and exits non-zero when the configured policy fails.

See the full [Quick Start](https://dobrotacreator.github.io/apex-ray/quickstart/) and [Review Workflow](https://dobrotacreator.github.io/apex-ray/review-workflow/) docs for installation requirements, provider setup, report interpretation, continuation commands, cache behavior, and troubleshooting.

## What It Does

- Builds context packs from changed files, symbols, callers, callees, contracts, metadata, and related tests.
- Runs a language-neutral diff -> context pack -> optional LLM review workflow.
- Uses enhanced analyzers for TypeScript/JavaScript, Python, Go, and Dart/Flutter today, with Rust planned next.
- Supports project-specific rules and repo-committed review memory.
- Runs without LLM calls, with Codex CLI / Claude Code CLI subscriptions, or
  with OpenAI, Anthropic, DeepSeek, Qwen, Kimi, Z.ai, and custom compatible
  APIs.
- Supports project risk policies and independent correctness, security,
  financial, UX, or other focused reviewers with separate scope, model
  routing, depth, verification, and budgets.
- Runs reviewer matrices in GitHub Actions and emits SARIF/code-scanning,
  step-summary, and downloadable report artifacts.
- Routes cheap and strong models through profiles.
- Tracks LLM coverage, skipped packs, partial severity, provider failures, cache usage, and continuation commands.
- Replays historical GitHub PR review comments for local evals.
- Writes local telemetry so teams can tune cost, latency, and coverage over time.

## Analyzer Coverage

Apex Ray's review pipeline is language-neutral. It is strongest where an analyzer backend can build repository-aware context instead of relying only on diff hunks.

| Status | Language family | Strongest current surfaces |
| --- | --- | --- |
| Enhanced analyzer available | TypeScript, JavaScript | NestJS controllers/providers/modules/guards, DTO/schema validators, route and DI metadata, workspace imports/exports, enum/const fanout, cache and permission surfaces, related tests. |
| Enhanced analyzer available | Python | FastAPI routes/dependencies, Pydantic models/settings/validators, SQLAlchemy sessions/transactions, Alembic migrations, async worker/event flows, external HTTP/cloud/Redis adapters, dataclass/TypedDict/Protocol contracts, pytest/unittest tests and fixtures. |
| Enhanced analyzer available | Go | Type-aware package loading, repository-relative symbols, changed and deleted symbol ranges, callers/callees, interface contracts, context metadata, syntax-only fallback, and related tests. |
| Enhanced analyzer available | Dart, Flutter | Dart Analysis Server symbols, references, call/type relationships, parts and local packages, related tests, bounded Flutter framework metadata, generated-code suppression, and exact literal platform-channel contracts. |
| Enhanced analyzer planned | Rust | Repository-aware symbols, callers/callees, contracts, service boundaries, persistence/I/O surfaces, and related tests. |
| Generic fallback | Other reviewable diffs | Diff-hunk context, risk signals, project rules, memory, reports, and optional LLM review without a repository-aware symbol graph. |

## What It Does Not Do

Apex Ray does not replace CI, tests, linters, typecheck, dependency scanners, SAST, or human review. It focuses on diff-aware behavioral review and makes partial coverage explicit.

## Documentation

- [Quick Start](https://dobrotacreator.github.io/apex-ray/quickstart/)
- [Review Workflow](https://dobrotacreator.github.io/apex-ray/review-workflow/)
- [Configuration](https://dobrotacreator.github.io/apex-ray/configuration/)
- [LLM Providers](https://dobrotacreator.github.io/apex-ray/providers/)
- [Rules And Memory](https://dobrotacreator.github.io/apex-ray/memory/)
- [Telemetry](https://dobrotacreator.github.io/apex-ray/telemetry/)
- [Historical PR Replay Evals](https://dobrotacreator.github.io/apex-ray/pr-eval/)
- [Architecture](https://dobrotacreator.github.io/apex-ray/architecture/)
- [Development](https://dobrotacreator.github.io/apex-ray/development/)

## Development

For local development from source:

```bash
git clone git@github.com:dobrotacreator/apex-ray.git
cd apex-ray
uv sync --all-groups
npm --prefix analyzer-runtimes/typescript ci
npm --prefix analyzer-runtimes/typescript run build
```

Useful checks:

```bash
uv run coverage run -m pytest -q
uv run coverage report -m
npm --prefix analyzer-runtimes/typescript run typecheck
npm --prefix analyzer-runtimes/typescript test
npm --prefix analyzer-runtimes/typescript run coverage
git diff --check
```

See [docs/development.md](docs/development.md) and [CONTRIBUTING.md](CONTRIBUTING.md).

Maintainers: release automation is documented in [docs/development.md](docs/development.md#release-hygiene).

## License

Apache-2.0. See [LICENSE](LICENSE).
