Metadata-Version: 2.4
Name: apex-ray
Version: 0.1.5
Summary: Local CLI-first AI code review for TypeScript and JavaScript projects.
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-review,javascript,llm,typescript
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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 TypeScript and JavaScript projects.

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 LLM review through a local CLI provider, verifies findings, and writes Markdown, JSON, and HTML reports. It is designed for teams that want review intelligence locally, 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.

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 'apps/api/src/payments.ts#capture:1' --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 TS/JS context packs from changed files, symbols, callers, callees, contracts, metadata, and related tests.
- Supports project-specific rules and repo-committed review memory.
- Runs without LLM calls, or with Codex CLI / Claude Code CLI when configured.
- 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.

## 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 analyzers/typescript ci
npm --prefix analyzers/typescript run build
```

Useful checks:

```bash
uv run coverage run -m pytest -q
uv run coverage report -m
npm --prefix analyzers/typescript run typecheck
npm --prefix analyzers/typescript test
npm --prefix analyzers/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).
