apex-ray 0.1.0__tar.gz

apex_ray-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+.venv/
+.ci-smoke-venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+.coverage
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.codegraph/
+.code-review-graph/
+.claude/settings.local.json
+.codex/config.local.toml
+.apex-ray/config.local.yml
+.apex-ray/cache/
+**/.apex-ray/cache/
+.apex-ray/telemetry/
+**/.apex-ray/telemetry/
+.apex-ray/eval/telemetry/
+**/.apex-ray/eval/telemetry/
+.apex-ray/eval/runs/
+**/.apex-ray/eval/runs/
+.apex-ray/evals/runs/
+**/.apex-ray/evals/runs/
+/review*.md
+/review*.json
+/review*.html
+/benchmark*.md
+/benchmark*.json
+analyzers/typescript/node_modules/
+analyzers/typescript/dist/
+analyzers/typescript/dist-test/

apex_ray-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## 0.1.0 (2026-05-31)
+
+
+### ⚠ BREAKING CHANGES
+
+* prepare Apex Ray for production readiness ([#10](https://github.com/dobrotacreator/apex-ray/issues/10))
+* reset the pre-release public history to a sanitized production baseline before wider use.
+
+### Features
+
+* release Apex Ray local review engine ([1105a4f](https://github.com/dobrotacreator/apex-ray/commit/1105a4f444c0399058af723fb911993f43d6b34a))
+
+
+### Refactoring
+
+* prepare Apex Ray for production readiness ([#10](https://github.com/dobrotacreator/apex-ray/issues/10)) ([6c7cde6](https://github.com/dobrotacreator/apex-ray/commit/6c7cde6b85b6a2e3b8ad699dc2f5e35dadb84e99))
+
+
+### Documentation
+
+* add animated project logo ([2911320](https://github.com/dobrotacreator/apex-ray/commit/291132084b849851589429d7bc5da881b0034581))
+* refresh logo assets ([#9](https://github.com/dobrotacreator/apex-ray/issues/9)) ([98932a5](https://github.com/dobrotacreator/apex-ray/commit/98932a5b25d24a99a7ac02328b67ba5e79123a78))
+
+
+### Infrastructure
+
+* **release:** add Release Please automation ([#11](https://github.com/dobrotacreator/apex-ray/issues/11)) ([8361715](https://github.com/dobrotacreator/apex-ray/commit/8361715de97654b446d7e693ec0954167fc036ee))
+
+## Changelog
+
+All notable changes to Apex Ray will be documented here.
+
+The format follows Keep a Changelog style categories and uses Conventional Commits for commit history.
+
+## Unreleased
+
+### Added
+
+- Local TS/JS code-review reports with optional LLM review and verifier passes.
+- Context-pack coverage summaries, continuation flows, and local review telemetry.
+- Historical PR replay evaluation utilities for comparing Apex Ray against prior review comments.
+
+### Changed
+
+- Pre-1.0 report schemas may change while the tool is prepared for production use.

apex_ray-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thanks for improving Apex Ray. This project is still pre-1.0, so breaking changes are allowed when they materially improve review quality, local usability, or release safety.
+
+## Development Setup
+
+Prerequisites:
+
+- Python 3.14+
+- Node.js 24+
+- npm
+- uv
+- git
+
+Install dependencies and build the TypeScript analyzer:
+
+```bash
+uv sync --all-groups
+npm --prefix analyzers/typescript ci
+npm --prefix analyzers/typescript run build
+```
+
+Run the main checks from the repository root:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run pyright
+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
+uv build --sdist --wheel
+uv run twine check dist/*
+git diff --check
+```
+
+## Git Flow
+
+- Work on feature branches.
+- Keep `main` releasable.
+- Merge through pull requests after CI passes.
+- Do not publish or tag from a dirty worktree.
+- Do not commit generated review reports, local telemetry, caches, or `.apex-ray/config.local.yml`.
+- Keep shared `.apex-ray/config.yml` focused on team policy; use `.apex-ray/config.local.yml` for personal provider/model/cost settings.
+
+## Commit Messages
+
+Use Conventional Commits:
+
+```text
+feat(llm): add Claude Code CLI provider
+fix(report): preserve failed pack status in coverage
+docs: rewrite quickstart
+chore(ci): add wheel install smoke
+feat!: change review report schema
+```
+
+Allowed commit types are `feat`, `fix`, `refactor`, `test`, `docs`, `infra`, `adr`, `migration`, and `chore`.
+
+Use `!` and a `BREAKING CHANGE:` footer for behavior or schema changes that can affect users, automation, or stored reports.
+
+## Pull Requests
+
+Good pull requests include:
+
+- A clear summary of user-visible behavior.
+- Focused tests for the changed behavior.
+- Fresh verification commands and results.
+- Notes for breaking changes, migration steps, or follow-up work.
+
+For review-quality changes, prefer executable fixtures or historical PR replay evidence over anecdotal prompt tuning.
+
+## Release Notes
+
+Do not manually bump `pyproject.toml` or edit release sections in `CHANGELOG.md` for normal releases. Release Please reads Conventional Commits on `main`, opens a release PR, updates `pyproject.toml`, updates `CHANGELOG.md`, and creates the release tag after that PR is merged.
+
+Use clear commit types and scopes so generated release notes are useful. See [docs/development.md](docs/development.md#release-hygiene) for maintainer release flow details.

apex_ray-0.1.0/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but not
+limited to compiled object code, generated documentation, and
+conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the
+original version of the Work and any modifications or additions to
+that Work or Derivative Works thereof, that is intentionally submitted
+to Licensor for inclusion in the Work by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the
+copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative
+Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work, excluding
+those notices that do not pertain to any part of the Derivative
+Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices
+within Derivative Works that You distribute, alongside or as an
+addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying
+the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this
+License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer, and
+charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Apex Ray contributors

apex_ray-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: apex-ray
+Version: 0.1.0
+Summary: Local CLI-first AI code review for TypeScript and JavaScript projects.
+Project-URL: Homepage, https://github.com/dobrotacreator/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)
+[![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.
+
+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/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.
+
+## 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.
+
+## Requirements
+
+- Python 3.14+
+- Node.js 24+
+- npm
+- git
+- uv for development
+- Codex CLI or Claude Code CLI for LLM review
+- GitHub CLI only for historical PR capture/eval commands
+
+## Install
+
+For published releases:
+
+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.
+
+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
+```
+
+Run from the repository root:
+
+```bash
+uv run apex-ray --version
+uv run apex-ray doctor
+```
+
+The shorter `apex-ray ...` commands below assume the console script is installed on your `PATH`. When working from a source checkout, either prefix commands with `uv run` or install the local checkout as an editable user tool:
+
+```bash
+uv tool install --editable .
+apex-ray doctor
+```
+
+## Quickstart
+
+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.
+
+`apex-ray init` creates `.apex-ray/config.yml`, rules/memory/report directories, gitignore entries, brief agent instruction pointers, project-local Apex Ray skills (`$apex-ray` and `$apex-ray-improve`), and a Lefthook pre-push gate command that follows shared and local config. Use `--hooks none`, `--agent-files none`, or `--no-agent-skill` for exceptional repositories.
+
+After the setup commit, run a deterministic local 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 explicitly:
+
+```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.
+
+## Configuration
+
+Project configuration lives in `.apex-ray/config.yml`:
+
+```yaml
+review:
+  base: main
+  ignore:
+    - "**/*.lock"
+    - "**/generated/**"
+  rule_paths:
+    - .apex-ray/rules
+  memory:
+    enabled: true
+    paths:
+      - .apex-ray/memory
+  llm:
+    enabled: true
+    provider: codex_cli
+    coverage_mode: balanced
+    max_packs: 64
+    max_deep_packs: 48
+    max_input_tokens: 300000
+    verify: true
+  telemetry:
+    enabled: false
+    path: .apex-ray/telemetry/review-runs.jsonl
+  gates:
+    pre_push:
+      enabled: true
+      min_finding_severity: high
+      require_verified_findings: true
+      fail_on_quality_gate: true
+      fail_on_partial_severity: critical
+```
+
+Machine-specific overrides can live in `.apex-ray/config.local.yml`. Apex Ray merges built-in defaults, shared config, local config, and CLI flags in that order. Local config is gitignored by default and is intended for provider/model/cost differences between contributors.
+
+See [docs/configuration.md](docs/configuration.md) for configuration details.
+
+## Rules And Memory
+
+Rules are Markdown files with YAML frontmatter under `.apex-ray/rules/`. They are matched to context packs and injected only when relevant.
+
+Memory cards are Markdown files under `.apex-ray/memory/`. They keep concise team learning, false-positive calibration, and domain review hints close to the codebase.
+
+See [docs/memory.md](docs/memory.md) for memory-card details.
+
+## LLM Providers
+
+Apex Ray supports Codex CLI and Claude Code CLI. Profiles let a project combine cheaper broad review with stronger verification/escalation, including mixed providers:
+
+```yaml
+review:
+  llm:
+    profiles:
+      cheap:
+        provider: codex_cli
+        model: "<cheap-codex-model>"
+      strong:
+        provider: claude_code_cli
+        model: "<strong-claude-model-or-alias>"
+    routing:
+      review_profile: cheap
+      verify_profile: strong
+      escalated_review_profile: strong
+      escalate_review_when:
+        risk: [auth, external_io, persistence]
+        rule_severity: [high, critical]
+        strict_rule: true
+        pack_truncated: true
+```
+
+Avoid near-sunset model IDs in shared defaults. Team members can use `.apex-ray/config.local.yml` for personal provider/model/path/cost overrides.
+
+See [docs/providers.md](docs/providers.md).
+
+## Architecture
+
+For a high-level implementation map, review flow, init artifacts, telemetry/eval flow, and test fixture explanation, see [docs/architecture.md](docs/architecture.md).
+
+## Coverage And Continuation
+
+LLM coverage modes:
+
+- `fast`: capped deep review.
+- `balanced`: deep review for high-value packs plus shallow breadth under token budget.
+- `exhaustive`: review every reviewable pack when budget allows.
+
+Reports include reviewed/unreviewed pack IDs, partial severity, residual P0/P1 packs, skipped reasons, provider failures, cache metrics, and suggested continuation commands.
+
+## Telemetry
+
+Local review telemetry is append-only JSONL. It is intended for tuning cost, latency, model routing, and coverage:
+
+```bash
+apex-ray review --worktree --llm --telemetry
+apex-ray telemetry-summary --telemetry-path .apex-ray/telemetry/review-runs.jsonl
+```
+
+Telemetry is measurement-only and is not injected into review prompts automatically. See [docs/telemetry.md](docs/telemetry.md).
+
+## Historical PR Evals
+
+Apex Ray can capture prior GitHub PR comments and replay local review on historical diffs:
+
+```bash
+apex-ray eval capture-prs --repo /path/to/project --output /path/to/project/.apex-ray/evals/cases --limit 10
+apex-ray eval run-prs --repo /path/to/project --cases /path/to/project/.apex-ray/evals/cases --output /path/to/project/.apex-ray/evals/runs/latest --llm
+```
+
+See [docs/pr-eval.md](docs/pr-eval.md).
+
+## Privacy
+
+When LLM review is enabled, Apex Ray sends selected diff and context-pack content to the configured local CLI provider. Review that provider's privacy and retention policy before using Apex Ray on private code.
+
+Caches and telemetry are local files. They may include repository paths, model names, finding counts, coverage metadata, and token estimates. Keep them ignored unless a team intentionally curates a shared artifact.
+
+## Development
+
+```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).